Type: Package
Title: Item Selection and Exhaustive Search for Rasch Models
Version: 0.3.7
Date: 2024-12-16
Description: Automation of the item selection processes for Rasch scales by means of exhaustive search for suitable Rasch models (dichotomous, partial credit, rating-scale) in a list of item-combinations. The item-combinations to test can be either all possible combinations or item-combinations can be defined by several rules (forced inclusion of specific items, exclusion of combinations, minimum/maximum items of a subset of items). Tests for model fit and item fit include ordering of the thresholds, item fit-indices, likelihood ratio test, Martin-Löf test, Wald-like test, person-item distribution, person separation index, principal components of Rasch residuals, empirical representation of all raw scores or Rasch trees for detecting differential item functioning. The tests, their ordering and their parameters can be defined by the user. For parameter estimation and model tests, functions of the packages 'eRm', 'psychotools' or 'pairwise' can be used.
License: GPL-3
Encoding: UTF-8
LazyData: true
Imports: eRm, psychotree, parallel, stats, utils, psych, tictoc, methods, psychotools, pairwise, arrangements, pbapply
Depends: R (≥ 3.5.0)
Suggests: knitr, rmarkdown, testthat (≥ 3.0.0)
Config/testthat/edition: 3
VignetteBuilder: knitr
RoxygenNote: 7.3.2
URL: https://github.com/chrgrebe/exhaustiveRasch
BugReports: https://github.com/chrgrebe/exhaustiveRasch/issues
NeedsCompilation: no
Packaged: 2024-12-16 21:25:53 UTC; Chris
Author: Christian Grebe ORCID iD [cre, aut], Mirko Schürmann ORCID iD [aut], Joerg-Henrik Heine [ctb], Patrick Mair [ctb], Thomas Rusch [ctb], Reinhold Hatzinger [ctb], Marco J. Maier [ctb], Rudolf Debelak [ctb]
Maintainer: Christian Grebe <grebe@hepcos.com>
Repository: CRAN
Date/Publication: 2024-12-17 10:30:02 UTC

Activities of Daily Living - dichotomous example data

Description

ADL date from N=591 nursing home residents from Germany

Usage

ADL

Format

Activities of Daily Living (V06-V39: 1= yes; 0= no):

Source

Data from Grebe (2013)

References

Grebe C (2013). Pflegeaufwand und Personalbemessung in der stationären Langzeitpflege: Entwicklung eines empirischen Fallgruppensystems auf der Basis von Bewohnercharakteristika. 3-Länder-Konferenz Pflege & Pflegewissenschaft, Konstanz.


InterprofessionalCollaboration - polytomous example data

Description

data for certainty of action measured with the Health Professionals Competence Scales (HePCoS-G). Dimension: interprofessional collaboration. sample: N=716 nurses, midwifes, occupational therapists, physiotherapists and speech therapists.

Usage

InterprofessionalCollaboration

Format

V01-V19: "How confident do you feel in the following situation?" (0= not confident; 1= hardly confident; 2= rather confident; 3=very confident)

Source

Data from the construction sample of the Health Professionals Competence Scales (HePCoS)

References

Grebe C, Schürmann M, Latteck, ÄD (2021). Die HePCoS-Skalen zur Kompetenzerfassung in den Gesundheitsfachberufen. Berichte aus Forschung und Lehre (48). Bielefeld, Fachhochschule Bielefeld. DOI: http://dx.doi.org/10.13140/RG.2.2.13480.08967/1


itemfit statistics for 'psychotools' Anderson's likelihood ratio test for 'psychotools'

Description

itemfit statistics for 'psychotools' Anderson's likelihood ratio test for 'psychotools'

Usage

LRtest.psy(model, modelType, splitcr = "median", splitseed = NULL)

Arguments

model

an object of 'psychotools' class 'raschmodel', 'pcmodel' or 'rsmodel' (a model previously fit using the 'psychotools' package) matching the value of modelType.

modelType

a character value defining the type of Rasch model. Possible values: "RM", "PCM", "RSM"

splitcr

