CutoffIpr: Cut-off points for Ipr generated estimates
In DFIT: Differential Functioning of Items and Tests

Description Usage Arguments Value Author(s) References Examples

Calculates a given quantile cut-off point for each item on the IPR estimated items statistics. This function may produce the cut-off points for the NCDIF index, Signed and Unsigned Area Measures and the Mantel-Haenszel statistic based on the Monte Carlo Item parameter replication approach. The quantiles may be calculated directly on the output from the IprNcdif, IprSam, IprUam, and IprMh functions; the may be calculated by obtaining the corresponding statistics for the item parameters simulated under the IPR approach; or by obatining both the simulated item parameters and the statistics based on the item parameter values and their corresponging covariance matrices for the parameter estimates. In the latter case, the user may choose to obtain the IPR simulated item parameters based only on the focal group's covariance matrix as proposed by Oshima et al. (2006), or both focal and reference groups' matrices as proposed by Cervantes (2012).

CutoffIpr(
  iprStatistics = NULL,
  quantiles,
  statistic = "ncdif",
  itemParameterList = NULL,
  irtModel = "2pl",
  focalAbilities = NULL,
  focalDistribution = "norm",
  focalDistrExtra = list(mean = 0, sd = 1),
  referenceDistribution = "norm",
  referenceDistrExtra = list(mean = 0, sd = 1),
  groupRatio = 1,
  subdivisions = 5000,
  logistic = TRUE,
  itemParameters = NULL,
  itemCovariances = NULL,
  nullGroup = NULL,
  focalSampleSize = NULL,
  referenceSampleSize = NULL,
  nReplicates = 5000
)

`iprStatistics`	A numeric matrix with the statistics obtained for the simulated IPR item parameters or a list containing all the elements of the output of this function. If not NULL they will be used for calculating the cut-off points.
`quantiles`	A numeric vector with the quantiles to be calculated.
`statistic`	A character indicating which statistic will the cut-off point will be obtained for. If iprStatistics are provided, it is up to the user to correctly especify this string for it will only be informative; otherwise, it will be used to identify the statistic to be calculated. Should be one of "ncdif", "sam", "uam" or "mh".
`itemParameterList`	A list where each element is a list containing "focal" and "reference" item Parameters. Item parameters are assumed to be on the same scale. Item parameters for each group should be a matrix with nrow equal to the number of items. Not used if iprStatistics are not NULL. If itemParameterList is not NULL, the statistic indicated with the argument "statistic" will be obtained for the set of itemParameterList, the corresponding arguments may be provided.
`irtModel`	A string stating the irtModel to be used. Should be one of "1pl", "2pl", "3pl", "grm" or "pcm". Not used if iprStatistics are not NULL.
`focalAbilities`	Only used if statistic is "ncdif". If NULL, NCDIF is calculated by numerical integration of focal distribution. If not NULL, must be a numerical vector containing the abilities for the individuals in the focal group.
`focalDistribution`	A string stating the distribution assumed for the focal group. Not used if iprStatistics are not NULL.
`focalDistrExtra`	A list stating the extra parameters needed by the focal distribution function. Not used if iprStatistics are not NULL.
`referenceDistribution`	A string stating the distribution assumed for the reference group. Not used if iprStatistics are not NULL.
`referenceDistrExtra`	A list stating the extra parameters needed by the reference distribution function. Not used if iprStatistics are not NULL.
`groupRatio`	A positive value indicating how many members of the reference group are expected for each member of the focal group. Only used if iprStatistics are NULL and statistic is "mh".
`subdivisions`	A numeric value indicating the number of subdivisions for numerical integration. Only used if focalAbilities and iprStatistics are NULL.
`logistic`	A logical value stating if the IRT model will use the logistic or the normal metric. Defaults to using the logistic metric by fixing the D constant to 1. If FALSE the constant is set to 1.702 so that the normal metric is used.
`itemParameters`	A list containing "focal" and "reference" item parameters. Item parameters are assumed to be on the same scale. Item parameters for each group should me a matrix with nrow equal to the number of items. Only used if both iprStatistics and itemParameterList are NULL. If used an itemParameterList from applying the IPR procedure will be simulated and the "statistic" will be calculated.
`itemCovariances`	Either a list containing "focal" and "reference" lists of matrices of covariance for item estimates or the string "asymptotic". Defaults to NULL. Only used if iprStatistics and itemParameterList are NULL, in all other cases the itemCovariances element of the returned list is equal to what is provided as value for these arguments.
`nullGroup`	If different from NULL and itemParameterList is NULL, a string equal to 'focal' or 'reference' to indicate which set of item parameters from itemParameters should be taken for the null hypothesis. If equal to NULL, itemParameterList will be generated using the given itemParameters for both groups.
`focalSampleSize`	A positive integer indicating the size of the focal group. Only used if itemCovariances is 'asymptotic'. Defaults to NULL.
`referenceSampleSize`	A positive integer indicating the size of the reference group. Only used if itemCovariances is 'asymptotic'. Defaults to NULL.
`nReplicates`	A numeric value indicating the number of replications to perform. Only used if iprStatistics and itemParameterList are NULL.

