# kcirt.fitMSS: Metaheuristic k-Cube Thurstonian IRT Fitting In kcirt: k-Cube Thurstonian IRT Models

## Description

Use metaheuristic stochastic search to locate k-Cube Thurstonian IRT hyperparameters and states.

## Usage

 ```1 2 3``` ```kcirt.fitMSS(model, lambdaConstraint = "self", kcpus = 2, penalty = "logit", usetruesigma = TRUE, mss.sd = 0.2, nsearch = 19, l2zvarpow = 0, xmu.shrink=0, xlambda.shrink=0, xeta.shrink=0.4) ```

## Arguments

 `model` A kcirt model; a named list of `class` "kcube.irt.model". `lambdaConstraint` Scalar string specifying how to constrain Lambda during fitting. See Details. `kcpus` Scalar positive integer telling `snowfall` how many threads to initialize. Set to 1 for no parallel processing. `penalty` Scalar string. How to measure quality of fit? Currently either 'logit', 'L2', 'L2c', 'miscat'. `usetruesigma` Scalar boolean. Use actual (assumed) system variance? `mss.sd` Scalar positive number or vector of length 3. Size of search function standard deviation for, in order, `mu`, `Lambda`, and `Eta` searches. `nsearch` Scalar positive integer. How many candidate values to draw from under the MSS function. Typically 14-20. `l2zvarpow` Scalar positive integer. Only used when `penalty` is 'L2c'. Power by which to raise `var(2*Y-1)`; the amount of 'smoothing' to impose on `2*Y-1`. Note that when zero, setting `penalty` to 'L2c' produces identical results to 'L2' – though slightly slower computationally. `xmu.shrink` Scalar non-negative real-valued. Only used when `penalty` is 'logit'. How much to shrink utility estimates towards zero. `xlambda.shrink` Scalar non-negative real-valued. Only used when `penalty` is 'logit'. How much to shrink loading estimates towards zero. `xeta.shrink` Scalar non-negative real-valued. Only used when `penalty` is 'logit'. How much to shrink state predictions towards zero.

## Details

Note: As of kcirt version >= 0.6, the argument `logitshrinkcoef` has been removed. Use `xeta.shrink` instead. lambdaConstraint defines the model k-cube, i.e., the item crosstalk space. Currently accepts `self`, only diagonal elements of `Lambda`; `withinx`, additionally includes within block items pointing to exogenous constructs; `withini`, additionally includes items within block pointing to same construct. `betweenx`, diagonal elements and all other items that point to different constructs; `betweeni`, additionally includes items that point to same construct. `priorx` is similar to `betweenx` except that only previous items crosstalk with item, i.e., `Lambda` is lower-block-diagonal; `priori` additionally permits crosstalk between prior items pointing to same construct.

penalty defines the objective function to be minimized. `logit` minimizes the logistic deviance. `L2` minimizes sum of squares between `2*Y-1` and `2*Yhat-1`. `L2c` is similar to `L2`, except that it pre-projects (up to a constant) `2*Y-1` and `2*Yhat-1` using `var(2*Y-1)`. Note that `NA` values in `Y` are replaced with 0.5. Finally, `miscat`, minimizes the misclassification rate using a confusion table between the observations, `Y`, and the predicted states (scales), `hatEta`, split at zero.

Excepting very adventurous explorations with this model, the defaults for lambdaConstraint and penalty will likely best serve the user.

## Value

A kcirt model. A named list of `class` 'kcube.irt.model'.

## Author(s)

Dave Zes, Korn/Ferry International

See Also `kcirt.fitEE`.
 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45``` ```constructMap.ls <- list( c(1,1,2,2), c(1,1,3,3), c(2,2,3,3), c(1,1,2,2), c(1,1,3,3), c(2,2,3,3), c(1,2), c(2,3), c(1,3) ) qTypes <- rep("R", length(constructMap.ls)) mod <- kcirt.model(constructMap.ls=constructMap.ls, qTypes=qTypes, mxLambda=NULL) N <- 200 set.seed(99999) mod <- kcirt.sim(model=mod, N=N) ikcirt.df1(mod, "self") ####### create initial guess for hyperparameters (aka loadings) mod\$mxHatLambda <- mod\$mxLambda - matrix( rnorm( sum(mod\$ns)^2, 0, 0.3 ), sum(mod\$ns), sum(mod\$ns) ) ####### need to assign hat states and utilities mod\$mxHatEta <- matrix(0, N, sum(mod\$nuc)) mod\$hatMu <- rep(0, sum(mod\$ns)) ## Not run: ###### run MSS fit -- performance is R^2 btwn true and pred states (aka scales) mod <- kcirt.fitMSS(model=mod, lambdaConstraint="self", kcpus=2, penalty="L2", usetruesigma=TRUE, mss.sd=1) mod\$performance ###### run again ... mod <- kcirt.fitMSS(model=mod, lambdaConstraint="self", kcpus=2, penalty="L2", usetruesigma=TRUE, mss.sd=1) mod\$performance ###### run a few more times ... ... ## End(Not run) ```