Split criterion for subject raw score splitting for test_LR. "median" uses the median as split criterion, "mean" performs a mean split, "random" performs a random split (in this case, the seed can be set with the "splitseed" argument. splitcr can also be a vector which assigns each person to a certain subgroup (typically an external criterion). This vector can be numeric, character or a factor.

splitseed

seed for random split

Value

the p-value of the likelihood-ratio test.

Examples

 model <- psychotools::raschmodel(ADL[c(6,7,12,14,15)])
 LRtest.psy(model=model, modelType="RM", splitcr="random", splitseed=332)

adds information criteria to the @IC slot of an object of class passed_exRa-class

Description

adds information criteria to the @IC slot of an object of class passed_exRa-class

Usage

add_ICs(obj, ignoreCores = 1)

Arguments

obj

an object of class passed_exRa-class

ignoreCores

a numeric value for the number of virtual CPU cores (threads)to hold out in computing the information criteria.

Value

an object of passed_exRa-class.

Examples


  library(exhaustiveRasch)
  data(ADL)
  passed <- exhaustive_tests(dset= ADL[c(1:4,7,12,14)],
    modelType= "RM", scale_length= 5, alpha=0.05,
    tests=c("test_LR", "test_itemfit", "test_respca"),
    splitcr_LR = ADL[,17], itemfit_param =
      itemfit_control(use.pval=FALSE, upperMSQ=1.5, lowerMSQ=0.5),
    estimation_param= estimation_control(
      est="psychotools"), verbose=FALSE)
  passed <- add_ICs(passed)


checks if all possible raw scores occur in the data.

Description

checks if all possible raw scores occur in the data.

Usage

all_rawscores(
  items = NULL,
  dset = NULL,
  na.rm = TRUE,
  model = NULL,
  p.par = NULL,
  modelType = NULL,
  estimation_param = NULL
)

Arguments

items

a numeric vector containing the index numbers of the items in dset that are used to fit the model

dset

a data.frame containing the data

na.rm

a boolean value. If TRUE, all cases with any NA are removed (na.omit). If FALSE, only cases with full NA responses are removed

model

on object of a fit Rasch model, estimated with the packages 'eRm' (classes 'RM', 'PCM' or 'RSM'), 'psychotools' (classes raschmodel, 'pcmodel' or 'rsmodel') or 'pairwise' (class 'pers'), matching the value of modelType. If 'model' is provided, this model is used. If NULL, a model is fit using 'dset' and 'items'.

p.par

a person parameter object matching the class of 'model'. If NULL, the person parameters will be estimated.

modelType

a character value defining the rasch model to fit. Possible values: "RM", "PCM", "RSM".

estimation_param

options for parameter estimation using estimation_control

Value

if all possible raw scores occur in dset, a list containing 3 elements is returned: the item combination that was tested, a list of the class the model was estimated with (depending on modelType and estimation_param$est) with the fit model and a list with a person parameter object (depending on estimation_param$est). If at least one raw score does not occur in dset, NULL is returned.


selects item combinations based on defined rules

Description

selects item combinations based on defined rules

Usage

apply_combo_rules(
  full,
  combo_length = 4:length(full),
  forced_items = NULL,
  rules = NULL,
  ignoreCores = 1
)

Arguments

full

a numeric vector containing the the source for the combinations, typically the indices of the items in the referring dataset

combo_length

a numeric vector with the allowed lengths of the selected combinations (scale lengths)

forced_items

a numeric vector of items that are forced to occur in every selected combination

rules

a list defining rules for combination selection

ignoreCores

number of cpu cores (threads) to be ignored during parallized processing.

Value

a list of numeric vectors containing the selected item combinations that match the defined rules of forced_items and/or rules.

Examples

data(ADL)
forced <- c(1)
rules_object <- list() # rules-Object
rules_object[[1]] <- list("min", 1, 8:9)
rules_object[[2]] <- list("min", 1, 14:15)
rules_object[[3]] <- list("max", 2, 2:6)
rules_object[[4]] <- list("forbidden", c(8,9))
final_combos <- apply_combo_rules(combo_length = 5:7,
                                  full=1:length(ADL),
                                   forced_items = forced,
                                   rules= rules_object)

selects item combinations based on defined rules

Description

selects item combinations based on defined rules

Usage

check_combo_rules(full, rules = NULL)

Arguments

full

a numeric vector containing the the source for the combinations, typically the indices of the items in the referring dataset

rules

a list defining rules for combination selection

Value

a list of numeric vectors containing the selected item combinations that match the defined rules of forced_items and/or rules.


cognition - polytomous example data data measured with the FACT-cog (subscale perceived cognitive functioning) sample size: N=1009

Description

cognition - polytomous example data data measured with the FACT-cog (subscale perceived cognitive functioning) sample size: N=1009

Usage

cognition

Format

Items 1-20: FACT-cog Items. Questions starting with In the past 7 days... Answer categories: 0= never; 1= about once a week; 2= two to three times a week; 3=nearly every day; 4= several times a day

Source

Data for perceived cognitive functioning from the PROsetta Stone Wave 2 dataset.

References

Cella D (2017). PROsetta Stone Wave 2. Harvard Dataverse. DOI: 10.7910/DVN/WZVYZI.


options for item parameter estimation

Description

options for item parameter estimation

Usage

estimation_control(
  est = "psychotools",
  resp.cat = NULL,
  use.thurst = TRUE,
  splitseed = NULL
)

Arguments

est

a character value defining the estimation function to use. Possible values: 'psychotools', 'eRm', 'pairwise'.

resp.cat

number of response (answer) categories for all items. If not given, they will be calculated from the data, assuming that every response category is at least once present in the data. Currently only used for pairwise estimations (m parameter in 'pairwise::pair').

use.thurst

a boolean value defining whether thurstonian threshold parameters (TRUE, default) or Rasch-Andrich thresholds (step parameters) will be computed.

splitseed

a numeric value, the seed for random splits in test_waldtest, lest_LR (both only relevant for 'pairwise' or 'psychotools' estimations) and test_mloef (only 'psychotools' estimations)

Value

a list containing the options


(main function) Runs exhaustive tests

Description

(main function) Runs exhaustive tests

Usage

exhaustive_tests(
  dset,
  modelType = "PCM",
  combos = NULL,
  scale_length = 4:length(dset),
  na.rm = TRUE,
  tests = c("no_test"),
  splitcr_mloef = NULL,
  splitcr_LR = NULL,
  splitcr_wald = NULL,
  icat_wald = FALSE,
  alpha = 0.1,
  bonf = FALSE,
  DIFvars = NULL,
  gap_prop = 0,
  extremes = TRUE,
  max_contrast = NULL,
  PSI = 0.8,
  ICs = FALSE,
  keep = FALSE,
  ignoreCores = 1,
  verbose = TRUE,
  ...,
  itemfit_param = NULL,
  estimation_param = NULL
)

Arguments

dset

a data.frame containing the data

modelType

a character value defining the rasch model to fit. Possible values: RM, PCM, RSM

combos

either 1) a list of item combinations to be tested, e.g. from apply_combo_rules or the passed_combos slot of an object of passed_exRa-class from a previous call to this function. Or 2) an object of passed_exRa-class. In this case, the previously fit models froms its passed_Models slot will also be used and will be passed to the test functions. This will speed up the analysis. If the parameter is NULL, all possible combinations of the items (columns) in dset will be tested

scale_length

a numeric vector defining the length of the item combinations to test

na.rm

a boolean value. If TRUE, in the respective item combination all cases with any NA are removed (na.omit). If FALSE, only cases with full NA responses are removed. NOTE: test_mloef currently does not allow for missing values. If test_mloef is under the tests to perform, na.rm will automatically be set TRUE for ALL tests.

tests

a vector of characters defining the tests to perform. Possible values: all_rawscores, test_itemfit, test_LR, test_mloef, test_waldtest, threshold_order, test_DIFtree, test_personsItems, test_respca, test_PSI. Tests will be performed in the given order. test_mloef is not available for pairwise estimation, threshold_order is not available (and not meaningful) for dichotomous models.

