Package {conquestr}

Type:	Package
Title:	An R Package to Extend 'ACER ConQuest'
Version:	1.9.2
Description:	Extends 'ACER ConQuest' through a family of functions designed to improve graphical outputs and help with advanced analysis (e.g., differential item functioning). Allows R users to call 'ACER ConQuest' from within R and read 'ACER ConQuest' System Files (generated by the command ‘put' https://conquestmanual.acer.org/s4-00.html#put). Requires ’ACER ConQuest' version 5.40 or later. A demonstration version can be downloaded from https://shop.acer.org/collections/acer-conquest-5.
License:	GPL-3
URL:	https://www.acer.org/au/conquest, https://conquestmanual.acer.org, https://shop.acer.org/collections/acer-conquest-5
Imports:	dplyr, ggplot2 (≥ 3.5.1), ggrepel, kableExtra, magrittr, methods, Rcpp, rlang, stats, stringr, tidyr, tidyselect, zlib
Suggests:	knitr, gridExtra, rmarkdown, testthat (≥ 3.2.1)
LinkingTo:	Rcpp
VignetteBuilder:	knitr
Config/testthat/edition:	3
Encoding:	UTF-8
SystemRequirements:	ACER ConQuest (>=5.40.0)
Collate:	"RcppExports.R" "ReadConQuestLibrary.R" "ReadConQuestRout_createDF.R" "ReadConQuestState.R" "postProcessCqSysfile.R" "ReadConQuestState_createDF.R" "conquestr.R" "conquestrFunc.R" "generateItems.R" "generateHelpers.R" "infoHelpers.R" "itanalHelpers.R" "plotGeneral.R" "plotRout.R" "pvStats.R" "residHelpers.R" "showHelpers.R" "thrstThrsh.R" "cleaningHelpers.R"
Depends:	R (≥ 4.1.0)
Config/roxygen2/version:	8.1.1
NeedsCompilation:	yes
Packaged:	2026-10-26 07:39:29 UTC; acercloneyd
Author:	Dan Cloney [aut, cre], Ray Adams [aut]
Maintainer:	Dan Cloney <dan.cloney@acer.org>
Repository:	CRAN
Date/Publication:	2026-10-26 11:50:02 UTC

ConQuestCall

Description

Call an instance of 'ACER ConQuest' at the command line and run a control file (syntax).

Usage

ConQuestCall(cqc, cqExe, stdout = "")

Arguments

Value

prints 'ACER ConQuest' output to stdout.

Examples

## Not run: 
ConQuestCall()

## End(Not run)

ConQuestRout

Description

Read an 'ACER ConQuest' rout file (a binary file) created by a plot command in 'ACER ConQuest'.

Usage

ConQuestRout(myRout)

Arguments

Value

A list containing the data objects to recreate 'ACER ConQuest' plots.

Examples

myPlot <- ConQuestRout()
## Not run: 
# the default example is an ICC plot from Example 1 
# <https://conquestmanual.acer.org/s2-00.html#s2-02>.
str(myPlot)

## End(Not run)

ConQuestSys

Description

Read an ”ACER ConQuest” system file created by a put command in 'ACER ConQuest'. The system file must not be compressed. Use the option ‘compressed=no“ in the put command within ’ACER ConQuest'.

Usage

ConQuestSys(myCqs, isMini = FALSE)

Arguments

Value

A list containing the data objects created by 'ACER ConQuest'.

Examples

mySysData <- ConQuestSys()
myEx1SysData <- ConQuestSys(myCqs = system.file("extdata", "mysysfile.cqs", package = "conquestr"))
## Not run: 
# if you run the above example this will return your original 'ACER ConQuest' syntax.
cat(unlist(myEx1SysData$gCommandHistory))

## End(Not run)

DecompressSys

Description

Internal function to decompress an 'ACER ConQuest' system file that has been compressed using zlib.

Usage

DecompressSys(myFile)

Arguments

Value

A raw vector: the uncompressed system file, beginning with the "uncompressed" header.

See Also

conquestr::ConQuestSys()

ItemDfStdZ

Description

Calculates centred and scaled item parameter estimates. Also calculates standardised standard errors of item parameter estimates to complement scaled item parameter estimates.

Usage

ItemDfStdZ(myDf)

Arguments

Value

a data frame.

See Also

conquestr::sysToItemDifDf()

ItemDfStdZMerge

Description

Calculates Z test on the common items from 2 data frames returned from conquestr::ItemDfStdZ.

Usage

ItemDfStdZMerge(myDf1, myDf2, mySuffixes)

Arguments

Value

a data frame.

See Also

conquestr::sysToItemDifDf()

ReadADesignMatrices

Description

ReadSys Read the A design matrix (A list of length gNGins of matrices. For each matrix the number of rows is gItemSteps (for that item) and the number of columns is gNParameters_C).

Usage

ReadADesignMatrices(myFile, Columns, Items, ItemSteps)

Arguments

Value

A list

ReadAllCaseEstimates

Description

ReadAllCaseEstimates

Usage

ReadAllCaseEstimates(myFile, Dimensions, N, NPlausibles, cqs_version)

Arguments

Value

A list

ReadAllGroupsData

Description

ReadAllGroupsData

Usage

ReadAllGroupsData(myFile, N, GroupVariables, AllVariables)

Arguments

Value

A list

ReadAllResponseData

Description

ReadAllResponseData

Usage

ReadAllResponseData(myFile, N)

Arguments

Value

A list

ReadAllY

Description

ReadAllY

Usage

ReadAllY(myFile, N, NReg)

Arguments

ReadAnchor

Description

ReadAnchor

Usage

ReadAnchor(myFile)

Arguments

Value

A list

ReadAnchorList

Description

ReadAnchorList

Usage

ReadAnchorList(myFile)

Arguments

Value

A list

ReadBDesignMatrices

Description

ReadSys Read the B design matrix (A list of length gNGins of lists, one per item. For each item a list of length gItemSteps of matrices).

Usage

ReadBDesignMatrices(myFile, ItemSteps, Items)

Arguments

Value

A list

ReadBandDefine

Description

ReadBandDefine

Usage

ReadBandDefine(myFile)

Arguments

Value

A list

ReadBandDefinesList

Description

ReadBandDefinesList

Usage

ReadBandDefinesList(myFile)

Arguments

Value

A list

ReadBitSet

Description

ReadBitSet

Usage

ReadBitSet(myFile)

Arguments

Value

A list

ReadBoolean

Description

ReadBoolean

Usage

ReadBoolean(myFile)

Arguments

Value

A list

ReadBooleanList

Description

ReadBooleanList

Usage

ReadBooleanList(myFile)

Arguments

Value

A list

ReadCDesignMatrices

Description

ReadSys Read the C design matrix (A list of length gNGins of lists, one per item. For each item a list of length gItemSteps of matrices).

Usage

ReadCDesignMatrices(myFile, Dimensions, ItemSteps, Items)

Arguments

Value

A list

ReadCategorise

Description

ReadCategorise

Usage

ReadCategorise(myFile)

Arguments

Value

A list

ReadCategoriseLegacy

Description

ReadCategoriseLegacy

Usage

ReadCategoriseLegacy(myFile)

Arguments

Value

A list

ReadCategoriseList

Description

ReadCategoriseList

Usage

ReadCategoriseList(myFile)

Arguments

Value

A list

ReadCategoriseListLegacy

Description

ReadCategoriseListLegacy

Usage

ReadCategoriseListLegacy(myFile)

Arguments

Value

A list

ReadCodeList

Description

ReadCodeList

Usage

ReadCodeList(myFile)

Arguments

Value

A list

ReadDataRecord

Description

ReadDataRecord

Usage

ReadDataRecord(myFile)

Arguments

Value

A list

ReadDouble

Description

ReadDouble

Usage

ReadDouble(myFile)

Arguments

Value

A list

ReadDoubleList

Description

ReadDoubleList

Usage

ReadDoubleList(myFile)

Arguments

Value

A list

ReadErrors

Description

ReadErrors

Usage

ReadErrors(myFile)

Arguments

Value

A list

ReadEstimatesRecord

Description

ReadEstimatesRecord

Usage

ReadEstimatesRecord(myFile, Dimensions, NPlausibles, n, cqs_version)

Arguments

Value

A list

ReadFit

Description

ReadFit

Usage

ReadFit(myFile)

Arguments

Value

A list

ReadFitList

Description

ReadFitList

Usage

ReadFitList(myFile)

Arguments

Value

A list

ReadGExportOptions

Description

ReadGExportOptions

Usage

ReadGExportOptions(myFile)

Arguments

Value

A list of a single ExportOption (e.g., used in ExportXsi())

ReadGExportOptionsList

Description

ReadGExportOptionsList

Usage

ReadGExportOptionsList(myFile)

Arguments

Value

A list of ExportOptions

ReadGraph

Description

ReadGraph

Usage

ReadGraph(myFile)

Arguments

Value

A list

ReadGroupsOneCase

Description

ReadGroupsOneCase

Usage

ReadGroupsOneCase(myFile, GroupVariables, AllVariables, CaseNum)

Arguments

Value

A list

ReadHistory

Description

ReadHistory

Usage

ReadHistory(myFile)

Arguments

Value

A list

ReadIRecode

Description

ReadIRecode

Usage

ReadIRecode(myFile)

Arguments

Value

A list

ReadIRecodeList

Description

ReadIRecodeList

Usage

ReadIRecodeList(myFile)

Arguments

Value

A list

ReadImplicitVar

Description

ReadImplicitVar

Usage

ReadImplicitVar(myFile)

Arguments

Value

A list

ReadIntArray2

Description

ReadIntArray2

Usage

ReadIntArray2(myFile)

Arguments

Value

A matrix

ReadInteger

Description

ReadInteger

Usage

ReadInteger(myFile)

Arguments

Value

A list

ReadIntegerList

Description

ReadIntegerList

Usage

ReadIntegerList(myFile)

Arguments

Value

A list

ReadIntegerListList

Description

ReadIntegerListList

Usage

ReadIntegerListList(myFile)

Arguments

Value

A list

ReadItemSet

Description

ReadItemSet

Usage

ReadItemSet(myFile)

Arguments

Value

A list

ReadItemSetList

Description

ReadItemSetList

Usage

ReadItemSetList(myFile)

Arguments

Value

A list

ReadKey

Description

ReadKey

Usage

ReadKey(myFile)

ReadKeyList

Description

ReadKeyList

Usage

ReadKeyList(myFile)

Arguments

Value

A list

ReadLabel

Description

ReadLabel

Usage

ReadLabel(myFile)

Arguments

Value

A list

ReadLabelList

Description

ReadLabelList

Usage

ReadLabelList(myFile)

Arguments

Value

A list

ReadLookUp

Description

ReadLookUp

Usage

ReadLookUp(myFile)

Arguments

Value

A list

ReadLookUpList

Description

ReadLookUpList

Usage

ReadLookUpList(myFile)

Arguments

Value

A list

ReadMatrix

Description

ReadMatrix

Usage

ReadMatrix(myFile)

Arguments

Value

A list

ReadMatrixList

Description

ReadMatrixList

Usage

ReadMatrixList(myFile)

Arguments

Value

A list

ReadMatrixVars

Description

ReadMatrixVars

Usage

ReadMatrixVars(myFile)

Arguments

Value

A list

ReadNamedStringList

Description

ReadNamedStringList

Usage

ReadNamedStringList(myFile)

Arguments

Value

A data frame

ReadParameters

Description

ReadParameters

Usage

ReadParameters(myFile)

Arguments

Value

A list

ReadParametersList

Description

ReadParametersList

Usage

ReadParametersList(myFile)

Arguments

Value

A list

ReadPoint

Description

ReadPoint

Usage

ReadPoint(myFile)

Arguments

Value

A list

ReadRandomStructure

Description

ReadRandomStructure

Usage

ReadRandomStructure(myFile)

Arguments

Value

A list

ReadRegression

Description

ReadRegression

Usage

ReadRegression(myFile)

Arguments

Value

A list

ReadRegressionList

Description

ReadRegressionList

Usage

ReadRegressionList(myFile)

Arguments

Value

A list

ReadRegressionListLeg

Description

ReadRegressionListLeg

Usage

ReadRegressionListLeg(myFile)

Arguments

Value

A list

ReadRegressors

Description

ReadRegressors

Usage

ReadRegressors(myFile)

Arguments

Value

A list

ReadResponse

Description

ReadResponse

Usage

ReadResponse(myFile)

Arguments

Value

A list

ReadResponseList

Description

ReadResponseList

Usage

ReadResponseList(myFile)

Arguments

Value

A list

ReadSeries

Description

ReadSeries

Usage

ReadSeries(myFile)

Arguments

Value

A list

ReadString

Description

ReadString

Usage

ReadString(myFile)

Arguments

Value

A list

ReadStringList

Description

ReadStringList

Usage

ReadStringList(myFile)

Arguments

Value

A list

ReadSys

Description

Internal function to read an 'ACER ConQuest' system file. Called by conquestr::ConQuestSys.

Usage

ReadSys(myFile, isMini)

Arguments

Value

A list containing the data objects created by 'ACER ConQuest'.

See Also

conquestr::ConQuestSys()

ReadSysMini

Description

Internal function to read an 'ACER ConQuest' system file. Called by conquestr::ConQuestSys.

Usage

ReadSysMini(myFile, Dimensions, N, NPlausibles, isDebug)

Arguments

Value

A list containing the data objects created by 'ACER ConQuest'.

See Also

conquestr::ConQuestSys()

ReadTerm

Description

ReadTerm

Usage

ReadTerm(myFile)

Arguments

Value

A list

ReadTerms

Description

ReadTerms

Usage

ReadTerms(myFile, cqs_version)

Arguments

Value

A list

ReadTermsList

Description

ReadTermsList

Usage

ReadTermsList(myFile, cqs_version)

Arguments

Value

A list

ReadVarInfo

Description

ReadVarInfo

Usage

ReadVarInfo(myFile)

Arguments

Value

A list

ReadVarList

Description

ReadVarList

Usage

ReadVarList(myFile)

Arguments

Value

A list

ReadVariable

Description

ReadVariable

Usage

ReadVariable(myFile)

Arguments

Value

A list

ReadVariableList

Description

ReadVariableList

Usage

ReadVariableList(myFile)

Arguments

Value

A list

ReadYOneCase

Description

ReadYOneCase

Usage

ReadYOneCase(myFile, NReg)

Arguments

Value

A list

buildPerturbMap

Description

Step 4 of genResponses(). Decides which perturbation (if any) applies to each case-item pair.

Usage

buildPerturbMap(perturbations, groups, nCases, nItems)

Arguments

Value

An integer cases by items matrix: 0 where the case receives the unperturbed item, otherwise the row of perturbations that applies. Where perturbations overlap, the later one is used, with a warning.

See Also

genResponses()

checkItemRespValid

Description

Check that the item responses in raw data are: (1) valid, (2) each valid response mapped to an item appears at least once, and (3) each valid reponse mapped to an item has sufficently many responses (defaults to a minimum of 10 observations for each response category)

Usage

checkItemRespValid(data, caseID, validMap, varLabel, validLabel)

Arguments

Value

A list of lists: one list per item in validMap$varLabel. Within each list, there can be up to three dfs: (1) the case ids and invalid responses for the item, (2) the valid codes not observed in the data set, and (3) the valid codes observed fewer than 10 times in the data. NOTE: a wanring is thrown if the validMap$varLabel is not found in the data.

checkNoExtraVars

Description

Check that the raw data does not include extraneous variables.

Usage

checkNoExtraVars(data, varNames, except = NULL)

Arguments

Value

A list.

checkVars

Description

Check raw data: are all required variables preseent and ensure there are no extraneous variables.

Usage

checkVars(data, varNames, except = NULL)

Arguments

Value

A list.

checkVarsExist

Description

Check that all required variables exist in raw data.

Usage

checkVarsExist(data, varNames)

Arguments

Value

A list.

cnvrtItemParam

Description

takes an item in one model's parameterisation and returns it in another parameterisation.

Usage

cnvrtItemParam(item, from = "muraki", to = "conquest", DFrom = 1, DTo = 1)

Arguments

Value

an m x 4 matrix of item parameters. The same dimensions as the input, item

Examples

myTheta <- 0
myDelta <- 1.5
a <- 1.5
m <- 3
itemParamX <- seq(0, m-1, 1)
itemParamD <- rep(myDelta, m)
itemParamT <- c(0, -0.5, 0.5)
itemParamA <- rep(a, m)
itemParam <- cbind(itemParamX, itemParamD, itemParamT, itemParamA)
colnames(itemParam)<- c("x", "d", "t", "a")
myItem <- cnvrtItemParam(itemParam, from = "conquest", to = "muraki", DFrom = 1, DTo = 1.7)

createConQuestProject

Description

creates a standard folder structure to work with 'ACER ConQuest' Projects.

Usage

createConQuestProject(prefix = getwd(), ...)

Arguments

Value

Boolean TRUE.

Examples

## Not run: 
createConQuestProject()

## End(Not run)

findConQuestExe

Description

Searches in common install paths to find ConQuest executable. This is called by ConQuestCall when no executable is passed explicitly.

Usage

findConQuestExe()

Value

Char with path to ConQuest executable.

Examples

## Not run: 
findConQuestExe()

## End(Not run)

Fisher z-transform a correlation matrix

Description

Applies Fisher's (1915) variance-stabilising transformation to the off-diagonal elements of a correlation matrix.

Usage

fisherTrnsfrm(myCorMat)

Arguments

Details

Each off-diagonal correlation is mapped to

z_{ij} = \operatorname{artanh}(r_{ij}) = \frac{1}{2}\ln\frac{1 + r_{ij}}{1 - r_{ij}}, \quad i \neq j.

For bivariate-normal data with population correlation \rho, z_{ij} is approximately normal with mean \operatorname{artanh}(\rho) and variance 1/(N-3), independent of \rho.

Since \operatorname{artanh}(\pm 1) = \pm\infty, off-diagonal values with |r_{ij}| \ge 1 - 10^{-7} are first truncated to \pm(1 - 10^{-7}) (giving |z_{ij}| \approx 8.4) and a warning is issued. The diagonal is left at 1 and is not meaningful on the z scale.

Value

A matrix of the same dimensions with z_{ij} off the diagonal and 1 on the diagonal.

References

Fisher, R. A. (1915). Frequency distribution of the values of the correlation coefficient in samples from an indefinitely large population. Biometrika, 10(4), 507–521. doi:10.2307/2331838

See Also

q3ExpCorrect(), steigerStat()

fmtCqItanal

Description

helper function to produce nicely formatted summary tables from a ConQuest Itanal.

Usage

fmtCqItanal(
  cqItanal,
  groups = "all",
  itemNumber = "all",
  ptBisFlag = 0,
  textColHighlight = "red",
  valueDecPlace = 2
)

Arguments

Value

A list

Examples

myEx1Sys <- ConQuestSys()
myEx1Sys_itanal <- getCqItanal(myEx1Sys)
myItanalSummary <- fmtCqItanal(myEx1Sys_itanal)
print(myItanalSummary[[1]])

fmtCqItanalSmry

Description

internal function to produce formatted itanal summary statistics seen at the end of a ConQuest itanal. Note that this function is called by fmtCqItanal and would not usually be called by the user. The returned table uses the library kable and will be formatted based on the users settings.

Usage

fmtCqItanalSmry(cqItanalSmry, valueDecPlace)

Arguments

Value

A data frame.

fmtCqItanalTbl

Description

internal function to produce formatted itanal category statistics tables for a generalised item. Note that this function is called by fmtCqItanal and would not usually be called by the user. The returned table uses the library kable and will be formatted based on the users settings.

Usage

fmtCqItanalTbl(
  cqItanalTbl,
  ptBisFlag,
  textColHighlight,
  valueDecPlace,
  itemName
)

Arguments

Value

A data frame.

genItems

Description

Generates a list of item parameter matrices for use in function like conquestr::genResponses and conquestr::informationWrightMap

Usage

genItems(n, scores = NULL, deltadots, taus, discrims = 1, centre = NULL)

Arguments

Value

A list of item matrices.

See Also

simplef(), genResponses(), browseVignettes("conquestr")

Examples

  myItem <- matrix(c(0, 0, 0, 0, 1, 1, 0, 1), ncol = 4, byrow = TRUE)
  myItems <- list(myItem, myItem)
  myItems[[2]][2, 2] <- -1 # make the second item delta equal to -1
  myResponses <- genResponses(abilities = rnorm(100), itemParams = myItems)

genItems_deltaDots

Description

Internal function to parse deltaDots argument to conquestr::genItems.

Usage

genItems_deltaDots(deltadots, n)

Arguments

Value

A vector of delta dots.

genItems_taus

Description

Internal function to parse taus argument to conquestr::genItems.

Usage

genItems_taus(taus, n)

Arguments

Value

A list

genMissingMCAR

Description

Step 6 of genResponses(). Selects case-item pairs to set to missing, completely at random.

Usage

genMissingMCAR(nCases, nItems, mcarP = 0)

Arguments

Value

A logical cases by items matrix, TRUE where the response is missing.

See Also

genResponses()

genRespInputs

Description

Step 1 of genResponses(). Validates and standardises the inputs used to generate responses.

Usage

genRespInputs(abilities, groups = NULL, itemParams, BMatrix = 1, mcarP = 0)

Arguments

Value

A list with elements abilities (a cases by dimensions double matrix), groups (a factor, or NULL), itemParams (a list of double matrices), itemDim (an integer vector, the ability column used by each item), nCases, and nItems.

See Also

genResponses()

genResponses

Description

Generates response vectors for n cases to i items given known item parameters, person abilities, and (optionally) other inputs.

Generation runs as a sequence of steps. Each step is also available as its own function so it can be checked in isolation:

1. genRespInputs() validates and standardises the inputs.

2. parsePerturbations() validates perturbR and puts each perturbation into a standard form (one row per perturbation).

3. perturbItem() builds the perturbed item parameters for each perturbation.

4. buildPerturbMap() decides which perturbation (if any) applies to each case-item pair, based on groups.

5. Category probabilities are calculated and responses drawn (in C++).

6. genMissingMCAR() sets responses to missing completely at random.

Use debug = TRUE to return the output of every step, and genResponsesProbs() to tabulate the response probabilities used for each case, with and without perturbation.

Usage

genResponses(
  abilities,
  groups = NULL,
  itemParams,
  BMatrix = 1,
  mcarP = 0,
  perturbR = NULL,
  debug = FALSE
)

Arguments

Value

If debug = FALSE (default), a matrix, n cases by i items, of scored item responses. If debug = TRUE, a list with elements:

• responses: the matrix returned when debug = FALSE.

• responsesComplete: responses before MCAR missingness was applied.

• missing: a logical cases by items matrix, TRUE where genMissingMCAR() selected the case-item pair to be missing.

• inputs: the standardised inputs returned by genRespInputs().

• perturbations: a data frame, one row per perturbation, returned by parsePerturbations().

• perturbedItems: a list of perturbed item parameter matrices, one per row of perturbations.

• perturbMap: an integer cases by items matrix returned by buildPerturbMap(). 0 where the case received the unperturbed item, otherwise the row of perturbations that was applied.

• draws: the uniform deviates used to draw each response (NA where the ability is NA).

• probs: a list, one cases by categories matrix per item, of the category probabilities used to draw each response (perturbed where applicable).

• probsBase: as probs, but under the unperturbed item parameters.

References

Adams, R. J., & Wright, B. D. (1994). When does misfit make a difference. In Objective Measurement Theory and Practice (Vol. 2). Ablex Publishing Corporation.

See Also

simplef(), genResponsesProbs(), browseVignettes("conquestr")

Examples

  myItem <- matrix(c(0, 0, 0, 0, 1, 1, 0, 1), ncol = 4, byrow = TRUE)
  myItems <- list(myItem, myItem)
  myItems[[2]][2, 2] <- -1 # make the second item delta equal to -1
  myResponses <- genResponses(abilities = rnorm(100), itemParams = myItems)

  # perturb item 2 for group "b" only, and keep the intermediate data
  myGroups <- factor(sample(c("a", "b"), 100, replace = TRUE))
  myPerturbations <- list(
    list(item = 2L, type = "shift", pivot = 1, group = "b")
  )
  myDebug <- genResponses(
    abilities = rnorm(100), groups = myGroups, itemParams = myItems,
    perturbR = myPerturbations, debug = TRUE
  )
  head(genResponsesProbs(myDebug, items = 2))

Generate item responses for all cases and items (C++ backend of genResponses)

Description

Loops over cases (outer) and items (inner), drawing one uniform deviate per non-missing case-item pair, in the same order as the original R implementation. Debug output reuses the same deviates, so it does not change the responses.

Usage

genResponsesCpp(
  abilities,
  itemParams,
  itemDim,
  perturbItems,
  perturbMap,
  debug = FALSE
)

Arguments

Value

A list with element responses (a cases by items NumericMatrix). When debug is TRUE, also draws (cases by items), and probs and probsBase (lists, one cases by categories matrix per item).

genResponsesProbs

Description

Tabulates the response probabilities used by genResponses() for each case, item, and category, alongside the probabilities under the unperturbed item. Use it to check that perturbations were applied to the intended cases, and by the intended amount.

Usage

genResponsesProbs(x, items = NULL)

Arguments

Value

A data frame with one row per case, item, and category, and columns: case, item, group, theta, perturbation (0 if unperturbed, otherwise the row of x$perturbations applied), category, score, prob (used to draw the response), probBase (under the unperturbed item), draw (the uniform deviate), and response (before MCAR missingness).

See Also

genResponses()

Examples

myItem <- matrix(c(0, 0, 0, 1, 1, 0.5, 0, 1), ncol = 4, byrow = TRUE)
myDebug <- genResponses(
  abilities = rnorm(10), itemParams = list(myItem),
  perturbR = list(list(item = 1L, type = "shift", pivot = 1)), debug = TRUE
)
genResponsesProbs(myDebug)

geom_line_or_smooth

Description

helper functions for ggplot - conditionally creates call to ggplot2::geom_smooth depending on the option linetype in the call to conquestr::plotCCC()

Usage

geom_line_or_smooth(thisData, thisLinetype)

Arguments

Value

a list with a function call to ggplot2::geom_line.

Examples

myExample <- geom_line_or_smooth()

getCqChain

Description

creates a data frame representation of the estimation chain from an MCMC model. For example the Patz estimator in ACER ConQuest. The burn is discarded and only the un-skipped iterations in MCMC chain are retained.

Usage

getCqChain(myCqs)

Arguments

Value

A data frame.

Examples

## Not run: 
getCqChain(ConQuestSys())

## End(Not run)

getCqData

Description

Get data objects from an R object of class ConQuestSys. This function returns person IDs, response data, case estimates, regression and weight data. Each data type is stored as a data frame, and each data frame is a named element of a list.

1. PID,

2. Responses,

3. Estimates,

4. Regression.

Usage

getCqData(mySys)

Arguments

Value

A List of data frames.

See Also

conquestr::ConQuestSys()

Examples

  mySys <- ConQuestSys()
  myData <- getCqData(mySys)

getCqDataDf

Description

Takes a list object returned by conquestr::getCqData and coerces it to a wide data frame. This can sometimes cause issues in complex data, for example where there are multiple response vectors for each case (for example a many-facets model). This is because it is assumed that the data can be reduced to a matrix of gNCases x m variables (where m is the number of id, item, estimate and regression variables in the analysis). For more complex data, the user should use the outputs of conquestr::getCqData to manually merge together a data frame.

Usage

getCqDataDf(cqData)

Arguments

Value

A data frame containing R data frames based on the list objects in the ConQuest system file that has been read in.

See Also

conquestr::ConQuestSys()

conquestr::getCqData

Examples

  mySys <- ConQuestSys()
  myData <- getCqData(mySys)
  suppressWarnings(myDataDf <- getCqDataDf(myData)) # NAs introduced by coercion

getCqEsts

Description

Return ability estimates as a data frame.

Usage

getCqEsts(mySys)

Arguments

Value

A data frame containing ability estimates (missing if not estimated).

getCqFit

Description

creates a data frame representation of the fit of parameters in the item response model

Usage

getCqFit(myCqs)

Arguments

Value

A data frame.

Examples

## Not run: 
getCqFit(ConQuestSys())

## End(Not run)

getCqHist

Description

creates a data frame representation of the iteration history for all parameters.

Usage

getCqHist(myCqs, labelParams = FALSE)

Arguments

Value

A data frame.

See Also

getCqChain() which is a wrapper for this function to use with models estimated by Markov chain Monte Carlo (MCMC) methods.

Examples

myHist <- getCqHist(ConQuestSys(), labelParams = TRUE)
str(myHist)

getCqItanal

Description

helper function to return list of lists, each list relates to one generalised item from an ACER ConQuest itanal output. Each list contains: (1) item-total and item-rest correlations ....

Usage

getCqItanal(sysFile, matrixPrefix = NULL, isDebug = FALSE)

Arguments

Value

A list.

Examples

myItanal <- getCqItanal()
print(myItanal[[1]])

getCqItanalFacility

Description

returns an item facility for each item in itanal object created by ACER ConQuest. For a dichotomously scored Rasch-like item, facility is the percent correct. For a polytomously scored item, or with estimated scores, facility is given by: the sum of the number of cases in each response category, multiplied by the score for that category divided by the sum of all cases responding to the items times the maximum score for the item.

Usage

getCqItanalFacility(itan)

Arguments

Value

A list.

Examples

mySys <- ConQuestSys()
myItan <- getCqItanal(mySys)
getCqItanalFacility(myItan)

getCqItanalSummary

Description

returns an itanal as a data frame in summary format: one row per generalised item with:

• item label

• valid N

• facility (see conquestr::getCqItanalFacility)

• item-rest correlation

• item-total correlation

• fit (infit/weighted MNSQ) if available

• item locations (deltas)

Usage

getCqItanalSummary(itan)

Arguments

Value

A data frame.

Examples

mySys <- ConQuestSys()
myItan <- getCqItanal(mySys)
getCqItanalSummary(myItan)

getCqKeys

Description

internal function to return keys associated with item categories in itanal tables.

Usage

getCqKeys(sysFile)

Arguments

Value

A data frame.

getCqLongLabs

Description

returns a vector of long gin labels returns vector of length 0 if there are no labels used (see command labels in conquest)

Usage

getCqLongLabs(sysFile)

Arguments

Value

A vector.

Examples

## Not run: 
getCqLongLabs(ConQuestSys())

## End(Not run)

getCqParams

Description

creates a data frame representation of the parameters of the model, including both estimated, constrained, and anchored parameters.

Usage

getCqParams(sysFile)

Arguments

Value

A data frame.

Examples

## Not run: 
getCqParams(ConQuestSys())

## End(Not run)

getCqPid

Description

Return PID as a data frame.

Usage

getCqPid(mySys)

Arguments

Value

A data frame containing sequence number and PID (if no PID is declared, this is the sequence number).

getCqResp

Description

Return item responses as a data frame.

Usage

getCqResp(mySys)

Arguments

Value

A data frame containing raw item responses (pre key) and scored item response (post key).

getCqRespModel

Description

produces a table of model parameter estimates, errors, fits, and scaled 2PL estimates if available.

Usage

getCqRespModel(sysFile)

Arguments

Value

A List of data frames. Each data frame is a term in the response model

Examples

## Not run: 
myShowRespMod <- getCqRespModel(conquestr::ConQuestSys())

## End(Not run)

getCqScores

Description

internal function to return scores associated with item categories in itanal tables.

Usage

getCqScores(sysFile)

Arguments

Value

A data frame.

getCqTerms

Description

creates a data frame representation of the terms of the model statement, including interactions.

Usage

getCqTerms(myCqs)

Arguments

Value

A data frame.

Examples

## Not run: 
getCqTerms(ConQuestSys())

## End(Not run)

getCqVars

Description

creates a data frame representation of the variables in the model statement. Note that steps are not variables.

Usage

getCqVars(myCqs)

Arguments

Value

A data frame.

Examples

## Not run: 
getCqVars(ConQuestSys())

## End(Not run)

getCqYData

Description

Return weight and regression data as a data frame.

Usage

getCqYData(mySys)

Arguments

Value

A data frame containing weight and regression data.

getItemMatrix

Description

generates an item matrix. Useful for

Usage

getItemMatrix(responses, itemParams, ...)

Arguments

Value

a data frame.

ginsOnDims

Description

returns a list of length gNDims. Each element of the list contains a vector of the gins on this dim.

Usage

ginsOnDims(sysFile)

Arguments

Value

a list

Examples

## Not run: 
myResult <- ginsOnDims(conquestr::ConQuestSys())

## End(Not run)

guide_remove_groups

Description

helper functions for ggplot - conditionally creates call to ggplot2::guides to remove legends that involve groups when there is no groups in the call to conquestr::plotCCC()

Usage

guide_remove_groups(groups = TRUE)

Arguments

Value

a list with a function call to ggplot2::guides.

Examples

myExample <- guide_remove_groups(TRUE)

guide_remove_linetype

Description

helper functions for ggplot - conditionally creates call to ggplot2::guides to remove legends that involve groups when there is no groups in the call to conquestr::plotCCC()

Usage

guide_remove_linetype(groups = TRUE)

Arguments

Value

a list with a call to ggplot2::guides.

Examples

myExample <- guide_remove_linetype(TRUE)

infoWI

Description

Calculates an index representing the product of a test information function and an ability distribution.

Usage

infoWI(myItems, myAbilities, type = "empirical")

Arguments

Value

A double.

Examples

infoWIOut <- infoWI(runif (10, -2, 3), rnorm(1000, 0, 1))

informationWrightMap

Description

Plots test information function, relative to ability density, and item locations.

Usage

informationWrightMap(
  myItems,
  myAbilities,
  type = "empirical",
  minTheta = NA,
  maxTheta = NA,
  stepTheta = NA,
  scaleInfo = 1,
  plotItemPoints = "deltadots"
)

Arguments

Value

A ggplot2 object.

Examples

myDeltaDots <- data.frame(
  id = c(1:10),
  itemid = paste0("item", 1:10),
  delta = rnorm(10)
)
MyTaus <- data.frame(
  id = c(2L, 10L),
  itemId = NA,
  step = c(1L, 1L),
  tau = rnorm(2)
)
myItemList <- makeItemList(deltaDot = myDeltaDots, tau = MyTaus)
myInfoPlot <- informationWrightMap(myItemList, rnorm(1000, 0, 1), minTheta=-5, maxTheta=5)

isCqConverged

Description

returns true is the ConQuest model has converged normally (system file).

Usage

isCqConverged(myCqs)

Arguments

Value

A boolean.

Examples

## Not run: 
isCqConverged(ConQuestSys())

## End(Not run)

itemInfoAtTheta

Description

Calculates item information at a value of theta given a set of item parameters for one item.

Usage

itemInfoAtTheta(myItem, theta)

Arguments

Examples

anItem <-  matrix(c(0,0,0,1,1,1,0,1), nrow = 2, byrow = TRUE)
itemInfoAtTheta(anItem, 0)

itemInfoOverTheta

Description

Calculates item information over a rage of theta given a set of item parameters. Returns a data frame with item information at a discrete set of values of theta. This is useful for plotting item information functions.

Note this function is redundant - use testInfoOverTheta and pass a single item as a list.

Usage

itemInfoOverTheta(myItem, minTheta = -6, maxTheta = 6, stepTheta = 0.1)

Arguments

Examples

anItem <- matrix(c(0,0,0,1,1,1,0,1), nrow = 2, byrow = TRUE)
itemInfoOverTheta(anItem)

itemListToDeltaDots

Description

Taskes a list of item parameter matricies and returns a data frame containing delta dots. This is mostly an internal function used, for example to plot items on Wright Maps.

Usage

itemListToDeltaDots(myItems)

Value

A data frame including 4 columns:

• id, an integer index reflecting which item this is, in the same order as myItems

• itemid, a string with the names from the items in myItems (NA if item list is not named)

• location, the value of the deta dot

Examples

myItem <- matrix(
  c(
    0, -0.58    ,  0     , 1,  # delta+tau   thurst thresh (gamma)
    1, -0.58    ,  0.776 , 1,  # 0.196       -1.14
    2, -0.58    , -0.697 , 1,  # -1.277      -0.93
    3, -0.58    , -0.629 , 1,  # -1.209      -0.64
    4, -0.58    ,  0.55  , 1   # -0.03        0.25
    ), ncol =4, byrow=TRUE
 )
thrstThrsh(myItem)

itemListToThresholds

Description

Taskes a list of item parameter matricies and returns a data frame containing Thurstonian Thresholds (gammas) for all items. Thurstonian thresholds are the location on the trait/scale at which the cumulative probability of being in category k, or any higher category equals some probability (usually 0.5, the default). Thurstonian thresholds are considered a way of describing the difficulty of polytomously scored items and are usually the value used in visualisations like Wright maps. Thurstonian thresholds can only be calculated for items where response categories are scored such that each category can be placed in an order increasing scores (e.g., no ties as per the Ordered Partition model)

Usage

itemListToThresholds(
  myItems,
  threshP = 0.5,
  minTheta = -20,
  maxTheta = 20,
  convC = 1e-05
)

Arguments

Value

A data frame including 4 columns:

• id, an integer index reflecting which item this is, in the same order as myItems

• itemid, a string with the names from the items in myItems (NA if item list is not named)

• step, which step does this threshold belong?

• location, the value of the threshold

Examples

myItem <- matrix(
  c(
    0, -0.58    ,  0     , 1,  # delta+tau   thurst thresh (gamma)
    1, -0.58    ,  0.776 , 1,  # 0.196       -1.14
    2, -0.58    , -0.697 , 1,  # -1.277      -0.93
    3, -0.58    , -0.629 , 1,  # -1.209      -0.64
    4, -0.58    ,  0.55  , 1   # -0.03        0.25
    ), ncol =4, byrow=TRUE
 )
itemListToThresholds(list(myItem))

itemResp

Description

Returns a probabilistic item response, given one ability and one set of item parameters.

Usage

itemResp(myAblty, myItem)

Arguments

Value

A numeric score, usually an integer in the range 0, 1, 2, ..., k-1. This is taken from the first column of the matrix of item parameters so may also contain a numeric score.

Examples

myItem <- matrix(c(0, 0, 0, 0, 1, 1, 0, 1), ncol = 4, byrow = TRUE)
itemResp(0, myItem)

find the largest common substring in 2 strings

Description

find the largest common substring in 2 strings

Usage

lcs(str1, str2)

Arguments

find the largest common substring in a vector of strings

Description

find the largest common substring in a vector of strings

Usage

lcs_vec(input_strings)

Arguments

makeItemDfs

Description

takes in a list of item matrices and returns a list of data frames each representing the parameters given in the matrices. The return object is suitable to pass into conquestr::makeItemList to construct a lit of matrices where each matrix represent one item's set of item parameters. The structure of the matrix is the same as used in conquestr::simplef (a matrix of k categories by four (category score, delta dot, tau, discrimination)). A common use for this function is turn a list of item matrices into a flat data structure.

Usage

makeItemDfs(itemList)

Arguments

Value

a list.

Examples

nItems <- 10
myItemsDeltaDot <- data.frame(
  id= seq(nItems),
  itemid= NA,
  delta = runif (nItems, -4, 1) # nItems items in range -4,1
)
myItemsList <- conquestr::makeItemList(deltaDot = myItemsDeltaDot)

makeItemList

Description

creates a list of item matrices. Each matrix represent one item's set of item parameters. The structure of the matrix is the same as used in conquestr::simplef (a matrix of k categories by four (category score, delta dot, tau, discrimination)).

Usage

makeItemList(scores = NULL, deltaDot, tau = NULL, discrim = 1)

Arguments

Value

a list.

Examples

nItems <- 10
myItemsDeltaDot <- data.frame(
  id= seq(nItems),
  itemid= NA,
  delta = runif (nItems, -4, 1) # nItems items in range -4,1
)
myItemsList <- conquestr::makeItemList(deltaDot = myItemsDeltaDot)

mleCalc

Description

returns the MLE for each case and asymptotic variance given a fixed set of item parameters. This is done by finding the root of the distance between the observed and expected score at theta. That is, the location where O-E = 0.

Usage

mleCalc(responses, itemParams, ...)

Arguments

Value

a data frame.

myAbilitiesHelper

Description

helper function to return attributes of vector of abilities for use in information function and WI.

Usage

myAbilitiesHelper(myWhat = "ok", myAbilities = NA)

Arguments

Value

A Boolean or a double.

myItemHelper

Description

helper function to return attributes of list of items for use in information function helpers and WI.

Usage

myItemHelper(myWhat = "ok", myItems)

Arguments

Value

A Boolean or a double.

orderItanalCols

Description

internal function to order and rename itanal tables. Called by conquestr::fmtCqItanalTbl Safely orders and renames tables when ndim > 1.

Usage

orderItanalCols(itanalTbl)

Arguments

Value

A data frame.

pX

Description

returns response probabilities for given response x to an item.

Usage

pX(x, probs)

Arguments

Value

a 1 x 1 matrix giving the response probability of x.

Examples

myTheta <- 0
myDelta <- 1.5
k <- 3
a <- 1.25
itemParamX <- seq(0, k-1, 1)
itemParamD <- rep(myDelta, k)
itemParamT <- c(0, -0.5, 0.5)
itemParamA <- rep(a, k)
itemParam <- cbind(itemParamX, itemParamD, itemParamT, itemParamA)
colnames(itemParam)<- c("x", "d", "t", "a")
myProbs <- simplef(myTheta, itemParam)
myProb <- pX(0, myProbs)

parsePerturbations

Description

Step 2 of genResponses(). Validates a list of perturbations and returns it in a standard form.

Usage

parsePerturbations(perturbR, nItems, groups = NULL)

Arguments

Value

A data frame with one row per perturbation and columns item, type, factor (NA for "shift"), pivot, pivotAt (NA for "shift"), shift (0 for "shift"), and group (a list column; NA means all cases).

See Also

genResponses()

perturbItem

Description

Step 3 of genResponses(). Returns the item parameters after applying one perturbation.

Usage

perturbItem(item, type, factor = 1, pivot = 0, pivotAt = "theta", shift = 0)

Arguments

Value

The perturbed item matrix.

See Also

genResponses()

Examples

myItem <- matrix(c(0, 0, 0, 1, 1, 0.5, 0, 1), ncol = 4, byrow = TRUE)
perturbItem(myItem, type = "discrimination", factor = 2, pivot = 0)
# pivot at the item location (0.5), so the location does not move
perturbItem(myItem, type = "discrimination", factor = 2, pivot = 0, pivotAt = "item")

perturbResp

Description

Perturbs a response given specified (item) misfit to implied model.

Usage

perturbResp(ability, item, group, perturbation)

Arguments

Value

A double - the observed response.

See Also

simplef(), genResponses(), perturbItem(), browseVignettes("conquestr")

Examples

myItem <- matrix(c(
  0, 0, 0   , 1,
  1, 1, -0.2, 1,
  2, 1, 0.2 , 1
), ncol = 4, byrow = TRUE)
perturbResp(0, myItem, "bfit", list(1L, "discrimination", 0.5, 0, "bfit"))

plotCCC

Description

Creates a plot of an item characteristic curve (by response category). For a dichotomous item, this will yield a single curve, for polytomous items this will produce a curve for each response category. Note this is not for use with rout files. See the generic function plotRout for plotting rout files.

Usage

plotCCC(
  item,
  abilities,
  responses,
  weights = NULL,
  groups = NULL,
  range = c(-6, 6),
  by = 0.1,
  linetype = "bins",
  bins = 10,
  plotZero
)

Arguments

Value

A ggplot2 object.

Examples

myRout <- ConQuestRout()
myPlot <- plotRout(myRout)
## Not run: 
# if you run the above example you will have an ICC plot in the object `myPlot`.
plot(myPlot)

## End(Not run)

plotCqHist

Description

generates a plot from a history object. Use getCqHist to create a history object from an 'ACER ConQuest' system file.

Usage

plotCqHist(
  myHist,
  centre = TRUE,
  params = c("all"),
  legend = FALSE,
  plotProblems = NULL
)

Arguments

Value

A ggplot2 object.

Examples

## Not run: 
myHistPlot <- plotCqHist(getCqHist(ConQuestSys()))

## End(Not run)

plotDif

Description

Creates a plot (ggplot2 object) of item parameter estimates common to two system files (e.g., a DIF analysis).

Usage

plotDif(mySysToItemDifDf, myScale = "centred", mySuffixes)

Arguments

Value

A ggplot2 object.

See Also

conquestr::sysToItemDifDf()

Examples

mySys1 <- ConQuestSys()
mySys2 <- ConQuestSys()
mySysList <- list(mySys1, mySys2)
myDifDf <- sysToItemDifDf(mySysList, mySuffixes = c("_male", "_female"), myDims = "all")
myDifPlot <- plotDif (myDifDf,myScale = "centred", mySuffixes = c("_male", "_female"))
## Not run: 
# if you run the above example you will have the plot in the object `myDifPlot`.
plot(myDifPlot)

## End(Not run)

plotItemMap

Description

Creates a plot (ggplot2 object) of item parameter estimates and abilities on latent trait. Note this is not for use with rout files. See the method method plotRout.itemMap to the generic function plotRout

Usage

plotItemMap(mySys, myDims = "D1", ginLabs = "short", abilityType = "PV", ...)

Arguments

Value

A ggplot2 object.

Examples

mySys1 <- ConQuestSys()
myItemMap <- plotItemMap(mySys1)
## Not run: 
# if you run the above example you will have the plot in the object `myItemMap`.
plot(myItemMap)

## End(Not run)

plotModelCCC

Description

Creates a plot of a model implied category characteristic curve. Note this is not for use with rout files. See the generic function plotRout for plotting rout files.

Usage

plotModelCCC(item, range = c(-6, 6), by = 0.1, plotZero)

Arguments

Value

A ggplot2 object.

Examples

myItem <- matrix(
  c(
    0, 0, 0, 1,
    1, 1, 0, 1
  ),
  ncol = 4, byrow=TRUE
)
myPlot <- plotModelCCC(myItem)

plotExpected

Description

Creates a plot of an item- or test- expected score curve. If ability estimates are provided, both empirical and model curves are produced. Can optionally handle weights and groups as required. Note this is not for use with rout files. See the generic function plotRout for plotting rout files.

Usage

plotModelExp(
  items,
  range = c(-6, 6),
  by = 0.1,
  bins = NULL,
  abilities = NULL,
  weights = NULL,
  group = NULL,
  scale = FALSE
)

Arguments

Value

A ggplot2 object.

Examples

myItem <- matrix(
  c(
    0, 0, 0, 1,
    1, 1, 0, 1
  ),
  ncol = 4, byrow=TRUE
)
myPlot <- plotModelExp(list(myItem))

plotRout

Description

generates a plot from an 'ACER ConQuest' Rout file. use ConQuestRout to read in an Rout file created by a plot command in 'ACER ConQuest'.

Usage

plotRout(myRout, ...)

## S3 method for class 'TestInfo'
plotRout(myRout, ...)

## S3 method for class 'InformationWithLatentDist'
plotRout(myRout, ...)

## S3 method for class 'ICC'
plotRout(myRout, ...)

## S3 method for class 'MCC'
plotRout(myRout, ...)

## S3 method for class 'TCC'
plotRout(myRout, ...)

## S3 method for class 'Expected'
plotRout(myRout, ...)

## Default S3 method:
plotRout(myRout, ...)

Arguments

Value

A ggplot2 object.

Examples

myRout <- ConQuestRout()
myPlot <- plotRout(myRout)
## to see why we import this, see https://ggplot2.tidyverse.org/articles/ggplot2-in-packages.html

postProcessSys

Description

Post processing of ConQuest system file created by ConQuestSys. Adds names and attributes (e.g., descriptions) to objects in list.

Usage

postProcessSys(sysFile)

Arguments

Value

A list containing the data objects created by 'ACER ConQuest'. Object is of class conQuestSysFile.

See Also

conquestr::ConQuestSys()

postProcess_gLConstraint

Description

internal function to process gLConstraint

Usage

postProcess_gLConstraint(this_gLConstraint, debug)

Arguments

Value

A list containing a documented gLConstraint object

See Also

conquestr::postProcessSys()

postProcess_gNCases

Description

internal function to processing gNCases

Usage

postProcess_gNCases(this_gNCases, debug)

Arguments

Value

A list containing a documented gNCases object

See Also

conquestr::postProcessSys()

pvCor

Description

Weighted Pearson correlations between one measure and one or more other measures, with standard errors from replicate weights and PVs. Each measure may be latent (a set of M plausible values) or manifest (a single observed column). For each PV and each weight the correlation is computed, then combined with Rubin's rules as in pvStat(). See the "Latent and manifest measures" section of pvCorMatrix() for how the two kinds are combined and for important caveats (in particular, conditioning).

With combine = "raw" (default) correlations are combined on the r scale, as in the PISA and TIMSS technical reports. With combine = "fisherZ" each PV/replicate correlation is transformed with atanh(), the variance components are computed on the z scale, and the estimate and confidence limits are back-transformed with tanh(). The reported se is then the delta-method SE on the r scale, zSe * (1 - r^2), and the variance components are on the z scale. The z scale is preferable when correlations are near +/-1, where the r scale is bounded and its sampling distribution is skewed.

Usage

pvCor(
  data,
  pvs,
  vars,
  weight = NULL,
  repWeights = NULL,
  repMethod = c("BRR", "Fay", "JK1", "JK2"),
  by = NULL,
  fayK = 0.5,
  repScale = NULL,
  combine = c("raw", "fisherZ"),
  confLevel = 0.95
)

Arguments

Value

A data frame with one row per variable (and group): variable, estimate, se, samplingVar, imputationVar, ciLower, ciUpper, combine, nPVs, nReps, n; with fisherZ, also zEstimate and zSe. nPVs is 1 when both measures are manifest (the estimate is then an ordinary weighted correlation and imputationVar is 0). imputationVar is B before Rubin's correction (see the "Variance components" section of pvStat()). With combine = "raw", se^2 = samplingVar + (1 + 1/nPVs) * imputationVar. With combine = "fisherZ" the variance components are on the z scale, so the same identity holds for zSe, and se = zSe * (1 - estimate^2). Missing values are deleted pairwise per variable (only cases missing on pvs, the weights, by, or that variable are dropped). This is safe because each row is a separate correlation; use pvCorMatrix() for a matrix, which requires a common set of cases.

Examples

set.seed(2718)
n <- 200
df <- data.frame(ses = rnorm(n), w = runif(n, 1, 3))
for (i in 1:5) df[[paste0("pv", i)]] <- 0.4 * df$ses + rnorm(n)
for (i in 1:5) df[[paste0("pvB", i)]] <- 0.5 * df[[paste0("pv", i)]] + rnorm(n)
for (r in 1:20) df[[paste0("rw", r)]] <- df$w * ifelse(seq_len(n) %% 20 == r - 1, 0, 20 / 19)
# PVs with a manifest variable
pvCor(df, paste0("pv", 1:5), "ses", weight = "w",
      repWeights = paste0("rw", 1:20), repMethod = "JK1")
# PVs with a manifest variable and another latent measure
pvCor(df, paste0("pv", 1:5), list(ses = "ses", B = paste0("pvB", 1:5)),
      weight = "w", repWeights = paste0("rw", 1:20), repMethod = "JK1")

pvCorMatrix

Description

Weighted Pearson correlation matrix of several measures, with standard errors from replicate weights and PVs. Each measure may be latent (a set of M plausible values, e.g., the outcome domains in IELS, PISA or TIMSS) or manifest (a single observed column, e.g., SES or age), so matrices mixing latent and observed variables can be produced.

For each PV draw m and each weight (full-sample and replicates), the full correlation matrix is computed in C++ in one pass over the data. Each element is then combined across the M draws and replicates with Rubin's rules as in pvStat() (see its "Variance components" section).

Usage

pvCorMatrix(
  data,
  pvs,
  weight = NULL,
  repWeights = NULL,
  repMethod = c("BRR", "Fay", "JK1", "JK2"),
  by = NULL,
  fayK = 0.5,
  repScale = NULL,
  combine = c("raw", "fisherZ"),
  confLevel = 0.95,
  format = c("long", "matrix")
)

Arguments

Value

With format = "long", a data frame with columns dim1, dim2, estimate, se, samplingVar, imputationVar, ciLower, ciUpper, combine, nPVs, nReps, n (and zEstimate, zSe with combine = "fisherZ"), plus a leading by column when by is used. With format = "matrix", a list with elements estimate, se, ciLower, ciUpper (D x D symmetric matrices, diagonal 1 for estimate and ciLower/ciUpper, 0 for se), n and latent (a named logical vector, TRUE for latent measures); when by is used, a named list of such lists, one per group.

Cases with a missing value on any measure, weight or by column are dropped (listwise), so all pairs use the same cases.

Latent and manifest measures

Pairing. Latent measures are paired by position: the correlation between latent A and B uses PV1 of A with PV1 of B, PV2 with PV2, and so on. This is appropriate when the PVs for all latent measures were drawn jointly from one multidimensional model (as in ConQuest), so the m-th PV of each comes from the same draw. If the latent measures were scaled in separate (e.g., unidimensional) runs, pairing by position has no special meaning, and the correlation will generally be biased towards zero. A manifest variable is the same in every draw, so its single column is reused for each of the M draws.

Consequently, for each pair of measures:

If no latent measure is given, the result is the ordinary weighted correlation (or covariance) matrix with replicate standard errors.

Conditioning. PVs reproduce the correlation with a background variable without bias only if that variable (or a good proxy for it) was in the population (conditioning) model used to draw them. A correlation between PVs and a manifest variable that was not in the conditioning model is biased towards zero. This cannot be detected from the data; check the scaling documentation of the study.

Single columns. A measure with one column is always treated as manifest. A latent measure must therefore have at least two PVs, and all latent measures must have the same number of PVs.

Validity of the matrix. Every measure is evaluated on the same cases (listwise deletion), so each per-draw matrix is a valid (positive semi-definite) correlation matrix, and so is their average (combine = "raw"). With combine = "fisherZ", elements are back-transformed separately and the matrix is no longer guaranteed to be positive semi-definite; a warning is given if it is not. Covariance matrices from pvCovMatrix() are always averaged on the raw scale.

Degenerate variables. A measure that is constant within a group (e.g., a dummy variable with only one value in that group, or the by variable itself) has no defined correlation; the affected elements are NA and a warning names them.

Examples

set.seed(2718)
n <- 300
df <- data.frame(w = runif(n, 1, 3), ses = rnorm(n))
g <- 0.5 * df$ses + rnorm(n)
for (d in c("LIT", "NUM", "SR")) for (i in 1:5) {
  df[[paste0("PV", i, d)]] <- 0.7 * g + rnorm(n, 0, 0.7)
}
for (r in 1:20) df[[paste0("rw", r)]] <- df$w * ifelse(seq_len(n) %% 20 == r - 1, 0, 20 / 19)
pvList <- lapply(c(lit = "LIT", num = "NUM", sr = "SR"), function(d) paste0("PV", 1:5, d))
pvCorMatrix(df, c(pvList, ses = "ses"), weight = "w",
            repWeights = paste0("rw", 1:20), repMethod = "JK1", format = "matrix")

pvCovMatrix

Description

Weighted covariance matrix of several measures, with standard errors from replicate weights and PVs. Each measure may be latent (a set of M plausible values; e.g., the variances and covariances of the outcome domains in IELS, PISA or TIMSS) or manifest (a single observed column).

As in pvCorMatrix(), for each PV draw and each weight the full D x D covariance matrix is computed in C++; each element is then combined across draws and replicates with Rubin's rules (see the "Variance components" section of pvStat()). The diagonal holds the variance of each measure and matches pvVar() applied to that measure's columns. See the "Latent and manifest measures" section of pvCorMatrix() for how latent and manifest measures are paired, and for caveats about conditioning.

Covariances use the same weighted estimator as pvVar(): sum(w (x - xbar)(y - ybar)) / sum(w) * n / (n - 1), where n is the number of cases with positive weight. Because every element is averaged on the raw scale over the same cases, the combined matrix is positive semi-definite.

Confidence limits are normal approximations. For variances near zero, or with few replicates, they can be poor (and the lower limit can be negative), because the sampling distribution of a variance is skewed.

Usage

pvCovMatrix(
  data,
  pvs,
  weight = NULL,
  repWeights = NULL,
  repMethod = c("BRR", "Fay", "JK1", "JK2"),
  by = NULL,
  fayK = 0.5,
  repScale = NULL,
  confLevel = 0.95,
  format = c("long", "matrix")
)

Arguments

Value

With format = "long", a data frame with columns dim1, dim2 (equal for variances), estimate, se, samplingVar, imputationVar, ciLower, ciUpper, nPVs, nReps, n, plus a leading by column when by is used. With format = "matrix", a list with elements estimate, se, ciLower, ciUpper (D x D symmetric matrices), n and latent; when by is used, a named list of such lists, one per group. imputationVar is B before Rubin's correction, so se^2 = samplingVar + (1 + 1/nPVs) * imputationVar.

Cases with a missing value on any measure, weight or by column are dropped (listwise).

Examples

set.seed(2718)
n <- 300
df <- data.frame(w = runif(n, 1, 3), ses = rnorm(n))
g <- 0.5 * df$ses + rnorm(n)
for (d in c("LIT", "NUM", "SR")) for (i in 1:5) {
  df[[paste0("PV", i, d)]] <- 0.7 * g + rnorm(n, 0, 0.7)
}
for (r in 1:20) df[[paste0("rw", r)]] <- df$w * ifelse(seq_len(n) %% 20 == r - 1, 0, 20 / 19)
pvList <- lapply(c(lit = "LIT", num = "NUM", sr = "SR"), function(d) paste0("PV", 1:5, d))
pvCovMatrix(df, c(pvList, ses = "ses"), weight = "w",
            repWeights = paste0("rw", 1:20), repMethod = "JK1", format = "matrix")

pvDescribe

Description

Standard descriptive statistics (mean, SD, variance, quartiles, IQR) of plausible values with replicate SEs, optionally by group.

Usage

pvDescribe(data, pvs, ...)

Arguments

Value

A data frame stacking the results of pvStat() for each statistic. imputationVar is the between-PV variance B before Rubin's correction, so se^2 = samplingVar + (1 + 1/nPVs) * imputationVar. See the "Variance components" section of pvStat().

pvDiff

Description

Differences in a statistic between levels of a grouping variable (e.g., girls minus boys), with standard errors that account for both sampling (replicate) and imputation (PV) variance. The difference is computed within each PV and each replicate weight, then combined with Rubin's rules, so the covariance between groups induced by the sampling design is accounted for.

Usage

pvDiff(data, pvs, by, pairs = NULL, ...)

Arguments

Value

A data frame with contrast, stat, estimate, se, samplingVar, imputationVar, t (estimate / se). imputationVar is B before Rubin's correction; se^2 = samplingVar + (1 + 1/M) * imputationVar, where M is the number of PVs. See the "Variance components" section of pvStat().

Examples

set.seed(2718)
n <- 200
df <- data.frame(sex = sample(c("boy", "girl"), n, TRUE), w = runif(n, 1, 3))
for (i in 1:5) df[[paste0("pv", i)]] <- rnorm(n)
for (r in 1:20) df[[paste0("rw", r)]] <- df$w * ifelse(seq_len(n) %% 20 == r - 1, 0, 20 / 19)
pvDiff(df, paste0("pv", 1:5), by = "sex", weight = "w",
       repWeights = paste0("rw", 1:20), repMethod = "JK1",
       pairs = list(c("girl", "boy")))

pvIqr

Description

Interquartile range (weighted Q3 - Q1) of plausible values with replicate SEs. See pvStat().

Usage

pvIqr(data, pvs, ...)

Arguments

pvMean

Description

Mean of plausible values with replicate SEs. See pvStat().

Usage

pvMean(data, pvs, ...)

Arguments

pvMedian

Description

Median of plausible values with replicate SEs. See pvStat().

Usage

pvMedian(data, pvs, ...)

Arguments

pvQuantile

Description

Quantiles of plausible values with replicate SEs. See pvStat().

Usage

pvQuantile(data, pvs, probs = c(0.1, 0.25, 0.5, 0.75, 0.9), ...)

Arguments

pvRegression

Description

Weighted linear regression of plausible values on background variables, with standard errors from replicate weights and PVs. For each PV and each weight (full-sample plus replicates) the model is fitted by weighted least squares; coefficients and R-squared are then combined with Rubin's rules as in pvStat(). The heavy lifting is done in C++ (normal equations factored once per weight and reused across PVs).

Usage

pvRegression(
  data,
  pvs,
  formula,
  weight = NULL,
  repWeights = NULL,
  repMethod = c("BRR", "Fay", "JK1", "JK2"),
  by = NULL,
  fayK = 0.5,
  repScale = NULL,
  confLevel = 0.95
)

Arguments

Value

A data frame with one row per term (and group), including "R-squared": term, estimate, se, t, ciLower, ciUpper, samplingVar, imputationVar, nPVs, nReps, n. imputationVar is B before Rubin's correction, so se^2 = samplingVar + (1 + 1/nPVs) * imputationVar (see the "Variance components" section of pvStat()). The R-squared row is the PV-averaged weighted R-squared; treat its SE as approximate since R-squared is bounded.

Examples

set.seed(2718)
n <- 200
df <- data.frame(ses = rnorm(n), sex = sample(c("boy", "girl"), n, TRUE),
                 w = runif(n, 1, 3))
for (i in 1:5) df[[paste0("pv", i)]] <- 0.4 * df$ses + rnorm(n)
for (r in 1:20) df[[paste0("rw", r)]] <- df$w * ifelse(seq_len(n) %% 20 == r - 1, 0, 20 / 19)
pvRegression(df, paste0("pv", 1:5), ~ ses + sex, weight = "w",
             repWeights = paste0("rw", 1:20), repMethod = "JK1")

Methods for pvRegression objects

Description

Standard model methods for objects returned by pvRegression(). When the model was fitted with by, coef(), vcov() and confint() return a list with one element per group, and predict() uses the group-specific model for each row of newdata (which must then contain the by column). Inference uses the normal approximation, as in pvRegression().

Usage

## S3 method for class 'pvRegression'
coef(object, ...)

## S3 method for class 'pvRegression'
vcov(object, ...)

## S3 method for class 'pvRegression'
confint(object, parm, level = 0.95, ...)

## S3 method for class 'pvRegression'
nobs(object, ...)

## S3 method for class 'pvRegression'
predict(object, newdata, se.fit = FALSE, ...)

## S3 method for class 'pvRegression'
print(x, digits = max(3L, getOption("digits") - 3L), ...)

## S3 method for class 'pvRegression'
summary(object, ...)

## S3 method for class 'summary.pvRegression'
print(x, digits = max(3L, getOption("digits") - 3L), ...)

Arguments

Weighted correlation matrices across PV dimensions, per PV and weight

Description

Internal workhorse for pvCorMatrix(). PVs are paired by index across dimensions: the m-th PV of each dimension is used together.

Usage

pvRepCorMatCpp(pv, wts, D, M)

Arguments

Value

A numeric array, P by M by (R + 1), where P = D (D - 1) / 2 and rows are the lower-triangle pairs in column-major order ((2,1), (3,1), ..., (D,1), (3,2), ...).

Weighted covariance matrices across PV dimensions, per PV and weight

Description

Internal workhorse for pvCovMatrix(). PVs are paired by index across dimensions, as in pvRepCorMatCpp(). Covariances use the same n / (n - 1) correction as the weighted variance in pvRepStatCpp(), where n is the number of cases with positive weight.

Usage

pvRepCovMatCpp(pv, wts, D, M)

Arguments

Value

A numeric array, P by M by (R + 1), where P = D (D + 1) / 2 and rows are the lower triangle including the diagonal in column-major order ((1,1), (2,1), ..., (D,1), (2,2), (3,2), ...).

Weighted least squares over PVs and replicate weights

Description

Internal workhorse for pvRegression(). The normal equations are formed and Cholesky-factored once per weight and reused for every PV.

Usage

pvRepRegCpp(X, pv, wts)

Arguments

Value

A numeric array, (p + 1) by M by (R + 1): rows 1..p are the coefficients, row p + 1 is the weighted R-squared.

Compute a weighted statistic over plausible values and replicate weights

Description

Internal workhorse for pvStat(). For each plausible value (column of pv) and each weight vector (the full-sample weight followed by each replicate weight), computes the requested statistic.

Usage

pvRepStatCpp(pv, wts, stat, prob)

Arguments

Value

A numeric matrix, M by (R + 1), of estimates.

pvSd

Description

Standard deviation of plausible values with replicate SEs. See pvStat().

Usage

pvSd(data, pvs, ...)

Arguments

pvStat

Description

Core function for estimating population statistics from plausible values (PVs) with replicate-weight standard errors. The statistic is computed for each PV under the full-sample weight and under each replicate weight. Results are combined using Rubin's rules:

• estimate: mean of the M full-sample PV estimates;

• sampling variance (U): mean over PVs of the replicate variance;

• imputation variance (B): variance of the M full-sample PV estimates;

• total error variance: U + (1 + 1/M) B.

See the "Variance components" section for how the returned columns relate to se.

Replicate variance for one PV is scale * sum((theta_r - theta_0)^2), where scale depends on repMethod:

Usage

pvStat(
  data,
  pvs,
  weight = NULL,
  repWeights = NULL,
  repMethod = c("BRR", "Fay", "JK1", "JK2"),
  stat = "mean",
  by = NULL,
  probs = 0.5,
  fayK = 0.5,
  repScale = NULL
)

Arguments

Value

A data frame with one row per group: group, stat, estimate, se, samplingVar, imputationVar, nPVs, nReps, n. samplingVar is U and imputationVar is B, the between-PV variance before Rubin's (1 + 1/M) correction, so se^2 = samplingVar + (1 + 1/nPVs) * imputationVar, not samplingVar + imputationVar. See "Variance components".

Variance components

The error variance of a PV-based estimate has two sources: sampling (which students were sampled) and measurement (each student's proficiency is uncertain, which is represented by drawing M PVs). The returned columns are:

Why (1 + 1/M) B rather than B. B estimates how much the statistic varies from one PV to another. The reported estimate, however, is the average of only M PV estimates, not the value that would be obtained with infinitely many PVs. That average has its own simulation error, with variance B / M, which must be added to the total. Hence the measurement component is B + B/M = (1 + 1/M) B (Rubin, 1987). Put another way, U + B follows from the law of total variance; the additional B/M term corrects for using a finite number of PVs. The correction matters most when M is small: it adds 20% to B with 5 PVs and 10% with 10 PVs.

Recovering se from the columns.

res <- pvMean(...)
all.equal(res$se,
          sqrt(res$samplingVar + (1 + 1 / res$nPVs) * res$imputationVar))

Computing sqrt(samplingVar + imputationVar) omits the B/M term and so slightly understates the standard error. The share of error variance due to measurement is (1 + 1/M) * B / se^2.

If repWeights is NULL, samplingVar and therefore se are NA; imputationVar is still returned.

Reference: Rubin, D. B. (1987). Multiple Imputation for Nonresponse in Surveys. Wiley.

Examples

set.seed(2718)
n <- 200
df <- data.frame(sex = sample(c("boy", "girl"), n, TRUE), w = runif(n, 1, 3))
for (i in 1:5) df[[paste0("pv", i)]] <- rnorm(n)
for (r in 1:20) df[[paste0("rw", r)]] <- df$w * ifelse(seq_len(n) %% 20 == r - 1, 0, 20 / 19)
pvStat(df, paste0("pv", 1:5), "w", paste0("rw", 1:20), "JK1", "mean", by = "sex")

pvVar

Description

Variance of plausible values with replicate SEs. See pvStat().

Usage

pvVar(data, pvs, ...)

Arguments

Correct Yen's Q3 for its expected value

Description

Shifts the off-diagonal elements of a matrix of residual correlations (Yen's Q_3) so that their expectation under local independence is approximately zero.

Usage

q3ExpCorrect(myCorMat, abilityType = c("ML", "WLE", "EAP", "PV"))

Arguments

Details

Yen's (1984) Q_3 for items i and j is the Pearson correlation, across persons n = 1, \ldots, N, of the raw item residuals

d_{ni} = x_{ni} - E(X_{ni} \mid \hat\theta_n), \qquad Q_{3,ij} = r(d_i, d_j).

Chou and Wang (2010) instead correlate the standardised residuals z_{ni} = d_{ni} / \sqrt{\mathrm{Var}(X_{ni} \mid \hat\theta_n)}. steigerStat() uses whichever residuals it is given.

When abilities are maximum-likelihood (ML) or weighted-likelihood (WLE) estimates from the same responses, the residuals are constrained, and under local independence the expected value of Q_3 is approximately -1/(L-1) rather than 0, where L is the number of items (Yen, 1993; Chou & Wang, 2010). For these abilities the function removes that expectation from every off-diagonal element:

Q_{3,ij}^{*} = Q_{3,ij} + \frac{1}{L-1}, \quad i \neq j.

The diagonal is left at 1. Values pushed outside [-1, 1] are clamped to the boundary.

The -1/(L-1) expectation assumes ML/WLE abilities. EAP estimates are shrunk towards the population mean, and plausible values (PVs) are random draws from each person's posterior. Either way the residuals are less tightly constrained, so the null mean of Q_3 is closer to 0, and adding 1/(L-1) over-corrects and inflates apparent dependence. In a simulated Rasch example (N = 1000, L = 10) the null mean was -0.111 with ML abilities but -0.075 with EAP. For abilityType = "EAP" or "PV" the correction is therefore turned off, and the input is returned unchanged after validation. No analytic expectation is applied for these cases.

Value

A matrix of the same dimensions (and dimnames). For ML/WLE it holds the corrected off-diagonal values Q_{3,ij}^{*}; for EAP/PV it is myCorMat unchanged.

References

Yen, W. M. (1984). Effects of local item dependence on the fit and equating performance of the three-parameter logistic model. Applied Psychological Measurement, 8(2), 125–145. doi:10.1177/014662168400800201

Yen, W. M. (1993). Scaling performance assessments: Strategies for managing local item dependence. Journal of Educational Measurement, 30(3), 187–213. doi:10.1111/j.1745-3984.1993.tb00423.x

Chou, Y.-T., & Wang, W.-C. (2010). Checking dimensionality in item response models with principal component analysis on standardized residuals. Educational and Psychological Measurement, 70(5), 717–731. doi:10.1177/0013164410379322

See Also

fisherTrnsfrm(), steigerStat()

rawScore

Description

returns the adjusted (for zero and perfects) and unadjusted raw scores as well as the maximum score.

Usage

rawScore(x, itemParams, perfAdjust = 0.3)

Arguments

Value

a list containing three elements: (1) raw score (unadjusted), (2) raw score (adjusted), (3) maximum score.

readCharSafe

Description

reads n bytes as raw from a binary connection. Removes any embedded nuls, replacing them with replace.

Usage

readCharSafe(con, n, replace = " ")

Arguments

Value

character vector.

recodeResps

Description

Recode raw item responses for analyses.

Usage

recodeResps(data, recodeMap, varLabel, rawLabel, recodeLabel)

Arguments

Value

a data frame with raw data recoded according to recodeMap.

iterate through a data frame and use replaceInVector

Description

iterate through a data frame and use replaceInVector

Usage

replaceInDataFrame(d, r, x)

Arguments

replace a very large negative number with something - usually NA_REAL

Description

replace a very large negative number with something - usually NA_REAL

Usage

replaceInVector(v, r, x)

Arguments

routPointsToDf

Description

routPointsToDf

Usage

routPointsToDf(myRout)

Arguments

Value

A data frame containing the series that make up the plot

routType

Description

routType

Usage

routType(myRout)

Arguments

Value

A string naming the type of plot

searchConQuestSys

Description

Search for object names within a ConQuest System file object.

Usage

searchConQuestSys(searchString, mySys, value = TRUE, ignore.case = TRUE)

Arguments

Value

a string including object names matching the search term

simplef

Description

returns expected score at a given value of theta.

Usage

simplef(theta, item, model, D)

Arguments

Value

a double - the expected score at theta.

Examples

myTheta <- 0
myDelta <- 1.5
k <- 3
a <- 1
itemParamX <- seq(0, k-1, 1)
itemParamD <- rep(myDelta, k)
itemParamT <- c(0, -0.5, 0.5)
itemParamA <- rep(a, k)
itemParam <- cbind(itemParamX, itemParamD, itemParamT, itemParamA)
colnames(itemParam)<- c("x", "d", "t", "a")
myExpect <- simplef(myTheta, itemParam)

simplep

Description

returns response probabilities for each response category of an item at a given value of theta.

Usage

simplep(theta, item, model = "conquest", D = 1)

Arguments

Value

a k x 1 matrix of response probabilities evaluated at theta.

Examples

myTheta <- 0
myDelta <- 1.5
a <- 1.5
k <- 3
itemParamX <- seq(0, k-1, 1)
itemParamD <- c(0, rep(myDelta, k-1))
itemParamT <- c(0, -0.5, 0.5)
itemParamA <- rep(a, k)
itemParam <- cbind(itemParamX, itemParamD, itemParamT, itemParamA)
colnames(itemParam)<- c("x", "d", "t", "a")
myProbs <- simplep(myTheta, itemParam)

Response probabilities for each category of an item at theta (C++ backend of simplep)

Description

Response probabilities for each category of an item at theta (C++ backend of simplep)

Usage

simplepCpp(theta, item, muraki = FALSE, D = 1)

Arguments

Value

A NumericVector of length k.

Steiger test of local independence of residuals

Description

Tests whether the matrix of item-residual correlations (Yen's Q_3) is consistent with an identity matrix, i.e. whether the standardised residuals are mutually uncorrelated (local independence).

Usage

steigerStat(
  myDat,
  q3Adj = TRUE,
  fisher = TRUE,
  dfAdj = FALSE,
  tpm,
  abilityType = c("ML", "WLE", "EAP", "PV")
)

Arguments

Details

The input is an N \times L matrix of standardised residuals

z_{ni} = \frac{x_{ni} - E(X_{ni})}{\sqrt{\mathrm{Var}(X_{ni})}},

where for a dichotomous item E(X_{ni}) = p_{ni} and \mathrm{Var}(X_{ni}) = p_{ni}(1 - p_{ni}). The steps are:

1. Residual correlations. Rows with any missing value are dropped (listwise deletion) and the Pearson correlation matrix R = [Q_{3,ij}] is computed.

2. Q3 correction (q3Adj = TRUE). For ML/WLE abilities each off-diagonal element is shifted by its approximate null expectation, Q_{3,ij} + 1/(L-1). The correction assumes ML/WLE abilities; for abilityType = "EAP" or "PV" it is turned off. See q3ExpCorrect().

3. Fisher transform (fisher = TRUE). Each off-diagonal element is transformed, z_{ij} = \operatorname{artanh}(r_{ij}); see fisherTrnsfrm().

4. Test statistic. Following Steiger (1980), under H_0: P = I the z_{ij} are approximately independent N(0, 1/(N-3)), so

   \chi^2 = (N - 3) \sum_{i < j} z_{ij}^2

   is referred to a \chi^2 distribution with

   df = \frac{L(L-1)}{2}.

5. Optional df adjustment (dfAdj = TRUE). The degrees of freedom are replaced by the empirical approximation

   df^{*} = \frac{L(L-1)}{2} + \frac{N}{70} - \frac{L}{4} - 12\,t - \frac{N t}{40} + \frac{2 L t}{3},

   where t is the test-person match (tpm). Chou and Wang (2010) found that, even after the -1/(L-1) correction, the Type I error rate of the Steiger statistic remained inflated in some conditions (e.g., large samples and short tests). They derived this adjustment by stepwise regression on simulated data as a simple correction that works reasonably well across a variety of conditions. The coefficients are therefore an empirical calibration, not an analytic result, and are best trusted within the range of conditions they simulated. The adjustment applies only to the Steiger statistic.

   The calibration data were 32 null (Rasch-generating, Rasch-analysed) conditions with 100 replications each: dichotomous items only, test lengths L \in \{10, 20, 40, 60\}, sample sizes N \in \{100, 200, 500, 1500\}, and test-person match t \in \{0, -1\}, where t is mean item difficulty minus mean person ability (item difficulties drawn from U(-2, 2), abilities normal with variance 1). The response variable was the observed \chi^2 minus its nominal df, regressed on N, L, t and their interactions. Even with the adjustment, Type I error stayed above the acceptable range in a few conditions, most notably N = 1500, L = 10, t = -1 (Chou & Wang, 2010, Table 4). Results outside these ranges (e.g., t > 0, polytomous items, or N > 1500) are extrapolations. The calibration also used ML-type (Winsteps) abilities with the -1/(L-1) correction applied, so with EAP or PV residuals the adjustment is untested.

If fisher = FALSE the statistic is computed from the untransformed correlations, which is only a reasonable approximation when all correlations are small.

Value

A list with elements:

• Cor: the (corrected and/or transformed) residual correlation matrix;

• steigerStat: the \chi^2 statistic;

• Chisq_p: the upper-tail p-value;

• Chisq_crit: the 95th percentile of the reference \chi^2;

• N, L, DF: number of persons, items and degrees of freedom.

References

Steiger, J. H. (1980). Tests for comparing elements of a correlation matrix. Psychological Bulletin, 87(2), 245–251. doi:10.1037/0033-2909.87.2.245

Fisher, R. A. (1915). Frequency distribution of the values of the correlation coefficient in samples from an indefinitely large population. Biometrika, 10(4), 507–521. doi:10.2307/2331838

Yen, W. M. (1984). Effects of local item dependence on the fit and equating performance of the three-parameter logistic model. Applied Psychological Measurement, 8(2), 125–145. doi:10.1177/014662168400800201

Chou, Y.-T., & Wang, W.-C. (2010). Checking dimensionality in item response models with principal component analysis on standardized residuals. Educational and Psychological Measurement, 70(5), 717–731. doi:10.1177/0013164410379322

See Also

q3ExpCorrect(), fisherTrnsfrm()

summariseCqChain

Description

takes a data frame created by getCqChain and returns a list reporting the mean and variance for each parameter

Usage

summariseCqChain(myChain)

Arguments

Value

A list.

Examples

## Not run: 
summariseCqChain(getCqChain(ConQuestSys()))

## End(Not run)

sysFileOk

Description

checks

Usage

sysFileOk(sysFile, defaultSys)

Arguments

Examples

## Not run: 
sysFileOkResult <- sysFileOk(conquestr::ConQuestSys())

## End(Not run)

sysToBMatrixDf

Description

Read an R object of class ConQuestSys and create a labelled representation of the B matrix (scoring matrix). This maps item response categories to items and dimensions. Returns long data frame, where items are duplicated if they are in many dimensions.

Usage

sysToBMatrixDf(mySys, applyLabels = TRUE)

Arguments

Value

A data frame containing R the labelled B matrix.

Examples

myBMatrix <- sysToBMatrixDf(ConQuestSys())
## Not run: 
# if you run the above example you will have the B Matrix from the example system file.
str(myBMatrix)

## End(Not run)

sysToDimLabels

Description

Gets dimensions labels from a ConQuest system file.

Usage

sysToDimLabels(mySys, myWarn = TRUE)

Arguments

Value

a data frame.

See Also

conquestr::sysToBMatrixDf()

sysToItemDifDf

Description

Creates a data frame that includes the common item parameter estimates from two (or more) system files (e.g., a DIF analysis).

Usage

sysToItemDifDf(listOfSysFiles, mySuffixes, myDims = "all")

Arguments

Value

A data frame object.

See Also

conquestr::plotDif ()

sysToItemLabels

Description

Gets item labels from a ConQuest system file.

Usage

sysToItemLabels(mySys, myWarn = TRUE)

Arguments

Value

a data frame.

See Also

conquestr::sysToBMatrixDf()

sysToItems

Description

Read an R object of class ConQuestSys and create a labelled representation of the B matrix (scoring matrix). This maps item response categories to items and dimensions.

Usage

sysToItems(mySys, myDims)

Arguments

Value

A data frame containing R the labelled B matrix.

See Also

conquestr::sysToItemDifDf()

testInfoAtTheta

Description

Calculates test information at a value of theta given a list of matricies of item parameters for one or more items.

Usage

testInfoAtTheta(myItems, theta)

Arguments

Examples

anItem <- matrix(c(0,0,0,1,1,1,0,1), nrow = 2, byrow = TRUE)
testInfoAtTheta(list(anItem), 0)

testInfoOverTheta

Description

Calculates test information over a range of theta given a list of matricies of item parameters for one or more items. Returns a data frame with item information at a discrete set of values of theta. This is useful for plotting test information functions.

Usage

testInfoOverTheta(myItems, minTheta = -6, maxTheta = 6, stepTheta = 0.1)

Arguments

Examples

anItem <- matrix(c(0,0,0,1,1,1,0,1), nrow = 2, byrow = TRUE)
testInfoOverTheta(list(anItem))

thetaScore

Description

Return score (O-E) at theta. Used in estimation of theta by minimising raw score - expected score at theta

Usage

thetaScore(theta, responses, itemParams, perfAdjust = 0.3)

Arguments

Value

a double, the score (O-E) at theta.

theta_ll

Description

returns the log of the likelihood of theta, given a vector of item responses, item parameters. Note that this is the simple ll - it is the continuing product of the response probabilities. It includes a hack, that will nudge the raw response to the first item to adjust for zeros and perfects. This should be updated to work with adjusted raw scores instead...

Usage

theta_ll(theta, responses, itemParams)

Arguments

Value

a double, the log of the likelihood at theta..

thrstThrsh

Description

Generates Thurstonian Thresholds (sometimes called gammas) to an item. Thurstonian thresholds are the location on the trait/scale at which the cumulative probability of being in category k, or any higher category equals some probability (usually 0.5, the default). Thurstonian thresholds are considered a way of describing the difficulty of polytomously scored items and are usually the value used in visualisations like Wright maps. Thurstonian thresholds can only be calculated for items where response categories are scored such that each category can be placed in an order increasing scores (e.g., no ties as per the Ordered Partition model)

Usage

thrstThrsh(myItem, threshP = 0.5, minTheta = -20, maxTheta = 20, convC = 1e-05)

Arguments

Value

A k-1 by 1 matrix with Thurstonian thresholds for this item. Values are NA when the threshold cannot be calculated.

Examples

myItem <- matrix(
  c(
    0, -0.58    ,  0     , 1,  # delta+tau   thurst thresh (gamma)
    1, -0.58    ,  0.776 , 1,  # 0.196       -1.14
    2, -0.58    , -0.697 , 1,  # -1.277      -0.93
    3, -0.58    , -0.629 , 1,  # -1.209      -0.64
    4, -0.58    ,  0.55  , 1   # -0.03        0.25
    ), ncol =4, byrow=TRUE
 )
thrstThrsh(myItem)

transformPvs

Description

Helper function to Transform PVs onto a new metric (e.g., PISA Mean = 500, SD = 100). Uses the method described in the PISA 2012 technical manual.

Usage

transformPvs(data, mT = 0, sdT = 1, weights = 1)

Arguments

Value

a List of transformed PVs with as many elements as PVs were listed in 'x'.

writeImportXsi

Description

Writes a fixed width text file in the format required for the ACER ConQuest command and argument ⁠import anchor_xsi⁠. Can also be used for initial values, though caution should be used with the interpretation of the argument lconstraint which should relate to the model of interest ACER ConQuest

Currently only works with implicit variables. Explicit variables may be added in the future.

Usage

writeImportXsi(items, bmatix = 1L, lconstraint = "none", file)

Arguments

See Also

simplef(), genResponses(), browseVignettes("conquestr")

Examples

  myItem <- matrix(c(0, 0, 0, 0, 1, 1, 0, 1), ncol = 4, byrow = TRUE)
  myItems <- list(myItem, myItem)
  myItems[[2]][2, 2] <- -1 # make the second item delta equal to -1
  myResponses <- genResponses(abilities = rnorm(100), itemParams = myItems)

zapNulls

Description

Zaps NULL values embedded in ConQuest data objects.

Usage

zapNulls(x)

Arguments

Value

x.

zapSystemMissing

Description

Coerce ConQuest system missing values to NA. Note this is very slow and users should use the internal function conquestr::replaceInDataFrame where possible.

Usage

zapSystemMissing(x)

Arguments

Value

x