cutoff A list containing: 'itemParameters', NULL if not provided as argument, 'itemCovariances', NULL if not provided as argument, 'itemParameterList', NULL unless calculated from 'itemParameters' or provided as argument, 'iprStatistics' the matrix of 'statistics' provided as argument or calculated from 'itemParameterList', 'statistic' for which the IPR approach is used according to the provided argument, 'quantiles' the vector or matrix of calculated quantiles for each item

Victor H. Cervantes <vhcervantesb at unal.edu.co>

Cervantes, V. H. (2012). On using the Item Parameter Replication (IPR) approach for power calculation of the noncompensatory differential item functioning (NCDIF) index (pp. 206-207). Proceedings of the V European Congress of Methodology. Santiago de Compostela, Spain: Universidade de Santiago de Compostela.

Cervantes, V. H. (2017). DFIT: An R Package for Raju's Differential Functioning of Items and Tests Framework. Journal of Statistical Software, 76(5), 1-24. doi:10.18637/jss.v076.i05

Oshima, T., Raju, N. & Nanda, A. (2006). A new method for assessing the statistical significance in the Differential Functioning of Items and Tests (DFIT) framework. Journal of educational measurement, 43(1), 1–17. doi:10.1111/j.1745-3984.2006.00001.x

Raju, N. (1988). The area between two item characteristic cureves. Psychometricka, 53(4), 495–502. doi:10.1007/bf02294403

Roussos, L., Schnipke, D. & Pashley, P. (1999). A generalized formula for the Mantel-Haenszel Differential Item Functioning parameter. Journal of educational and behavioral statistics, 24(3), 293–322. doi:10.3102/10769986024003293

# # Not run
# #
# # data(dichotomousItemParameters)
# # threePlParameters <- dichotomousItemParameters
# # isNot3Pl          <- ((dichotomousItemParameters[['focal']][, 3] == 0) |
# #                       (dichotomousItemParameters[['reference']][, 3] == 0))
# #
# # threePlParameters[['focal']]          <- threePlParameters[['focal']][!isNot3Pl, ]
# # threePlParameters[['reference']]      <- threePlParameters[['reference']][!isNot3Pl, ]
# # threePlParameters[['focal']][, 3]     <- threePlParameters[['focal']][, 3] + 0.1
# # threePlParameters[['reference']][, 3] <- threePlParameters[['reference']][, 3] + 0.1
# # threePlParameters[['focal']][, 2]     <- threePlParameters[['focal']][, 2] + 1.5
# # threePlParameters[['reference']][, 2] <- threePlParameters[['reference']][, 2] + 1.5
# # threePlParameters[['focal']]          <- threePlParameters[['focal']][-c(12, 16, 28), ]
# # threePlParameters[['reference']]      <- threePlParameters[['reference']][-c(12, 16, 28), ]
# #
# # threePlAse <- list()
# # threePlAse[["focal"]]     <- AseIrt(itemParameters = threePlParameters[["focal"]],
# #                                     logistic = TRUE,
# #                                     sampleSize = 10000,
# #                                     irtModel = "3pl")
# # threePlAse[["reference"]] <- AseIrt(itemParameters = threePlParameters[["reference"]],
# #                                     logistic = TRUE,
# #                                     sampleSize = 15000,
# #                                     irtModel = "3pl")
# #
# # set.seed(41568)
# #
# # threePlIprCutoff <- CutoffIpr(itemParameters = threePlParameters,
# #                               itemCovariances = threePlAse, nullGroup = 'focal',
# #                               nReplicates = 1000, statistic = 'ncdif', irtModel = '3pl')