splitcr_mloef

Split criterion to define the item groups for test_mloef. "median" and "mean" split items in two groups based on their items' raw scores median or mean. "random" (only for 'psychotools' estimation) performs a random split (in this case, the seed can be set with the "splitseed" argument of itemfit_control. splitcr_mloef can also be a vector of length k (where k denotes the number of items) that takes two or more distinct values to define groups used for the Martin-Löf Test.

splitcr_LR

Split criterion for subject raw score splitting for test_LR. "median" uses the median as split criterion, "mean" performs a mean split, "random" (only for 'psychotools' or 'pairwise' estimation) performs a random split (in this case, the seed can be set with the "splitseed" argument of itemfit_control. splitcr_LR can also be a vector which assigns each person to a certain subgroup (typically an external criterion). This vector can be numeric, character or a factor.

splitcr_wald

Split criterion for subject raw score splitting for test_waldtest. "median" uses the median as split criterion, "mean" performs a mean-split, "random" (only for 'psychotools' or 'pairwise' estimation) performs a random split (in this case, the seed can be set with the "splitseed" argument of itemfit_control. Optionally splitcr_wald can also be a dichotomous vector which assigns each person to a certain subgroup (e.g., following an external criterion). This vector can be numeric, character or a factor.

icat_wald

a boolean value indicating if the waldtest will be conducted on item level (TRUE, default value) or on item category level. This parameter only effects estimations using 'psychotools' or 'pairwise' and will be ignored for eRm estimations.

alpha

a numeric value for the alpha level. Will be ignored for test_itemfit if use.pval in itemfit_control is FALSE

bonf

a boolean value whether to use a Bonferroni correction. Will be ignored if use.pval is FALSE

DIFvars

a data.frame containing the variables and their data to use for differential item functioning analysis with test_DIFtree

gap_prop

a numeric value between 0 and 1 that sets the criterion for the minimum proportion of neighboring person parameters with an item/threshold location in between. If set to 0, this criterion will not be checked (used in test_personsItems only)

extremes

a boolean value indicating if a check for the item/threshold locations left of the 2nd lowest and right of the 2nd highest person parameter (used in test_personsItems only).

max_contrast

a numeric value defining the maximum loading of a factor in the principal components analysis of the standardised residuals. Only relevant, if test_respca is one of the tests.

PSI

a numeric value defining the minimum value for the person- separation-index (separation reliablility).

ICs

a boolean value defining whether to compute information criteria for the remaining models. You can add these later to the object of class passed_exRa-class by using the add_ICs function.

keep

a boolean value difining whether des person parameters will be part of the passed_exRa-class results object (TRUE) or not (FALSE). Keeping the person parameters will result in shorter runtimes, if several tests that need these parameters are used. On the other hand there will be a largeramount of memeory usage.

ignoreCores

a numeric value for the number of cpu cores to hold out in parallelizing the test run.

verbose

a boolean value. If set to FALSE, all output during the analysis will be suppressed.

...

arguments for itemfit_control and estimation_controlcan be passed directly to this function.

itemfit_param

a list from itemfit_control with options for test_itemfit

estimation_param

options for parameter estimation using estimation_control

Value

an object of passed_exRa-class.

Examples


  library(exhaustiveRasch)
  data(ADL)
  passed <- exhaustive_tests(dset= ADL[c(1:4,7,12,14)],
    modelType= "RM", scale_length= 5, alpha=0.05,
    tests=c("test_LR", "test_itemfit", "test_respca"),
    splitcr_LR = ADL[,17], itemfit_param =
      itemfit_control(use.pval=FALSE, upperMSQ=1.5, lowerMSQ=0.5),
    estimation_param= estimation_control(
      est="psychotools"), verbose=FALSE)


returns a matrix with dims like resp matrix with expected scores and more ... func. by joerg-henrik heine jhheine(at)googlemail.com needs func. pvx in i.pvx.R and pvx.matrix in i.pvx.matrix.R Notation and formulas see: Wright & Masters 1982 p.100 in a revised form (korrigendum) see http://www.rasch.org/rmt/rmt34e.htm

Description

returns a matrix with dims like resp matrix with expected scores and more ... func. by joerg-henrik heine jhheine(at)googlemail.com needs func. pvx in i.pvx.R and pvx.matrix in i.pvx.matrix.R Notation and formulas see: Wright & Masters 1982 p.100 in a revised form (korrigendum) see http://www.rasch.org/rmt/rmt34e.htm

Usage

expscore(pers_obj, na_treat = NA)

Arguments

pers_obj

an object of class "pers"

na_treat

internal

Value

internal


returns a matrix with dims like resp matrix with expected scores and more ... func. by joerg-henrik heine jhheine(at)googlemail.com needs func. pvx in i.pvx.R and pvx.matrix in i.pvx.matrix.R Notation and formulas see: Wright & Masters 1982 p.100 in a revised form (korrigendum) see http://www.rasch.org/rmt/rmt34e.htm

Description

returns a matrix with dims like resp matrix with expected scores and more ... func. by joerg-henrik heine jhheine(at)googlemail.com needs func. pvx in i.pvx.R and pvx.matrix in i.pvx.matrix.R Notation and formulas see: Wright & Masters 1982 p.100 in a revised form (korrigendum) see http://www.rasch.org/rmt/rmt34e.htm

Usage

expscore.psy(X, thres, ppar, na_treat = NA)

Arguments

X

internal

thres

internal

ppar

internal

na_treat

internal

Value

internal


parameter estimation for for rasch models.

Description

parameter estimation for for rasch models.

Usage

fit_rasch(X, modelType, estimation_param)

Arguments

X

a numeric vector containing the index numbers of the items in dset that are used to fit the model

modelType

a character value defining the rasch model to fit. Possible values: RM, PCM, RSM

estimation_param

options for parameter estimation using estimation_control

Value

a model of the class depending of modelType and estimation_param$est.If no model can be fit, NULL is returened.


options for test_itemfit()

Description

options for test_itemfit()

Usage

itemfit_control(
  zstd = FALSE,
  msq = TRUE,
  outfits = TRUE,
  use.pval = TRUE,
  lowerMSQ = 0.7,
  upperMSQ = 1.3,
  lowerZ = -1.96,
  upperZ = 1.96,
  use.rel = FALSE
)

Arguments

zstd

a boolean value whether to check the standardised fit indices

msq

a boolean value whether to check the mean-squared fit indices

outfits

a boolean value whether to check outfit indices (if FALSE, only infits are checked)

use.pval

a boolean value whether to exclude combinations with at least one item with significant p-value

lowerMSQ

a numeric value for the lower bound for acceptable fit (mean-squared fit indices)

upperMSQ

a numeric value for the upper bound for acceptable fit (mean-squared fit indices)

lowerZ

a numeric value for the lower bound for acceptable fit (standardised fit indices)

upperZ

a numeric value for the upper bound for acceptable fit (standardised fit indices)

use.rel

a boolean value wheter to use the unweighted (default, FALSE) or weighted item fit indices for MSQ and z-standardised fit-indices. Only available for 'pairwise' and 'psychotools' estiomation, will be ignored, for 'eRm' estimation.

Value

a list containing the options


S3 logLik for Object of class "pers"

Description

S3 logLik method to extract the log-likelihood for object of class pairwise::pers

Usage

## S3 method for class 'pers'
logLik(object, sat = FALSE, p = FALSE, ...)

Arguments

object

object of class pairwise::pers

sat

a "logical" with default set to sat=FALSE to return the Log-Likelihood of the data for the unrestricted modell based on parameters estimated with function pairwise::pers. If set to sat=TRUE the Log-Likelihood of the saturated model is returned instead.

p

a "logical" with default set to p=FALSE to return the category propabilities for the empirical data.

...

not used jet.

Value

an object of class 'logik', containing the likelihood an degrees of freedom


Martin-Loef test for psychotools

Description

Martin-Loef test for psychotools

Usage

mloef.psy(model, modelType, splitcr = "median", splitseed = NULL)

Arguments

model

an object of 'psychotools' class 'raschmodel', 'pcmodel' or 'rsmodel' (a model previously fit using the 'psychotools' package) matching the value of modelType.

modelType

a character value defining the type of Rasch model. Possible values: "RM", "PCM", "RSM"

splitcr

Split criterion to define the item groups. "median" and "mean" split items in two groups based on their items' raw scores median or mean. "random" performs a random split (in this case, the seed can be set with the "splitseed" argument. splitcr can also be a vector of length k (where k denotes the number of items) that takes two or more distinct values to define groups used for the Martin-Löf Test.

splitseed

seed for random split

Value

a list containing the test statistic, the degrees of freedom and the p-value of the Martin-Löf test.

Examples

 model <- psychotools::raschmodel(ADL[c(6,7,12,14,15)])
 mloef.psy(model=model, modelType="RM", splitcr="random", splitseed=332)

no test will be conducted, but rasch models (RM, PCM, RSM - depending on modelType) will be fit

Description

no test will be conducted, but rasch models (RM, PCM, RSM - depending on modelType) will be fit

Usage

no_test(
  items = NULL,
  dset = NULL,
  na.rm = TRUE,
  model = NULL,
  p.par = NULL,
  modelType = NULL,
  estimation_param = NULL
)

Arguments

items

a numeric vector containing the index numbers of the items in dset that are used to fit the model

dset

a data.frame containing the data

na.rm

a boolean value. If TRUE, all cases with any NA are removed (na.omit). If FALSE, only cases with full NA responses are removed

model

on object of a fit Rasch model, estimated with the packages 'eRm' (classes 'RM', 'PCM' or 'RSM'), 'psychotools' (classes raschmodel, 'pcmodel' or 'rsmodel') or 'pairwise' (class 'pers'), matching the value of modelType. If 'model' is provided, this model is used. If NULL, a model is fit using 'dset' and 'items'.

p.par

a person parameter object matching the class of 'model'. If NULL, the person parameters will be estimated.

modelType

a character value defining the rasch model to fit. Possible values: "RM", "PCM", "RSM".

estimation_param

options for parameter estimation using estimation_control

Value

if there are no items with disordered thresholds in the model, a list containing two elements is returned: the pattern that was tested and a list of type RM, RCM or RSM (depending on modelType) with the fit model. If there is at least one item with disordered thresholds, NULL is returned.


conducts and controls the parallelisation of the tests, Intentionally, there are no defauklt values for the parameters, as this internal function is called by exhaustive_tests that also defines the default values for this function.

Description

conducts and controls the parallelisation of the tests, Intentionally, there are no defauklt values for the parameters, as this internal function is called by exhaustive_tests that also defines the default values for this function.

Usage

parallized_tests(
  dset,
  modelType,
  combos,
  models,
  p.par,
  na.rm,
  testfunction,
  itemfit_param,
  splitcr = NULL,
  icat_wald,
  alpha,
  bonf,
  DIFvars,
  gap_prop,
  max_contrast,
  PSI,
  extremes,
  ignoreCores,
  estimation_param,
  tests_count,
  verbose = TRUE,
  ...
)

Arguments

dset

a data.frame containing the data

modelType

a character value defining the rasch model to fit. Possible values: RM, PCM, RSM

combos

either 1) a list of item combinations to be tested, e.g. from apply_combo_rules or the passed_combos slot of an object of passed_exRa-class from a previous call to this function. Or 2) an object of passed_exRa-class. In this case, the previously fit models froms its passed_Models slot will also be used and will be passed to the test functions. This will speed up the analysis. If the parameter is NULL, all possible combinations of the items (columns) in dset will be tested

na.rm

a boolean value. If TRUE, in the respective item combination all cases with any NA are removed (na.omit). If FALSE, only cases with full NA responses are removed. NOTE: test_mloef currently does not allow for missing values (because erm::MLoef doesn't). If test_mloef is under the tests to perform, na.rm will automatically be set TRUE for ALL tests.

testfunction

a character defining the actual test (the internal testfunction) to perform. Possible values: all_rawscores, test_itemfit, test_LR, test_mloef, test_waldtest, threshold_order, test_DIFtree, test_personsItems, test_respca.

itemfit_param

a list from itemfit_control with options for test_itemfit

splitcr

the split criterion to use, if the actual testfunction is test_LR or test_waldtest.Split criterion for subject raw score splitting. "all.r" corresponds to a full raw score split, "median" uses the median as split criterion, "mean" performs a mean split. Optionally splitcr can also be a vector which assigns each person to a certain subgroup (e.g., following an external criterion). This vector can be numeric, character or a factor.

icat_wald

a boolean value indicating if the waldtest will be conducted on item level (TRUE, default value) or on item category level. This parameter only effects estimations using psychotools or pairwise and will be ignored for eRm estimations.

alpha

a numeric value for the alpha level. Will be ignored for test_itemfit if use.pval in itemfit_control is FALSE

bonf

a boolean value wheter to use a Bonferroni correction. Will be ignored if use.pval is FALSE

DIFvars

a data.frame containing the variables and their data to use for differential item functioning analysis with test_DIFtree

gap_prop

a numeric value between 0 and 1 that sets the criterion for the minimum proportion of neighboring person parameters with an item/threshold location in between. If set to 0, this criterion will not be checked (used in test_personsItems only)

max_contrast

a numeric value defining the maximum loading of a factor in the principal components analysis of the standardised residuals. Only relevant, if test_respca is one of the tests.

extremes

a boolean value indicating if a check for the item/threshold locations left of the 2nd lowest and right of the 2nd highest person parameter (used in test_personsItems only).

ignoreCores

a numeric value for the number of cpu cores to hold out in parallelizing the test run.

estimation_param

options for parameter estimation using estimation_control

verbose

a boolean value. If set to FALSE, all output during the analysis will be suppressed.

...

options for itemfit_control can be passed directly to this function.

Value

a list containing 3 elements is returned: a list of the item combinations, a list of the models (depending on modelType and estimation_param$est) with the fit models and a list with the person parameter objects (depending on estimation_param$est).


class passed_exRa, an S4 class representing an a result of the exhaustive_tests function

Description

class passed_exRa, an S4 class representing an a result of the exhaustive_tests function

Slots

process

a data.frame containg process information from the call to exhaustive_tests

passed_combos

a list of vectors containing item combinations using the indices of the items

passed_models

a list of objects of the class the respective package used for estimation uses for its models

passed_p.par

a list of objects containing the person parameters. Depending on the package used for estimation, also residuals and/or the PSI value can be part of this list

IC

a data.frame containing information criteria for each of the models in passed_models

data

a data.frame containing the data used for the analyses.

timings

a data.frame containing the the timings of the analyses.


itemfit statistics for psychotools

Description

itemfit statistics for psychotools

Usage

ppar.psy(model = NULL)

Arguments

model

an object of 'psychotools' class 'raschmodel', 'pcmodel' or 'rsmodel' (a model previously fit using the 'psychotools' package) matching the value of modelType.

Value

an object containing person parameters, residuals and PSI

Examples

 model <- psychotools::raschmodel(ADL[c(6,7,12,14,15)])
 ppar.psy(model)

this is an internal function for expscore()

Description

this is an internal function for expscore()

Usage

pvx(theta, thres, xm = NULL)

Arguments

thres

internal

xm

internal

Value

internal


pvx matrix

Description

pvx matrix

Usage

pvx.matrix(theta_v, thres, xm_v = NULL)

Arguments

theta_v

internal

thres

internal

xm_v

internal

Value

internal


internal pvx.super function"

Description

internal

Usage

pvx.super(theta_v, thres = NULL, dat = NULL)

Arguments

theta_v

internal

thres

internal

dat

internal

Value

internal


removes subsets or supersets of item combinations

Description

removes subsets or supersets of item combinations

Usage

remove_subsets(obj, keep_longest = FALSE)

Arguments

obj

either a list of vectors of item combinations (typically the passed_combos slot of an object of class passed_exRa or an object of passed_exRa-class. If combos is an object of passed_exRa-class, all process data (the process slot) and for any removed item combination also the fit models in the passed_models slot will be removed.

keep_longest

boolean; if TRUE, the respective superset is kept (and all subsets of these supersets are removed), if FALSE all subsets is kept (and supersets of these subsets are removed).

Value

depending of the class of obj, either a list of numeric vectors containing the remaining item combinations or an object of passed_exRa-class with the remaining item combinations, fit models and information criteria, but without the process information.

Examples


  library(exhaustiveRasch)
  data(ADL)
  passed_ADL <- exhaustive_tests(dset=ADL[1:15], scale_length=4:5,
    modelType= "RM", na.rm=TRUE, tests= c("test_LR"),
    splitcr_LR = ADL[,17], estimation_param = estimation_control())
  passed_shortest <- remove_subsets(passed_ADL, keep_longest=FALSE)
 

S3 residuals for Object of class "pers"

Description

S3 residuals method to extract the (Rasch) residuals for object of class pairwise::pers

Usage

## S3 method for class 'pers'
residuals(object, res = "sr", na_treat = 0, ...)

Arguments

object

object of class pairwise::pers

res

a character string defining which type of (rasch–) residual to return. This must be (exactly) one of the strings "exp" for expected scores "sr" for score residuals (default), "stdr" for standardised residuals, "srsq" for score residuals squared, or "stdrsq" for standardised residuals squared. The default is set to res="sr".

na_treat

value to be assigned to residual cells which have missing data in the original response matrix. Default is set to na_treat=0 to set the residuals to 0, which implys that they are imputed as 'fitting data', i.e., zero residuals. This can attenuate contrasts (see. http://www.rasch.org/rmt/rmt142m.htm). An option is to set it to na_treat=NA.

...

not used jet.

Value

a matrix containing the residuals


summary function for class passed_exRa

Description

summary function for class passed_exRa

Usage

## S4 method for signature 'passed_exRa'
summary(object)

Arguments

object

an object of passed_exRa-class

Value

no object is returned, the summary is printed to the console. This comprises: tested scale lengths, total number of tested item combinations, applied tests, number of passed item combinations that passed each test, item importance and runtimes.


builds a raschtree using the raschtree or rstree function of the psychotree Package.

Description

builds a raschtree using the raschtree or rstree function of the psychotree Package.

Usage

test_DIFtree(
  items = NULL,
  DIFvars = NULL,
  dset = NULL,
  na.rm = TRUE,
  model = NULL,
  p.par = NULL,
  modelType = NULL,
  alpha = 0.1,
  estimation_param = NULL
)

Arguments

items

a numeric vector containing the index numbers of the items in dset that are used to fit the model

DIFvars

a vector or a data.frame containing the external variable(s) to test for differential item functioning

dset

a data.frame containing the data

na.rm

a boolean value. If TRUE, all cases with any NA are removed (na.omit). If FALSE, only cases with full NA responses are removed

model

on object of a fit Rasch model, estimated with the packages 'eRm' (classes 'RM', 'PCM' or 'RSM'), 'psychotools' (classes raschmodel, 'pcmodel' or 'rsmodel') or 'pairwise' (class 'pers'), matching the value of modelType. If 'model' is provided, this model is used. If NULL, a model is fit using 'dset' and 'items'.

p.par

a person parameter object matching the class of 'model'. If NULL, the person parameters will be estimated.

modelType

a character value defining the rasch model to fit. Possible values: "RM", "PCM", "RSM".

alpha

a numeric value for the alpha level. Will be ignored if use.pval is FALSE

estimation_param

options for parameter estimation using estimation_control

Value

if none of the p-values is significant, a list containing 3 elements is returned: the item combination that was tested, a list of the class the model was estimated with (depending on modelType and estimation_param$est) with the fit model and a list with a person parameter object (depending on estimation_param$est). If there is at least one item with a significant p-value, NULL is returned.


runs Anderson's likelihood ration test using the LRtest() function of eRm.

Description

runs Anderson's likelihood ration test using the LRtest() function of eRm.

Usage

test_LR(
  items = NULL,
  dset = NULL,
  na.rm = TRUE,
  model = NULL,
  p.par = NULL,
  modelType = NULL,
  splitcr = "median",
  alpha = 0.1,
  estimation_param = NULL
)

Arguments

items

a numeric vector containing the index numbers of the items in dset that are used to fit the model

dset

a data.frame containing the data

na.rm

a boolean value. If TRUE, all cases with any NA are removed (na.omit). If FALSE, only cases with full NA responses are removed

model

on object of a fit Rasch model, estimated with the packages 'eRm' (classes 'RM', 'PCM' or 'RSM'), 'psychotools' (classes raschmodel, 'pcmodel' or 'rsmodel') or 'pairwise' (class 'pers'), matching the value of modelType. If 'model' is provided, this model is used. If NULL, a model is fit using 'dset' and 'items'.

p.par

a person parameter object matching the class of 'model'. If NULL, the person parameters will be estimated.

modelType

a character value defining the rasch model to fit. Possible values: "RM", "PCM", "RSM".

splitcr

as defined by eRm::LRtest. Split criterion for subject raw score splitting. "all.r" corresponds to a full raw score split, "median" uses the median as split criterion, "mean" performs a mean split. Optionally splitcr can also be a vector which assigns each person to a certain subgroup (e.g., following an external criterion). This vector can be numeric, character or a factor. A random split, as in pairwise, is also a possible option.

alpha

a numeric value for the alpha level. Will be ignored if use.pval is FALSE

estimation_param

options for parameter estimation using estimation_control

Value

if the p-value of the test is not significant AND if no items were excluded in the test due to missing patterns, a list containing 3 elements is returned: the item combination that was tested, a list of the class the model was estimated with (depending on modelType and estimation_param$est) with the fit model and a list with a person parameter object (depending on estimation_param$est). If the test is significant, NULL is returned.


runs a principal component analysis (PCA) on the residuals of the rasch model.

Description

runs a principal component analysis (PCA) on the residuals of the rasch model.

Usage

test_PSI(
  items = NULL,
  dset = NULL,
  na.rm = TRUE,
  model = NULL,
  p.par = NULL,
  modelType = NULL,
  PSI = NULL,
  estimation_param = NULL
)

Arguments

items

a numeric vector containing the index numbers of the items in dset that are used to fit the model

dset

a data.frame containing the data

na.rm

a boolean value. If TRUE, all cases with any NA are removed (na.omit). If FALSE, only cases with full NA responses are removed

model

on object of a fit Rasch model, estimated with the packages 'eRm' (classes 'RM', 'PCM' or 'RSM'), 'psychotools' (classes raschmodel, 'pcmodel' or 'rsmodel') or 'pairwise' (class 'pers'), matching the value of modelType. If 'model' is provided, this model is used. If NULL, a model is fit using 'dset' and 'items'.

p.par

a person parameter object matching the class of 'model'. If NULL, the person parameters will be estimated.

modelType

a character value defining the rasch model to fit. Possible values: "RM", "PCM", "RSM".

PSI

a numeric value defining the minimum value for the person- separation-index (separation reliablility).

estimation_param

options for parameter estimation using estimation_control

Value

if the value of the PSI for the model is >= the PSI argument, a list containing 3 elements is returned: the item combination that was tested, a list of the class the model was estimated with (depending on modelType and estimation_param$est) with the fit model and a list with a person parameter object (depending on estimation_param$est). Else, NULL is returned.


checks the itemfit indices of a rasch model using the itemfit() function of eRm.

Description

checks the itemfit indices of a rasch model using the itemfit() function of eRm.

Usage

test_itemfit(
  items = NULL,
  dset = NULL,
  na.rm = TRUE,
  control,
  modelType = NULL,
  model = NULL,
  p.par = NULL,
  alpha = 0.1,
  bonf = FALSE,
  estimation_param = NULL
)

Arguments

items

a numeric vector containing the index numbers of the items in dset that are used to fit the model

dset

a data.frame containing the data

na.rm

a boolean value. If TRUE, all cases with any NA are removed (na.omit). If FALSE, only cases with full NA responses are removed

control

list object with options from itemfit_control

modelType

a character value defining the rasch model to fit. Possible values: "RM", "PCM", "RSM".

model

on object of a fit Rasch model, estimated with the packages 'eRm' (classes 'RM', 'PCM' or 'RSM'), 'psychotools' (classes raschmodel, 'pcmodel' or 'rsmodel') or 'pairwise' (class 'pers'), matching the value of modelType. If 'model' is provided, this model is used. If NULL, a model is fit using 'dset' and 'items'.

p.par

a person parameter object matching the class of 'model'. If NULL, the person parameters will be estimated.

alpha

a numeric value for the alpha level. Will be ignored if use.pval is FALSE

bonf

a boolean value whether to use a Bonferroni correction. Will be ignored if use.pval is FALSE

estimation_param

options for parameter estimation using estimation_control

Value

if all fit indices meet the given criteria, a list containing 3 elements is returned: the item combination that was tested, a list of the class the model was estimated with (depending on modelType and estimation_param$est) with the fit model and a list with a person parameter object (depending on estimation_param$est). If at least one item's fit indices do not meet the given criteria, NULL is returned.


runs Martin-Loef Test using the MLoef() function of eRm.

Description

runs Martin-Loef Test using the MLoef() function of eRm.

Usage

test_mloef(
  items = NULL,
  dset = NULL,
  na.rm = TRUE,
  model = NULL,
  p.par = NULL,
  modelType = NULL,
  splitcr = "median",
  alpha = 0.1,
  estimation_param = NULL
)

Arguments

items

a numeric vector containing the index numbers of the items in dset that are used to fit the model

dset

a data.frame containing the data

na.rm

a boolean value. If TRUE, all cases with any NA are removed (na.omit). If FALSE, only cases with full NA responses are removed

model

on object of a fit Rasch model, estimated with the packages 'eRm' (classes 'RM', 'PCM' or 'RSM'), 'psychotools' (classes raschmodel, 'pcmodel' or 'rsmodel') or 'pairwise' (class 'pers'), matching the value of modelType. If 'model' is provided, this model is used. If NULL, a model is fit using 'dset' and 'items'.

p.par

a person parameter object matching the class of 'model'. If NULL, the person parameters will be estimated.

modelType

a character value defining the rasch model to fit. Possible values: "RM", "PCM", "RSM".

splitcr

as defined by eRm::MLoef: Split criterion to define the item groups. "median" and "mean" split items in two groups based on their items' raw scores. splitcr can also be a vector of length k (where k denotes the number of items) that takes two or more distinct values to define groups used for the Martin-Löf Test.

alpha

a numeric value for the alpha level. Will be ignored if use.pval is FALSE

estimation_param

options for parameter estimation using estimation_control

Value

if the p-value of the test is not significant, a list containing 3 elements is returned: the item combination that was tested, a list of the class the model was estimated with (depending on modelType and estimation_param$est) with the fit model and a list with a person parameter object (depending on estimation_param$est). If the test is significant, NULL is returned.


checks the relationship between the person parameter distribution and the item (or: threshold) locations for defined criteria

Description

checks the relationship between the person parameter distribution and the item (or: threshold) locations for defined criteria

Usage

test_personsItems(
  items = NULL,
  dset = NULL,
  na.rm = TRUE,
  model = NULL,
  p.par = NULL,
  modelType = NULL,
  gap_prop = 0,
  extremes = TRUE,
  estimation_param = NULL
)

Arguments

items

a numeric vector containing the index numbers of the items in dset that are used to fit the model

dset

a data.frame containing the data

na.rm

a boolean value. If TRUE, all cases with any NA are removed (na.omit). If FALSE, only cases with full NA responses are removed

model

on object of a fit Rasch model, estimated with the packages 'eRm' (classes 'RM', 'PCM' or 'RSM'), 'psychotools' (classes raschmodel, 'pcmodel' or 'rsmodel') or 'pairwise' (class 'pers'), matching the value of modelType. If 'model' is provided, this model is used. If NULL, a model is fit using 'dset' and 'items'.

p.par

a person parameter object matching the class of 'model'. If NULL, the person parameters will be estimated.

modelType

a character value defining the rasch model to fit. Possible values: "RM", "PCM", "RSM".

gap_prop

a numeric value between 0 and 1 that sets the criterion for the minimum proportion of neighboring person parameters with an item/threshold location in between. If set to 0, this criterion will not be checked.

extremes

a boolean value indicating if a check for the item/threshold locations left of the 2nd lowest and right of the 2nd highest person parameter.

estimation_param

options for parameter estimation using estimation_control

Value

if the criteria are met, a list containing 3 elements is returned: the item combination that was tested, a list of the class the model was estimated with (depending on modelType and estimation_param$est) with the fit model and a list with a person parameter object (depending on estimation_param$est). If the criteria are not met, NULL is returned.


runs a principal component analysis (PCA) on the residuals of the rasch model.

Description

runs a principal component analysis (PCA) on the residuals of the rasch model.

Usage

test_respca(
  items = NULL,
  dset = NULL,
  na.rm = TRUE,
  model = NULL,
  p.par = NULL,
  modelType = NULL,
  max_contrast = 1.5,
  estimation_param = NULL
)

Arguments

items

a numeric vector containing the index numbers of the items in dset that are used to fit the model

dset

a data.frame containing the data

na.rm

a boolean value. If TRUE, all cases with any NA are removed (na.omit). If FALSE, only cases with full NA responses are removed

model

on object of a fit Rasch model, estimated with the packages 'eRm' (classes 'RM', 'PCM' or 'RSM'), 'psychotools' (classes raschmodel, 'pcmodel' or 'rsmodel') or 'pairwise' (class 'pers'), matching the value of modelType. If 'model' is provided, this model is used. If NULL, a model is fit using 'dset' and 'items'.

p.par

a person parameter object matching the class of 'model'. If NULL, the person parameters will be estimated.

modelType

a character value defining the rasch model to fit. Possible values: "RM", "PCM", "RSM".

max_contrast

a numeric value defining the maximum loading of a factor in the principal components analysis of the standardised residuals.

estimation_param

options for parameter estimation using estimation_control

Value

if the maximum eigenvalue of the contrasts of the pca is < max_contrast, a list containing 3 elements is returned: the item combination that was tested, a list of the class the model was estimated with (depending on modelType and estimation_param$est) with the fit model and a list with a person parameter object (depending on estimation_param$est). Else, NULL is returned.


runs a Wald test using the Waldtest() function of eRm.

Description

runs a Wald test using the Waldtest() function of eRm.

Usage

test_waldtest(
  items = NULL,
  dset = NULL,
  na.rm = TRUE,
  model = NULL,
  p.par = NULL,
  modelType = NULL,
  splitcr = "median",
  icat = FALSE,
  alpha = 0.1,
  bonf = FALSE,
  estimation_param = NULL
)

Arguments

items

a numeric vector containing the index numbers of the items in dset that are used to fit the model

dset

a data.frame containing the data

na.rm

a boolean value. If TRUE, all cases with any NA are removed (na.omit). If FALSE, only cases with full NA responses are removed

model

on object of a fit Rasch model, estimated with the packages 'eRm' (classes 'RM', 'PCM' or 'RSM'), 'psychotools' (classes raschmodel, 'pcmodel' or 'rsmodel') or 'pairwise' (class 'pers'), matching the value of modelType. If 'model' is provided, this model is used. If NULL, a model is fit using 'dset' and 'items'.

p.par

a person parameter object matching the class of 'model'. If NULL, the person parameters will be estimated.

modelType

a character value defining the rasch model to fit. Possible values: "RM", "PCM", "RSM".

splitcr

as defined by eRm::Waldtest: Split criterion for subject raw score splitting. median uses the median as split criterion, mean performs a mean-split. Optionally splitcr can also be a dichotomous vector which assigns each person to a certain subgroup (e.g., following an external criterion). This vector can be numeric, character or a factor.

icat

a boolean value indicating if the waldtest will be conducted on item level (TRUE, default value) or on item category level. This parameter only effects estimations using psychotools or pairwise and will be ignored for eRm estimations.

alpha

a numeric value for the alpha level. Will be ignored if use.pval is FALSE

bonf

a boolean value wheter to use a Bonferroni correction. Will be ignored if use.pval is FALSE

estimation_param

options for parameter estimation using estimation_control

Value

if none of the p-values is significant, a list containing 3 elements is returned: the item combination that was tested, a list of the class the model was estimated with (depending on modelType and estimation_param$est) with the fit model and a list with a person parameter object (depending on estimation_param$est). If there is at least one item with a significant p-value, NULL is returned.


checks for disordered thresholds in rasch models

Description

checks for disordered thresholds in rasch models

Usage

threshold_order(
  items = NULL,
  dset = NULL,
  na.rm = TRUE,
  model = NULL,
  p.par = NULL,
  modelType = NULL,
  estimation_param = NULL
)

Arguments

items

a numeric vector containing the index numbers of the items in dset that are used to fit the model

dset

a data.frame containing the data

na.rm

a boolean value. If TRUE, all cases with any NA are removed (na.omit). If FALSE, only cases with full NA responses are removed

model

on object of a fit Rasch model, estimated with the packages 'eRm' (classes 'RM', 'PCM' or 'RSM'), 'psychotools' (classes raschmodel, 'pcmodel' or 'rsmodel') or 'pairwise' (class 'pers'), matching the value of modelType. If 'model' is provided, this model is used. If NULL, a model is fit using 'dset' and 'items'.

p.par

a person parameter object matching the class of 'model'. If NULL, the person parameters will be estimated.

modelType

a character value defining the rasch model to fit. Possible values: "RM", "PCM", "RSM".

estimation_param

options for parameter estimation using estimation_control

Value

if there are no items with disordered thresholds in the model, a list containing 3 elements is returned: the item combination that was tested, a list of the class the model was estimated with (depending on modelType and estimation_param$est) with the fit modeland a list with a person parameter object (depending on estimation_param$est). If there is at least one item with disordered thresholds, NULL is returned.


Fischer and Scheiblechner's "wald-like" S-statistic for psychotools

Description

Fischer and Scheiblechner's "wald-like" S-statistic for psychotools

Usage

waldtest.psy(
  model,
  modelType,
  splitcr = "median",
  splitseed = NULL,
  icat = FALSE
)

Arguments

model

an object of 'psychotools' class 'raschmodel', 'pcmodel' or 'rsmodel' (a model previously fit using the 'psychotools' package) matching the value of modelType.

modelType

a character value defining the type of Rasch model. Possible values: "RM", "PCM", "RSM"

splitcr

split criterion for subject raw score splitting. "median" uses the median as split criterion, "mean" performs a mean-split, "random" performs a random split (in this case, the seed can be set with the "splitseed" argument. Optionally splitcr can also be a dichotomous vector which assigns each person to a certain subgroup (typically an external criterion). This vector can be numeric, character or a factor.

splitseed

seed for random split

icat

a boolean value defining wether to use item parameters ('psychotools' function 'itempar', if TRUE) or item category parameters ('psychotools' function 'threshpar')

Value

a vector containing the p-values of the Scheiblechner's "wald-like" S-statistic for the items (if icat=FALSE) or for the item categories (if icat=TRUE).

Examples

 model <- psychotools::raschmodel(ADL[c(6,7,12,14,15)])
   waldtest.psy(model=model, modelType="RM", splitcr="random", splitseed=332,
   icat=FALSE)