Package 'mstATA'

Analytic classification accuracy and consistency for MST panels

Description

Once the analytical CSEMs are derived based on recursion-based approach (Lim, 2000), the evaluation of MST performance using classification metrics can be estimated using Rudner's method (2000,2005). The implementation follows the same logic as irtQ::cac_rud().

Usage

analytic_mst_classification(decision_theta_cuts, eval_tb, theta_weight)

Arguments

decision_theta_cuts	Numeric vector of classification cut theta values. These define $K+1$ ordered classification levels.
eval_tb	A data frame containing at least the columns theta and csem. It can be created by analytic_mst_precision().
theta_weight	A data frame containing the population distribution over the ability grid. It must have the following columns: theta Numeric ability grid. This must match eval_tb$theta exactly. w Non-negative population weights corresponding to each ability value. The theta_weight object can be generated using gen_weight().

Details

This function evaluates classification performance without simulation. Given a set of decision cuts and conditional standard errors across a fixed ability grid, classification accuracy and consistency are computed analytically by integrating conditional classification probabilities over a population ability distribution.

The procedure consists of the following steps:

1. Define true classification levels: Each ability value $\theta$ on the evaluation grid is assigned to a true classification level based on the specified cut theta values.

2. Compute conditional classification probabilities: For each $\theta$, the probability of being classified into each level is computed assuming a normal distribution for the reported ability estimate:

   $\hat{\theta} \mid \theta \sim \mathcal{N}(\theta,\ CSEM(\theta)^2).$

3. Conditional accuracy and consistency:

   Conditional classification accuracy is defined as

   $P(\hat{C} = C \mid \theta)$

   where $C$ is the true classification level.

   Conditional consistency is defined as

   $\sum_k P(\hat{C} = k \mid \theta)^2$

   representing the probability that two independent parallel administrations yield the same classification.

4. Marginalization over the population:

   Conditional indices are integrated over a population ability distribution using externally supplied weights, yielding marginal classification accuracy, marginal classification consistency, and a confusion matrix.

Value

A list with the following components:

confusion

A matrix giving the joint probability of true and expected classification levels. Rows correspond to true levels; columns correspond to expected levels.

marginal

A data frame of marginal classification accuracy and consistency by true level, including an overall (marginal) row.

conditional

A data frame of conditional accuracy and consistency at each ability value $\theta$.

prob.level

A data frame of conditional classification probabilities for each level at each $\theta$.

cutscore

The classification cut theta values used in the analysis.

Mathematical Formulation

Let $\theta_i$ denote an ability grid point and $CSEM(\theta_i)$ the corresponding conditional standard error. For classification cut scores $c_1, \dots, c_K$, define level boundaries $(-\infty, c_1, \dots, c_K, \infty)$.

The probability of classifying an examinee with true ability $\theta_i$ into level $k$ is

$P(\hat{C} = k \mid \theta_i)$

$= \Phi(\frac{(u_k - \theta_i)}{CSEM(\theta_i)}) - \Phi(\frac{(\ell_k - \theta_i)}{CSEM(\theta_i)})$

where $(\ell_k, u_k)$ is the interval for level $k$.

Conditional accuracy at $\theta_i$ is

$P(\hat{C}=C \mid \theta_i)$

and conditional consistency is

$\sum_{k=1}^{K+1} P(\hat{C}=k \mid \theta_i)^2$

Let $w(\theta_i) \ge 0$ be population weights on the grid, with $\sum_{i=1}^{I} w(\theta_i)=1$.

The marginal (population) indices are the discrete weighted averages of the conditional quantities:

$MarginalAccuracy = \sum_{i=1}^{I} w(\theta_i) P(\hat{C} = C(\theta_i) \mid \theta_i)$

where $C(\theta_i)$ is the true level implied by $\theta_i$ and the cut scores.

$MarginalConsistency =\sum_{i=1}^{I} w(\theta_i) \sum_{k=1}^{K+1} P(\hat{C} = k \mid \theta_i)^2$

If $w(\theta_i)$ approximates a density $g(\theta)$, these correspond to the integrals $\int g(\theta)\,\cdot\, d\theta$.

References

Rudner, L. M. (2000). Computing the expected proportions of misclassified examinees. Practical Assessment, Research, and Evaluation, 7(1). doi:10.7275/an9m-2035

Rudner, L. M. (2005). Expected classification accuracy. Practical Assessment, Research, and Evaluation, 10(1). doi:10.7275/56a5-6b14

---

Evaluate MST designs via recursive score-distribution propagation

Description

Computes conditional bias and conditional standard error of measurement (CSEM) for a multistage test (MST) panel using a recursion-based evaluation method. The implementation follows the logic of irtQ::reval_mst(), propagating score distributions stage by stage conditional on true ability $\theta$, applying routing rules, and mapping final scores to reported ability estimates via inverse test characteristic curves (TCCs).

Usage

analytic_mst_precision(
  design,
  exclude_pathways = NULL,
  assembled_panel,
  item_par_cols,
  model_col,
  D = 1,
  theta = seq(-3, 3, 0.1),
  range_tcc = c(-5, 5),
  rdps,
  tol = 1e-04
)

Arguments

design	A character string specifying the MST design. The string encodes the number of modules per stage and may use commas, dashes, or slashes as separators. For example, "1-3-3", "1,3,3", and "1/3/3" all define an MST with 1 module in stage 1, 3 modules in stage 2, and 3 modules in stage 3.
exclude_pathways	Optional character vector specifying disallowed pathways. Each element must be a string of the form "x-y-z", where each number refers to a module index at the corresponding stage. If NULL (default), all pathways implied by the design are allowed. This option is commonly used to prohibit extreme routing transitions (e.g., from very easy to very hard modules).
assembled_panel	A "mstATA_panel" object returned by assembled_panel(). All panels share identical module and pathway structure.
item_par_cols	A named list defining the IRT parameter columns required for each supported model. The list names must exactly match the model identifiers specified in model_col column: "1PL", "RASCH", "2PL", "3PL","4PL", "GRM", "MGRM", "PCM", "GPCM", "RSM", and "NRM". Each list element is a character vector giving the column names that contain the required item parameters for the corresponding model.
model_col	A character string specifying the column name in either assembled_panel$ItemsInModules or assembled_panel$ItemsInPathways data frames that indicates the IRT model used for each item. Values in this column must correspond to the supported model names: "1PL", "RASCH", "2PL", "3PL","4PL", "GRM", "MGRM", "PCM", "GPCM", "RSM", and "NRM".
D	Scaling constant used in the IRT model. Default is D=1 (for logistic metric); D=1.702 yields approximately the normal metric.
theta	Numeric vector specifying the ability grid used to construct ICCs. Defaults are -3 to 3 with 0.1 interval.
range_tcc	Numeric vector giving the search interval for inverse TCC evaluation (length = 2). Defaults is (-5,5).
rdps	List of routing cuts on the theta scale.
tol	A convergence tolerance used for inverse TCC calculations. Default is 1e-4.

Details

1. Recursion-based analytic evaluation

The analytic evaluation proceeds in four conceptual steps:

1. Module score distributions

   For each module, the conditional score distribution $P(S_m \mid \theta)$ is computed from item response category probabilities.

2. Stage-wise recursion with routing

   Joint (cumulative) score distributions are built recursively across stages. At each stage, examinees are deterministically assigned to next-stage modules based on the comparison between their ITCC estimates and the predefined cut points for that stage.

3. Exact joint score propagation

   For each valid routing branch, the cumulative score distribution is updated by convolving the previous-stage score distribution with the score distribution of the next module.

4. Inverse TCC and conditional moments

   Final pathway-specific score distributions are mapped to reported ability estimates via inverse test characteristic curves (ITCCs). The conditional mean, conditional bias and conditional variance (CSEM) are computed at each true ability value $\theta$.

2. Conditional bias and conditional SEM

Let $S$ denote the cumulative test score and $\hat \theta(S)$ the ITCC estimator.

For each true ability value $\theta$, this function computes:

$\mu(\theta) = E(\hat{\theta} \mid \theta)$

$\sigma^2(\theta) = Var(\hat{\theta} \mid \theta)$

where the expectation is taken with respect to the exact joint score distribution induced by the MST routing rules.

Value

A list with components:

prefix_table

prefix-to-module lookup tables by stage.

eq_theta

ITCC estimates for each stage.

cdist_by_mod

Module-level score distributions.

joint_dist

Stage-wise joint score distributions by prefix.

eval_tb

A data frame with columns theta, mu, sigma2, bias, and csem.

Mathematical Formulation

Let $\theta \in \Theta$ denote a true ability value on a discrete grid. Consider a multistage test (MST) consisting of $T$ stages, where at each stage exactly one module is administered according to deterministic routing rules that map observed cumulative scores to modules.

(a) Module score distributions

For module $m$, let $S_m$ denote the module score. Conditional on ability $\theta$, the module score distribution is

$P(S_m = s \mid \theta)$

which is obtained by analytically combining item response category probabilities under the specified IRT model. This distribution is computed independently for each module using module_score_dist().

(b) Stage-wise recursion with routing

Let $S^{(t)}$ denote the cumulative score after stage $t$. At each stage $t$, examinees are assigned to a next-stage module $m_{t+1}$ based on the comparison between the ITCC estimates and the cut theta points.

The routing rule can be written as a deterministic mapping

$m_{t+1} = r_t(S^{(t)})$

where $r_t(\cdot)$ maps observed cumulative scores to modules at stage $t+1$.

(c) Exact joint score propagation

For a given routing branch induced by the realized cumulative score, the cumulative score evolves as

$S^{t+1} = S^t + S^{t+1}_m$

Conditional on $\theta$, the joint score distribution is updated analytically via convolution:

$P(S^{t+1} = s \mid \theta) = \sum_u P(S^t = u \mid \theta) P(S^{t+1}_m = s - u \mid \theta)$

where the sum is taken over all reachable values of $S^{(t)}$ along the routing branch.

(d) Inverse TCC and conditional moments

Let $S^{(t)}$ denote the final cumulative test score, and let $\hat{\theta}(S)$ be the reported ability estimate obtained by applying the inverse test characteristic curve (TCC) associated with the administered pathway determined by the routing rules.

For each true ability value $\theta$, the conditional mean and conditional variance of the reported ability are defined as

$\mu(\theta) = E[\hat{\theta} \mid \theta]$

$\sigma^2(\theta) = Var[\hat{\theta} \mid \theta]$

where the expectation is taken with respect to the exact joint distribution $P(S \mid \theta)$ induced by the MST routing rules.

Explicitly,

$\mu(\theta) = \sum_{s} \hat{\theta}(s)\, P(S = s \mid \theta)$

$\sigma^2(\theta) = \sum_{s} (\hat{\theta}(s) - \mu(\theta))^2\, P(S = s \mid \theta)$

References

Lim, H., Davey, T., & Wells, C. S. (2020). A recursion-based analytical approach to evaluate the performance of MST. Journal of Educational Measurement, 58(2), 154–178. doi:10.1111/jedm.12276

See Also

compute_icc()

module_score_dist()

joint_module_score_dist()

inverse_tcc()

---

Assemble Selected Items into MST panel

Description

Constructs a panel-centric representation of an assembled multistage panel (MST) from the solver output. The function extracts binary decision variables, maps them to items in the item pool, and organizes the results by panel, module, and pathway.

This function is typically called after solve_model() and is intended for post-solution interpretation, diagnostics, and reporting.

Usage

assembled_panel(x, result)

Arguments

x	An object of class "mstATA_design" created by mst_design().
result	A solver result returned by solve_model(), containing components model and solution.

Details

The workflow is:

1. Extract item-module-panel binary decision variables with value 1 from the solver solution.

2. Parse decision variable names of the form x[module_id, item_id, panel_id].

3. Map internal item indices (item_id) to item-module-panel identifiers.

4. Merge selected items with the item pool to attach item attributes.

5. For each panel:

   • Construct ItemsInModules, listing items selected in each module.

   • Construct ItemsInPathways, listing items associated with each pathway based on the pathway-module mapping.

If pathway or module labels are available in x$PathwayIndex and x$ModuleIndex, labels for modules/pathways are attached.

Value

An object of S3 class mstATA_panel with a named list with one element per panel: Panel_1, Panel_2, ....Each panel is a list with components:

ItemsInModules

A data frame containing selected items grouped by module. Columns include item_name, item_id, varname, module_id, and all item attributes from the item pool.

ItemsInPathways

A data frame containing selected items grouped by pathway. Columns include item_name, item_id, varname, pathway_id, and all item attributes from the item pool.

See Also

solve_model()

---

Precomputed MST Panel: Binary_Minimax Formulation

Description

A precomputed multistage testing (MST) panel assembled using the minimax objective formulation (two_dev) described in the Formulation for Multiple Objectives vignette.

Usage

binary_minimax_panel

Format

An object of class mstATA_panel.

Details

This object is included to avoid long solver runtimes during vignette building and package checking.

Source

Generated using mstATA::assembled_panels() and mstATA::solve_model()with the HiGHS solver.

---

Precomputed Bottom-up MST Assembly Example (BU13)

Description

A precomputed multistage testing (MST) panel assembled using the bottom-up strategy demonstrated in the Three ATA Strategies Vignette.

Usage

BU13_panel

Format

An object of class mstATA_panel.

Source

Generated using mstATA::assembled_panels() and mstATA::solve_model()with the HiGHS solver.

---

Capped maximin objective

Description

The capped maximin strategy balances multiple competing objectives by maximizing a common lower bound across multiple objective terms, while simultaneously limiting how far any single objective term may exceed that bound.

Compared to the classical maximin formulation–where overflow control may be imposed through a user-specified upper bound $\delta$–the capped maximin strategy treats $\delta$ as a decision variable and optimizes it jointly with the common floor value $y$. The resulting objective to be maximized, $(y - \delta)$, balances improving the worst-performing objective while penalizing excessive dominance by any single objective.

Usage

capped_maximin_obj(x, multiple_terms, strategy_args = list())

Arguments

x	An object of class mstATA_design created by mst_design().
multiple_terms	A list of objective terms created by objective_term(). The list must contain two or more objective terms. All objective terms must be relative objectives (i.e., goal = NULL).
strategy_args	A named list of strategy-specific arguments used by the capped_maximin aggregation. Supported fields: proportions – A positive numeric vector of length length(multiple_terms) specifying the relative scaling of each objective term. Defaults to a vector of ones.

Details

1. Overview

The capped maximin strategy applies when there are two or more objective terms, each representing a linear score of the form

$y_k = a_k^\top x, k = 1,\ldots,K,$

where $a_k$ is the coefficient vector constructed by objective_term(), and $x$ denotes the binary item-module decision variables.

The goal is to:

• maximize the minimum normalized performance across all objective terms, and

• restrict excessive dominance of any single objective via an overflow band.

Unlike the classical maximin strategy (where $\delta$ is user-specified or infinite), capped maximin treats $\delta$ as a decision variable and optimizes it jointly with the common floor.

Each objective term is created using objective_term() and may differ in attribute type, attribute level, and target value.

Key characteristics for each objective term:

(1) Requirement type

• Categorical: maximize the number of items from a specified category level; or

• Quantitative: maximize the sum of item-level quantitative attributes (e.g., difficulty, discrimination, item information).

(2) Application level

• "Module-level" – only items in a specified module contribute;

• "Pathway-level" – items in all modules belonging to a pathway;

• "Panel-level" – all item selections in the panel contribute.

(3) Objective type

The capped maximin strategy supports relative objectives only: maximize $a_k^\top x$

Absolute (goal-based) objectives of the form $|a_k^\top x - g_k|$ are not permitted under capped maximin.

2. Proportions and normalization

Each objective term may be associated with a positive proportion $p_k > 0$. These proportions encode the relative scaling of each objective.

By default, $p_k = 1$ for all terms.

3. Overflow control via $\delta$

The capped maximin formulation introduces a common overflow variable $\delta \ge 0$, yielding the constraints:

$p_k\, y \le a_k^\top x \le p_k\, y + \delta, k = 1,\ldots,K.$

These constraints ensure that:

• all objective terms achieve a highest value proportional to a common normalized floor $y$, and

• no term exceeds the highest value by more than $\delta$.

Value

A list of class "compiled_objective"

name

A character vector indicating the specifications in each row of A_binary

specification

A data.frame summarizing the constraint specification, including the requirement name, attribute, constraint type, application level, operator, and the number of constraint rows generated.

A_binary

A sparse binary matrix representing the linear constraint coefficients.

A_real

A sparse constraint matrix (class "Matrix") for continuous decision variables. Must have the same number of rows as A_binary.

operators

A character vector of constraint operators, one per row of A_binary.

d

A numeric vector of right-hand-side values for the constraints.

C_binary

A numeric vector of objective coefficients for binary decision variables.

C_real

A numeric vector of objective coefficients for continuous decision variables.

sense

Always "max" for the capped_maximin strategy.

decisionvar_name_new

Character vector indicating the names of new decision variables, same length as ncol(A_real).

decisionvar_type_new

A character vector of "C" (continuous), same length as ncol(A_real).

notes

List of strategy metadata.

Mathematical Formulation

Let $x$ denote the vector of binary item-module decision variables. For each objective term $k = 1,\ldots,K$, define:

$y_k = a_k^\top x.$

Introduce two continuous decision variables:

• $y$ – the common normalized floor value;

• $\delta$ – the maximum allowable overflow above the floor.

The capped maximin optimization problem is:

$\max (y - \delta)$

subject to:

$p_k \, y \le y_k \le p_k \, y + \delta, k = 1,\ldots,K.$

This formulation encourages balanced improvement across multiple objectives while penalizing excessive disparity among them.

Examples

data("mini_itempool")
# MST 1-2-3 design, S1R-S2E-S3H, S1R-S2H-S3E pathways are not allowed.
test_mstATA <- mst_design(
  itempool        = mini_itempool,
  design          = "1-3-3",
  exclude_pathway = c("1-1-3", "1-3-1"),
  pathway_length  = 8
)

# Example: Maximize the minimum TIF across theta = -1, 0, 1
theta_n1 <- objective_term(
  x = test_mstATA,
  attribute = "iif(theta=-1)",
  applied_level = "Module-level",
  which_module = 1,
  sense = "max"
)

theta_0 <- objective_term(
  x = test_mstATA,
  attribute = "iif(theta=0)",
  applied_level = "Module-level",
  which_module = 1,
  sense = "max"
)

theta_1 <- objective_term(
  x = test_mstATA,
  attribute = "iif(theta=1)",
  applied_level = "Module-level",
  which_module = 1,
  sense = "max"
)


capped_maximin_obj(x = test_mstATA, multiple_terms = list(theta_n1,theta_0,theta_1))

---

Precomputed MST Panel: Capped_Maximin Formulation

Description

A precomputed multistage testing (MST) panel assembled using the capped_maximin objective formulation described in the Formulation for Multiple Objectives vignette.

Usage

capped_maximin_panel

Format

An object of class mstATA_panel.

Details

This object is included to avoid long solver runtimes during vignette building and package checking.

Source

Generated using mstATA::assembled_panels() and mstATA::solve_model()with the HiGHS solver.

---

Feasibility check for a specified combination of constraint blocks

Description

Diagnoses infeasibility in an mstATA_model by testing whether a user-specified combination of constraint blocks, together with the core set of constraints, results in an infeasible model.

The full model must be infeasible. A reduced model is constructed that always includes the core constraints (objective-related constraints and essential MST structure constraints) and additionally includes the constraint blocks specified in con_blocks. The solver status of this reduced model is then evaluated.

Usage

check_comblock_feasibility(model_spec, con_blocks, solver, time_limit = 99999)

Arguments

model_spec	An object of class mstATA_model. The full model must be infeasible.
con_blocks	An integer vector giving the indices of constraint blocks (rows of model_spec$specification) to be jointly tested. These blocks are added to the core constraints as a group.
solver	A character string indicating which solver to use. One of "gurobi", "lpsolve", "HiGHS", "Symphony", or "GLPK".
time_limit	The maximum amount of computation time allocated to the solver. Default is 99999 seconds.

Details

The reduced model always includes a fixed core set of constraints:

• Objective-related constraints.

• Essential MST structure constraints (e.g., module-/pathway-level item count constraints, routing decision points constraints, item reusage within a panel).

The constraint blocks specified in con_blocks are added to this core simultaneously and tested as a group. This function does not perform a one-at-a-time or incremental check; instead, it evaluates the feasibility of the combined block set.

This function is primarily intended for second-stage infeasibility diagnostics, such as verifying suspected conflicting constraint combinations or validating results from block-wise (additive or subtractive) diagnostic procedures.

Value

A list with the following elements:

blocks_tested

Character vector of requirement names corresponding to con_blocks.

status

Solver status returned for the reduced model (e.g., "INFEASIBLE", "OPTIMAL", "FEASIBLE").

See Also

check_singleblock_feasibility()

---

Block-wise feasibility diagnostics for infeasible mstATA models

Description

Diagnoses infeasibility in an mstATA_model by solving a sequence of reduced models. The full model must be infeasible. A core set of constraints (objective-related constraints and essential MST structure constraints) is checked for feasibility first. If feasible, the core set of constraints is always included. Each remaining constraint block is then tested individually by solving a reduced model that contains the core constraints plus exactly one additional constraint block (i.e., non-core blocks are not accumulated).

Usage

check_singleblock_feasibility(model_spec, solver, time_limit = 99999)

Arguments

model_spec	An object of class mstATA_model. The model must be infeasible.
solver	A character string indicating which solver to use. One of "gurobi", "lpsolve", "HiGHS", "Symphony", or "GLPK".
time_limit	The maximum amount of computation time allocated to the solver. Default is 99999 seconds.

Details

The core model always includes:

• Objective-related constraints.

• Essential MST structure constraints (e.g., module-/pathway-level item count constraints, routing decision points constraints, item reusage within a panel).

The MST structure constraints ensure that the fundamental structural requirements of the MST design are satisfied.

Specifically, MST structure constraints include:

(1) Item count constraints

(a) Number of items in each module is provided in mst_design()

• One constraint is created for each module.

• Each module must contain exactly the specified number of items.

(b) Number of items in each pathway is provided in mst_design().

• Each pathway must contain exactly the specified number of items.

• Optional stage-level structure constraints may additionally enforce:

  • Minimum number of items per stage.

  • Maximum number of items per stage.

• If stage_length_bound = NULL, the following default stage-level structure is enforced:

  • Each stage must contain at least one item.

  • Modules within the same stage must have equal length.

(2) Routing decision points constraints

These constraints are generated when rdps is provided in mst_design().

• The test information at the routing decision point between adjacent modules in the next stage is similar within a specified tolerance.

(3) Panel-level item usage constraints

These constraints are generated using panel_itemreuse_con() limiting how many times an item may be selected across the modules and pathways contained within a single MST panel.

After checking the feasibility of the core set of constraints, all other (non-structural) constraint blocks are tested individually by adding them to the core model one at a time. This function does not attempt to diagnose infeasibility arising from interactions among multiple non-core constraint blocks.

Value

A data frame with one row per constraint block tested.

See Also

test_itemcount_con(),

test_rdp_con(),

mst_structure_con(),

panel_itemreuse_con(),

check_comblock_feasibility(),

solve_model()

---

Compute Item Characteristic Curves (ICC)

Description

Computes item category characteristic curves (ICCs) for dichotomous, polytomous, or mixed-format item pools. The function supports multiple IRT models simultaneously and returns category-level response probabilities for each item at specified ability points.

Usage

compute_icc(items, item_par_cols, theta, model_col, nrCat_col = NULL, D = 1)

Arguments

items	A data frame containing item metadata. Each row represents an item. The data frame must include a column specifying the item model (see model_col) and the parameter columns referenced in item_par_cols.
item_par_cols	A named list defining the IRT parameter columns required for each supported model. The list names must exactly match the model identifiers specified in items[[model_col]]: "1PL", "RASCH", "2PL", "3PL", "4PL", "GRM", "MGRM", "PCM", "GPCM", "RSM", and "NRM". Each list element is a character vector giving the column names in items that contain the required item parameters for the corresponding model.
theta	A numeric vector of ability values at which the ICCs are evaluated.
model_col	A character string specifying the column name in items that indicates the IRT model used for each item. Values in this column must correspond to the supported model names: "1PL", "RASCH", "2PL", "3PL", "4PL", "GRM", "MGRM", "PCM", "GPCM", "RSM", or "NRM".
nrCat_col	A character string specifying the column name in items that indicates the number of response categories for each items. Default is NULL, the number of response categories is derived based on item parameters. If not NULL, the number of response categories is checked with number of item parameters for consistency.
D	Scaling constant used in the IRT model. Default is D=1 (for logistic metric); D=1.702 yields approximately the normal metric.

Details

The output matrices returned by compute_icc() include a fixed set of category columns (cat0, cat1, ...), with unused categories filled with zeros to ensure consistent dimensions across mixed-format item pools.

(1) Dichotomous models.

For the models "1PL", "RASCH", "2PL", "3PL", and "4PL", item parameters are extended to the following four columns:

discrimination

Slope parameter ($a$).

difficulty

Location parameter ($b$).

guessing

Lower asymptote ($c$).

upper

Upper asymptote ($d$).

Missing parameters required for a given model are automatically filled. For example, the RASCH and 1PL models are represented with $a = 1$, $c = 0$, and $d = 1$.

All dichotomous item parameters are validated prior to ICC computation:

• discrimination > 0

• 0 <= guessing <= 1

• 0 <= upper <= 1

• guessing < upper

(2) Polytomous models.

The supported polytomous models include "GRM", "MGRM", "PCM", "GPCM", "RSM", and "NRM". Let $K$ denotes the number of non-baseline response categories. Required parameters depend on the specific model and may include discrimination parameters and category-specific thresholds or step parameters (e.g., betaj1, ..., betajK, deltaj1, ..., deltajK). See Pi_internal().

Value

A named list of matrices, one for each value in theta. List length = the number of ability values and List names = Character strings of the form "theta=<value>".

Each matrix entry gives the probability of responding in the corresponding category for the given item at the specified ability level. Matrix rows = the number of items, with row names equal to item identifiers. Matrix columns = Response categories labeled cat0, cat1, ..., catM.

Examples

## Example 1: Dichotomous model
data("mini_itempool")
compute_icc(mini_itempool,list("3PL"=c("discrimination","difficulty","guessing")),
            theta = c(-1,0,1),model_col = "model",D = 1.7)

## Example 2: Polytomous model (PCM)
data("poly_itempool")
compute_icc(poly_itempool,list("PCM"=c("deltaj1","deltaj2","deltaj3")),
            theta = c(-1,0,1),model_col = "model")

## Example 3: multiple IRT models (3PL + GPCM + GRM)
data("Rmst_pool")
compute_icc(Rmst_pool,
            item_par_cols = list("3PL"=c("a","b","c"),
                                 "GPCM" = c("alpha","delta1","delta2","delta3"),
                                  "GRM" = c("alpha","beta1","beta2")),
            theta = c(-1,0,1),model_col = "model")

---

Compute Item Information Function (IIF) at Target Theta Points

Description

Computes item information function (IIF) values for dichotomous, polytomous, or mixed-format item pools across a set of target ability values. The function supports multiple unidimensional IRT models simultaneously and returns an item-by-theta information matrix.

Usage

compute_iif(items, item_par_cols, theta, model_col, D = 1)

Arguments

items	A data frame containing item metadata. Each row represents an item. The data frame must include a column specifying the item model (see model_col) and the parameter columns referenced in item_par_cols.
item_par_cols	A named list defining the IRT parameter columns required for each supported model. The list names must exactly match the model identifiers specified in items[[model_col]]: "1PL", "RASCH", "2PL", "3PL", "4PL", "GRM", "MGRM", "PCM", "GPCM", "RSM", and "NRM". Each list element is a character vector giving the column names in items that contain the required item parameters for the corresponding model.
theta	A numeric vector of ability values at which the IIFs are evaluated.
model_col	A character string specifying the column name in items that indicates the IRT model used for each item. Values in this column must correspond to the supported model names: "1PL", "RASCH", "2PL", "3PL", "4PL", "GRM", "MGRM", "PCM", "GPCM", "RSM", or "NRM".
D	Scaling constant used in the IRT model. Default is D=1 (for logistic metric); D=1.702 yields approximately the normal metric.

Value

A numeric matrix of item information values, with rows corresponding to items and columns corresponding to theta.

See Also

compute_icc()

Examples

## Example 1: Dichotomous model
data("mini_itempool")
compute_iif(mini_itempool,
            item_par_cols = list("3PL"=c("discrimination","difficulty","guessing")),
            theta = c(-1,0,1),model_col = "model")

## Example 2: Polytomous model (PCM)
data("poly_itempool")
compute_iif(poly_itempool,
            item_par_cols = list("PCM"=c("deltaj1","deltaj2","deltaj3")),
            theta = c(-1,0,1),model_col = "model")

## Example 3: multiple IRT models (3PL + GPCM + GRM)
data("Rmst_pool")
compute_iif(Rmst_pool,
            item_par_cols = list("3PL"=c("a","b","c"),
                                "GPCM" = c("alpha","delta1","delta2","delta3"),
                                 "GRM" = c("alpha","beta1","beta2")),
            theta = c(-1,0,1),model_col = "model")

---

Concatenate Enemy Sets

Description

Concatenates enemy sets produced by create_enemy_sets(). Enemy sets from each source are appended without modification, while pairwise enemy relationships are unioned across all inputs. No transitive closure or set expansion is performed.

Usage

concat_enemy_sets(...)

Arguments

...	One or more enemy relationships returned by create_enemy_sets(). Each input must be a list with the following components: ExclusionPair A two-column character matrix of pairwise enemy relationships. EnemySet A list of character vectors representing explicitly defined enemy sets.

Details

Suppose source A defines five enemy sets and source B defines two enemy sets. The resulting object will contain seven enemy sets, formed by simple concatenation of the input EnemySet components.

The ExclusionPair component of the result is the union of all unique, unordered pairwise enemy relationships across inputs.

Importantly, no transitive inference is applied. If item A is an enemy of B and item B is an enemy of C (possibly from different sources), this function does not infer that A is an enemy of C.

This function is intended for situations where enemy relationships are defined from multiple independent sources (e.g., similarity, cluing, or security rules) and must be preserved exactly as specified.

Value

A list with components:

ExclusionPair

A two-column character matrix of unioned enemy pairs.

EnemySet

A list of enemy sets formed by concatenating all inputs.

See Also

create_enemy_sets

Examples

## Example: combining multiple sources of enemy relationships
## Enemy relationships based on similarity
similarity <- create_enemy_sets(
  id_col    = mini_itempool$item_id,
  enemy_col = mini_itempool$enemy_similarity
)

## Enemy relationships based on cluing
cluing <- create_enemy_sets(
  id_col    = mini_itempool$item_id,
  enemy_col = mini_itempool$enemy_cluing
)

## Combine all enemy relationships into a single enemy set
enemy_all <- concat_enemy_sets(
  similarity,
  cluing
)
enemy_all

---

Create Enemy Pairs and Enemy Sets

Description

Create pairwise enemy relationships and corresponding enemy sets for items or stimuli based on metadata in the item pool.

This function parses enemy information from two aligned vectors– an identifier column and an enemy-specification column–and returns (1) a matrix of unique enemy pairs and (2) a list of enemy sets. Enemy pairs represent item or stimulus combinations that must not be selected together. See Details.

The function is intended as a preprocessing step prior to constructing enemy-item or enemy-stimulus exclusion constraints.

Usage

create_enemy_sets(id_col, enemy_col, sep_pattern = ",")

Arguments

id_col	A character vector of item or stimulus identifiers (e.g., item IDs or stimulus names).
enemy_col	A character vector specifying enemy items or stimuli associated with each element of id_col. The length must equal length(id_col). Missing values indicate no enemies.
sep_pattern	A regular expression used to split multiple enemy identifiers within enemy_col. Defaults to ",".

Details

1. Enemy definition

Two items or two stimuli are considered enemies if they must not appear together. Typical reasons include:

• High surface similarity or paraphrasing

• Shared clues or solution pathways

• Security, exposure, or operational constraints

The ExclusionPair component is the authoritative definition of explicitly declared enemy relationships. Each row represents a single, directly specified pairwise exclusion.

The EnemySet component provides a grouped representation of enemy relationships for constraint construction. Enemy sets may include items or stimuli that are connected through one or more pairwise exclusions in ExclusionPair. Formally, each enemy set corresponds to a connected component of the graph induced by ExclusionPair.

2. Interpretation of enemy relationships

Enemy relationships specified through enemy_col are interpreted transitively. That is, if item/stimulus A is an enemy of B, and B is an enemy of C, then A, B, and C are merged into a single enemy set. From each enemy set, at most one item or stimulus may be selected.

This conservative interpretation prevents indirect information leakage or similarity chains that may not be obvious from pairwise specifications alone.

3. Important modeling note

If users intend different types of enemy relationships that should not propagate transitively, they should encode them in separate columns of the item pool.

For example:

• Item A is an enemy of item B because they are too similar.

• Item B is an enemy of item C because they provide clues to each other.

• The user does not believe that item A and item C should be treated as enemies.

In this case, a safer modeling strategy is:

• Encode the A-B enemy relationship in one enemy column (e.g., enemy_similarity);

• Encode the B-C enemy relationship in a different enemy column (e.g., enemy_clueing);

• Construct enemy sets separately from each column.

This approach prevents unintended transitive grouping, allowing items A and C to remain eligible for joint selection while still enforcing the intended pairwise exclusions.

In this case, users construct enemy sets separately, concatenate them using concat_enemy_sets() and supply the concatenated result to mst_design().

Value

A list with the following components:

ExclusionPair

A two-column character matrix in which each row represents a unique pair of mutually exclusive (enemy) items or stimuli.

EnemySet

A list of character vectors, where each element represents a set of items or stimuli that are mutually exclusive with one another.

See Also

concat_enemy_sets()

Examples

## Example 1: Enemy item relationships
create_enemy_sets(
  id_col = mini_itempool$item_id,
  enemy_col = mini_itempool$enemy_similarity,
  sep_pattern = ","
)

## Example 2: Enemy stimulus relationships
create_enemy_sets(
  id_col = reading_itempool$stimulus,
  enemy_col = reading_itempool$enemy_stimulus,
  sep_pattern = ", "
)

---

Create Pivot-Stimulus Mapping

Description

Construct a stimulus-pivot item map from an item pool containing stimulus identifiers and pivot-item indicators. This function extracts the pivot item for each stimulus and identifies all items associated with that stimulus.

This function is typically used as a preprocessing step before applying any constraints related with stimuli and stimulus-based items.

Usage

create_pivot_stimulus_map(
  itempool,
  item_id_col = "item_id",
  stimulus,
  pivot_item
)

Arguments

itempool	A data.frame containing the item pool.
item_id_col	A string giving the column name in itempool that uniquely identifies items.
stimulus	A string giving the column name in itempool that identifies the stimulus or passage to which each item belongs. Values may be character, or numeric (coerced to character). Items not associated with a stimulus should be coded as NA.
pivot_item	A string giving the column name in itempool. Values must be character and non-missing values identify pivot items. Each stimulus must have exactly one pivot item. Empty strings or whitespace are treated as missing. See Details.

Details

Formally, a pivot item is defined as an item that is selected if and only if its corresponding stimulus is selected. In practice, the pivot item is typically chosen as the item within a set that best represents the stimulus–identified by content experts as having the most representative content or desirable psychometric properties.

Value

A list with the following components:

pivot_item_id

A character vector of pivot item IDs, one per stimulus.

stimulus_name

A character vector giving the stimulus identifier associated with each pivot item. The order matches pivot_item_id.

stimulus_members

A named list. Each element contains the item IDs belonging to a stimulus. Names match stimulus_name.

numItems_stimulus

An integer vector giving the number of items associated with each stimulus. This is length(stimulus_members[[i]]).

Examples

itempool <- data.frame(
  item_id = 1:7,
  stimulus_id = c("S1","S1","S1","S2","S2", NA, NA),
  is_pivot   = c("P", NA, NA, "P", NA, NA, NA)
)

create_pivot_stimulus_map(
  itempool = itempool,
  item_id_col = "item_id",
  stimulus = "stimulus_id",
  pivot_item = "is_pivot"
)

---

Defining Solution-level Item Indicator Variables and Generating Constraints for Item Exposure Control Across Multiple Panels

Description

This function does not need to be called by users and is internally used by multipanel_spec(). It is a structural component of multi-panel MST assembly.

It has two roles.

• Define the semantics of the solution-level indicator variable $s_i$: an item is considered used if and only if it is selected in at least one module of at least one panel.

• Constrain user-specified minimum and maximum reuse limits for each item across all panels. The total number of constraints depends on the number of items in the item pool (for min and max usage, two constraints per item).

Usage

dvlink_item_solution(
  x,
  num_panels,
  global_min_use = 0,
  global_max_use = Inf,
  item_min_use = NULL,
  item_max_use = NULL
)

Arguments

x	An object of class "mstATA_design" created by mst_design().
num_panels	Integer. Number of panels to be assembled.
global_min_use	Scalar. Minimum number of times any item may be used across panels. Default is 0.
global_max_use	Scalar. Maximum number of times any item may be used across panels. Default is Inf.
item_min_use	Optional data frame with columns item_id and min, specifying item-specific minimum reuse counts. Default is NULL.
item_max_use	Optional data frame with columns item_id and max, specifying item-specific maximum reuse counts. Default is NULL.

Details

1. Specification

The constraint enforces:

Each item can be used at least a specified minimum number of times and/or no more than a specified maximum number of times across all panels.

Key characteristics:

• Attribute: itemset level (item-itself set) logical (if selected, then increment reuse).

• Constraints are applied at the "Solution-level".

2. Number of times an item can be selected

Global reuse limits are supplied via global_min_use and global_max_use. These bounds apply to all items unless overridden.

Item-specific reuse limits may be supplied through:

• item_min_use: a data frame with columns item_id and min

• item_max_use: a data frame with columns item_id and max

The total number of constraints generated is always $2 \times P$ where $P$ is the pool size, corresponding to one minimum and one maximum constraint per item.

Value

An object of S3 class "mstATA_constraint" with named elements:

name

A character vector indicating the specifications in each row of A_binary

specification

A data.frame summarizing the constraint specification, including the requirement name, attribute, constraint type, application level, operator, and the number of constraint rows generated.

A_binary

A sparse binary matrix representing the linear constraint coefficients.

A_real

NULL for 'mstATA_constraint' object

operators

A character vector of constraint operators, one per row of A_binary.

d

A numeric vector of right-hand-side values for the constraints.

C_binary

NULL for 'mstATA_constraint' object

C_real

NULL for 'mstATA_constraint' object

sense

NULL for 'mstATA_constraint' object

Mathematical Formulation

Suppose the item pool contains (S - 1) stimulus-based item sets, indexed by $s = 1, \ldots, S - 1$. Each stimulus has a designated pivot item, indexed by $i^*_s$. In addition, the pool contains a set of discrete (non-stimulus-based) items, which are represented by a dummy stimulus $s = S$ to allow a unified indexing scheme. Items belonging to stimulus $s$ are indexed as $i_s = 1, 2, \ldots, I_s$.

Suppose there are $M$ modules in an MST panel. Let $m = 1, \ldots, M$ denote the module index. Suppose there are $P$ panels assembled in one solution. Let $p = 1, \ldots, P$ denote the panel index.

Decision variable set 1: item-module-panel selection variables

For each item $i_s$, $x_{i_s,m,p}$ = 1 if item $i_s$ is selected in module $m$ of panel $p$. $x_{i_s,m,p}$ = 0 otherwise.

Decision variable set 2: solution-level item indicators

For each item $i_s$, $s_{i_s}$ = 1 if item $i_s$ is used in any module in any panel. $s_{i_s}$ = 0 otherwise.

Number of times item i is selected in a solution

$u_i = \sum_{p}\sum_{m} x_{i_s,m,p}$

This constraints enforce:

$m_i^{\min} s_{i_s} \le u_i \le m_i^{\max} s_{i_s}$

ensuring consistency between panel-level selections and solution-level indicators while enforcing reuse limits.

where:

• $x_{i_s,m,p}$ indicates whether item $i_s$ is selected in module $m$ of panel $p$;

• $s_{i_s}$ indicates whether item $i_s$ is used anywhere in the solution;

• $m_i^{\min}$ and $m_i^{\max}$ are item-specific reuse bounds.

These constraints are structural: they define the meaning of the solution-level indicator variables and also create constraints for the item exposure control across panels.

• If $s_i = 0$, then item $i$ cannot be selected in any module of any panel.

• If $s_i = 1$, the total number of selections of item $i$ must lie within the specified reuse bounds.

• If item $i$ is not selected in any module across panels, then $s_i$ must equal 0.

• If item $i$ is selected in at least one module of any panel, then $s_i$ must equal 1.

Examples

data("mini_itempool")

test_mstATA <- mst_design(
  itempool      = mini_itempool,
  design        = "1-3-3",
  module_length = c(6, 4, 4, 4, 3, 3, 3)
)

# Example: Allow each item to be used at most once across all panels
dvlink_item_solution(
  x = test_mstATA,
  num_panels = 2,
  global_max_use = 1
)

---

Generate Pathway-Level Constraints to Prevent Enemy Items from Appearing Together

Description

Constructs linear constraints to ensure that items belonging to the same enemy set do not appear together within any assembled MST pathway (i.e., any complete test form).

Enemy items are items that:

• give away the answer to one another,

• are too similar in content or structure, or

• should not be seen by the same examinee for security or fairness reasons.

The total number of constraints = num of enemy item sets * num of pathways

Usage

enemyitem_exclu_con(x)

Arguments

x	An object of class "mstATA_design" created by mst_design().

Details

1. Specification

The enforced constraint is:

At most one item from the same enemy set can be selected in a pathway

• The attribute is a itemset-level logical grouping: enemyitem_set defines enemy item groups in the item pool.

• The constraint must be applied at "Pathway-level". Because each pathway represents the full sequence of modules that an examinee could encounter, preventing enemy items from appearing in a pathway ensures that no examinee can see more than one item from the same enemy set.

2. Logical Interpretation

For an enemy item set $V_e^{item}$:If one item in the set is selected anywhere in the pathway, all other items in the same set must be excluded from that pathway.

This ensures that at most one item from each enemy group appears in any assembled test form.

Value

An object of S3 class "mstATA_constraint" with named elements:

name

A character vector indicating the specifications in each row of A_binary

specification

A data.frame summarizing the constraint specification, including the requirement name, attribute, constraint type, application level, operator, and the number of constraint rows generated.

A_binary

A sparse binary matrix representing the linear constraint coefficients.

A_real

NULL for 'mstATA_constraint' object

operators

A character vector of constraint operators, one per row of A_binary.

d

A numeric vector of right-hand-side values for the constraints.

C_binary

NULL for 'mstATA_constraint' object

C_real

NULL for 'mstATA_constraint' object

sense

NULL for 'mstATA_constraint' object

Mathematical Formulation

Suppose the item pool contains (S - 1) stimulus-based item sets, indexed by $s = 1, \ldots, S - 1$. Each stimulus has a designated pivot item, indexed by $i_s^{*}$. In addition, the pool contains a set of discrete (non-stimulus-based) items, which are represented by a dummy stimulus $s = S$ to allow a unified indexing scheme. Items belonging to stimulus $s$ are indexed as $i_s = 1, 2, \ldots, I_s$.

Suppose there are $M$ modules in an MST panel. Let $m = 1, \ldots, M$ denote the module index.

Let $V_e^{item}$ denotes a set of items that are mutually exclusive (enemy) items.

$\sum_{m \in r} \sum_{i_s \in V_e^{item}} x_{i_s,m} \le 1 .$

Here:

• $x_{i_s,m}$ is the binary decision variable indicating whether item $i_s$ is selected into module m.

• $m \in r$ denote modules belonging to pathway r.

See Also

create_enemy_sets(),

concat_enemy_sets()

Examples

# Example 1: Two enemy sets: {Item1, Item2, Item3} and {Item4, Item5}
data("mini_itempool")

enemyitem_set<- create_enemy_sets(mini_itempool$item_id,
                                 mini_itempool$enemy_similarity,
                                 sep_pattern = ",")

test_mstATA <- mst_design(
  itempool = mini_itempool,
  design = "1-3-3",
  module_length = c(4,2,2,2,2,2,2),
  enemyitem_set = enemyitem_set
)

enemyitem_exclu_con(x = test_mstATA)


# Example 2:
## Enemy relationships based on similarity
similarity <- create_enemy_sets(
  id_col    = mini_itempool$item_id,
  enemy_col = mini_itempool$enemy_similarity
)

## Enemy relationships based on cluing
cluing <- create_enemy_sets(
  id_col    = mini_itempool$item_id,
  enemy_col = mini_itempool$enemy_cluing
)

## Combine all enemy relationships into a single enemy set
enemy_all <- concat_enemy_sets(
  similarity,
  cluing
)

## Use the combined enemy set in the test design
test_mstATA2 <- mst_design(
  itempool       = mini_itempool,
  design = "1-3-3",
  module_length = c(4,2,2,2,2,2,2),
  enemyitem_set = enemy_all
)

enemyitem_exclu_con(test_mstATA2)

---

Generate Pathway-Level Constraints to Prevent Enemy Stimuli from Appearing Together

Description

Constructs linear constraints to ensure that stimuli belonging to the same enemy set do not appear together within any MST pathway (i.e., any complete test form).

Enemy stimuli are stimuli that should not be viewed by the same examinee for security or fairness reasons.

The total number of constraints = number of enemy stimulus sets * number of pathways.

Usage

enemystim_exclu_con(x)

Arguments

x	An object of class "mstATA_design" created by mst_design().

Details

1. Specification

The enforced constraint is:

At most one stimulus from the same enemy set can be selected in a pathway

• The attribute is a itemset-level logical grouping: enemystim_set defines enemy stimulus groups in the item pool.

• The constraint must be applied at "Pathway-level". Because each pathway represents the full sequence of modules that an examinee could encounter, preventing enemy stimuli from appearing in a pathway ensures that no examinee can see more than one stimulus from the same enemy set.

2. Logical Interpretation

For an enemy stimulus set $V_e^{stim}$:If a stimulus in the set is selected anywhere in the pathway, all other stimuli in the same set must be excluded from that pathway.

This ensures that at most one stimulus from each enemy group appears in any assembled test form.

Value

An object of S3 class "mstATA_constraint" with named elements:

name

A character vector indicating the specifications in each row of A_binary

specification

A data.frame summarizing the constraint specification, including the requirement name, attribute, constraint type, application level, operator, and the number of constraint rows generated.

A_binary

A sparse binary matrix representing the linear constraint coefficients.

A_real

NULL for 'mstATA_constraint' object

operators

A character vector of constraint operators, one per row of A_binary.

d

A numeric vector of right-hand-side values for the constraints.

C_binary

NULL for 'mstATA_constraint' object

C_real

NULL for 'mstATA_constraint' object

sense

NULL for 'mstATA_constraint' object

Mathematical Formulation

Suppose the item pool contains (S - 1) stimulus-based item sets, indexed by $s = 1, \ldots, S - 1$. Each stimulus has a designated pivot item, indexed by $i_s^{*}$. In addition, the pool contains a set of discrete (non-stimulus-based) items, which are represented by a dummy stimulus $s = S$ to allow a unified indexing scheme. Items belonging to stimulus $s$ are indexed as $i_s = 1, 2, \ldots, I_s$.

Suppose there are $M$ modules in an MST panel. Let $m = 1, \ldots, M$ denote the module index.

Let $V_e^{stim}$ denotes a set of stimuli that are mutually exclusive (enemy).

$\sum_{m \in r} \sum_{s \in V_e^{stim}} x_{i_s^{*},m} \le 1 .$

Here:

• $x_{i_s^{*},m}$ indicates whether the pivot item for stimulus s is selected into module m, thereby indicating whether the stimulus s is selected in that module.

• $m \in r$ denote modules belonging to pathway r.

See Also

create_enemy_sets(),

concat_enemy_sets(),

create_pivot_stimulus_map()

Examples

data("reading_itempool")

pivot_stim_map <- create_pivot_stimulus_map(
  itempool   = reading_itempool,
  stimulus   = "stimulus",
  pivot_item = "pivot_item"
)

# Create enemy-stimulus sets
enemystim_set<-create_enemy_sets(
  reading_itempool$stimulus,
  reading_itempool$enemy_stimulus,
  sep_pattern = ","
)

test_mstATA <- mst_design(
  itempool       = reading_itempool,
  design         = "1-3-3",
  module_length  = c(10,12,12,12,15,15,15),
  exclude_pathway = c("1-1-3", "1-3-1"),
  pivot_stim_map = pivot_stim_map,
  enemystim_set = enemystim_set
)

enemystim_exclu_con(x = test_mstATA)

---

Expected score

Description

Computes the expected total score implied by item category probability curves. The expectation can be evaluated either at a grid point (single ICC matrix) or at an arbitrary ability value.

Usage

expected_score(icc, target_theta = NULL)

Arguments

icc	Either a numeric matrix of item category probabilities at a fixed ability level $\theta$ (Rows correspond to items and columns correspond to response categories (cat0, cat1, ...).), or a named list of such matrices evaluated on the ability grid.
target_theta	Optional numeric value giving the ability level at which the expected score is to be evaluated. Required when icc is a list.

Details

1. How expected score is computed

Consider there are $I$ items. Let the score for item $i$ be a discrete random variable $Y_i$ taking values $\{0, 1, \dots, m\}$. Conditional on ability $\theta$, item responses are assumed to be locally independent, with category probabilities

$\Pr(Y_i = k \mid \theta) = p_{ik}(\theta), k = 0,\dots,m.$

The expected score for item $i$ at ability level $\theta$ is

$E(Y_i \mid \theta) = \sum_{k=0}^{m} k p_{ik}(\theta).$

The expected total score is the sum of item-level expectations:

$E(S \mid \theta) = E(\sum_{i=1}^{I} Y_i \mid \theta) = \sum_{i=1}^{I} E(Y_i \mid \theta),$

where $S = \sum_{i=1}^{I} Y_i$ denotes the total score.

This function evaluates the above expression numerically using the item category probability matrix produced by compute_icc(). Missing categories (if any) are assumed to have zero probability.

2. ICC input

(1) If icc is a matrix, the expected score is computed directly as

$E(S \mid \theta) = \sum_{i}\sum_{k} k p_{ik}(\theta),$

where $p_{ik}$ denotes the probability that item $i$ produces score $k$ at ability level $\theta$.

(2) If icc is a list, the expected score function $E(S \mid \theta)$ is first evaluated on the grid encoded in names(icc), and a continuous approximation is constructed via linear interpolation. The expected score at target_theta is then obtained from this interpolated test characteristic curve using stats::approxfun(). The numerical accuracy of the interpolated value depends on the density and range of the ability grid used to construct the ICC list.

Value

A single numeric value giving the expected total score $E(S \mid \theta)$ at the specified ability level.

See Also

compute_icc(),

inverse_tcc(),

stats::approxfun()

Examples

## Example 1: Dichotomous model
data("mini_itempool")
icc_mat<-compute_icc(mini_itempool,
                     list("3PL"=c("discrimination","difficulty","guessing")),
                     theta = 0,model_col = "model",D = 1.7)

icc_list<-compute_icc(mini_itempool,
                      list("3PL"=c("discrimination","difficulty","guessing")),
                      theta = seq(-5,5,0.1),model_col = "model",D = 1.7)

expected_score(icc_mat[[1]])
expected_score(icc_list,target_theta=seq(-5,5,0.1))

## Example 2: Polytomous model (PCM)
data("poly_itempool")
icc_mat<-compute_icc(poly_itempool,
                    list("PCM"=c("deltaj1","deltaj2","deltaj3")),
                     theta = 0,model_col = "model")
icc_list<-compute_icc(poly_itempool,
                     list("PCM"=c("deltaj1","deltaj2","deltaj3")),
                     theta = seq(-5,5,0.1),model_col = "model")
expected_score(icc_mat[[1]])
expected_score(icc_list,target_theta=0)

## Example 3: Mixed item format (3PL + GPCM + GRM)
data("Rmst_pool")
icc_mat<-compute_icc(Rmst_pool,
                     item_par_cols = list("3PL"=c("a","b","c"),
                                          "GPCM" = c("alpha","delta1","delta2","delta3"),
                                         "GRM" = c("alpha","beta1","beta2")),
                     theta = 0,model_col = "model")
icc_list<-compute_icc(Rmst_pool,
                      item_par_cols = list("3PL"=c("a","b","c"),
                                           "GPCM" = c("alpha","delta1","delta2","delta3"),
                                           "GRM" = c("alpha","beta1","beta2")),
                      theta = seq(-5,5,0.1),model_col = "model")
expected_score(icc_mat[[1]])
expected_score(icc_list,target_theta=0)

---

Generate population weights over a specified ability grid

Description

Computes normalized weights on a user-specified ability grid theta based on a chosen population distribution. The function evaluates the specified density at each grid point and rescales the resulting values so that the weights sum to 1. The output provides a discrete approximation of the population ability distribution and can be used for marginal summaries in analytic classification accuracy or precision evaluation.

Supports:

• Named base-R distributions via their densities (e.g., norm, t, logis, unif, beta, gamma, lnorm,...).

• Finite mixtures of named distributions

• Empirical distributions via Gaussian-kernel KDE (kernel density estimation)

Weights are normalized so that sum(w) == 1. Use them to approximate expectations:

$\mathbb{E}[f(\theta)] \approx \sum_i w_i f(\theta_i).$

Usage

gen_weight(
  theta = seq(-5, 5, 0.1),
  dist = "norm",
  params = list(mean = 0, sd = 1),
  components = NULL,
  empirical_theta = NULL
)

Arguments

theta	Optional numeric vector specifying the ability grid at which the population distribution is evaluated. Default is seq(-5,5,0.1).
dist	Character string specifying the distribution family: one of norm, t, logis, unif, beta, gamma, lnorm, mixture, empirical. Default is norm.
params	List of parameters for the named distribution (when dist is not "mixture", "empirical"). For example, list(mean = 0, sd = 1) for "norm", list(df = 5) for "t", list(location = 0, scale = 1) for "logis". Default is list(mean = 0, sd = 1).
components	For dist = "mixture": a list of components, each like list(dist = "norm", params = list(mean = 0, sd = 1), weight = 0.7). Component weights are rescaled to sum to 1 if needed.
empirical_theta	For dist = "empirical": numeric sample theta values used to build a KDE.

Value

A dataframe with:

theta

The supplied ability grid.

w

Normalized weights, sum(w) = 1.

Examples

## Standard normal population on a custom grid
theta <- seq(-3, 3, by = 0.2)
gen_weight(theta,dist = "norm")

## Normal population with custom parameters
gen_weight(
  theta,
  dist = "norm",
  params = list(mean = -0.5, sd = 1.2)
)

## Empirical population via KDE
gen_weight(
  theta,
  dist = "empirical",
  empirical_theta = rnorm(1000)
)

## Two-component mixture distribution
gen_weight(
  theta,
  dist = "mixture",
  components = list(
    list(dist = "norm", params = list(mean = -1, sd = 0.8), weight = 0.4),
    list(dist = "norm", params = list(mean =  1, sd = 0.8), weight = 0.6)
  )
)

---

Get Item Categorical/Quantitative Attribute Value

Description

Create a vector representing the attribute value.

Usage

get_attribute_val(itempool, attribute, cat_level = NULL)

Arguments

itempool	A data.frame containing the item pool.
attribute	A string giving the column name in itempool that represents the categorical/quantitative attribute.
cat_level	A optional character string for one category for the categorical attribute. Default is NULL, indicating the attribute is a quantitative attribute.

Value

A vector of item attribute values. The same length as the item pool.

• If the attribute is a quantitative attribute, return a numeric vector. NA is not allowed in the quantitative attribute.

• If the attribute is a categorical attribute, return a binary integer vector with 1 indicating an item having the categorical attribute, 0 indicating an item not having the categorical attribute. If an item has NA in the categorical attribute, it will be coded as 0, indicating this item not having the categorical attribute.

Examples

# Example 1, item categorical attribute
data("mini_itempool")
get_attribute_val(itempool = mini_itempool,attribute = "itemtype",cat_level = "MC")
# Example 2, item quantitative attribute
get_attribute_val(itempool = mini_itempool,attribute = "difficulty",cat_level = NULL)
# Example 3: stimulus categorical attribute
data("reading_itempool")
get_attribute_val(itempool = reading_itempool[!is.na(reading_itempool$pivot_item),],
                  attribute = "stimulus_type",cat_level = "history")
# Example 4: stimulus quantitative attribute
get_attribute_val(itempool = reading_itempool[!is.na(reading_itempool$pivot_item),],
                  attribute = "stimulus_words")

---

Minimize Deviations from Target Goals (Goal Programming)

Description

Implements a goal programming objective that minimizes deviations between achieved objective values and user-specified target goals.

Multiple absolute objective terms are combined into a single optimization problem. Each term contributes one (mode = "one_dev") or two (mode = "two_dev") deviation variables, and the solver minimizes a (weighted) sum of these deviations.

Weights may be assigned to individual objective terms to reflect their relative importance.

Usage

goal_programming_obj(x, multiple_terms, strategy_args = list())

Arguments

x	An object of class mstATA_design created by mst_design().
multiple_terms	A list of objective terms created by objective_term(). The list must contain two or more objective terms. All objective terms must be absolute (goal-based) objectives, meaning that a finite target value goal is specified for each term.
strategy_args	A named list of strategy-specific arguments used by the goal_programming aggregation. Supported fields: mode – Character string specifying the deviation formulation. Must be either "one_dev" (single absolute deviation) or "two_dev" (separate positive and negative deviations). weights – Optional positive numeric vector of length(multiple_term) specifying the relative importance of each objective term. Defaults to a vector of ones.

Details

1. Overview

Goal programming applies when there are two or more objective terms, each formulated as an absolute deviation objective of the form

$|a_k^\top x - g_k|,$

where:

• $a_k^\top x$ is the linear score defined by the objective term;

• $g_k$ is the target value specified by the test developer.

Each objective term is created using objective_term() and may differ in attribute type, attribute level, and target value.

Key characteristics for each objective term:

(1) Requirement type

• Categorical: minimize deviation from a target number of items belonging to a specified category level; or

• Quantitative: minimize deviation from a target sum of item-level quantitative attributes (e.g., difficulty, discrimination, or item information).

(2) Application level

• "Module-level" – only items in a specified module contribute;

• "Pathway-level" – items in all modules belonging to a pathway;

• "Panel-level" – all item selections in the panel contribute.

(3) Objective type

The goal_programming strategy supports absolute objectives only.

2. Deviation Modes

Two deviation formulations are supported:

• One-deviation mode (mode = "one_dev"):

  Introduces one nonnegative deviation variable $d_k \ge 0$ for each term:

  $|a_k^\top x - g_k| \le d_k.$

  The objective minimizes:

  $\min \sum_{k=1}^K w_k d_k.$

• Two-deviation mode (mode = "two_dev"):

  Introduces separate positive and negative deviation variables $d_k^+ \ge 0$ and $d_k^- \ge 0$:

  $a_k^\top x - g_k = d_k^+ - d_k^-.$

  with constraints:

  $a_k^\top x - g_k \le d_k^+$

  $g_k - a_k^\top x \le d_k^-$

  The objective minimizes:

  $\min \sum_{k=1}^K w_k (d_k^+ + d_k^-).$

Interpretation:

• $d_k^+$ measures how much objective $k$ exceeds its target;

• $d_k^-$ measures how much objective $k$ falls short;

• $d_k$ (one-dev) measures total absolute deviation.

Value

An object of S3 class "compiled_objective" with named elements:

name

A string indicating the objective function name

specification

A data.frame summarizing the constraint specification, including the requirement name, attribute, constraint type, application level, operator, and the number of constraint rows generated.

A_binary

A sparse binary matrix representing the linear constraint coefficients.

A_real

A sparse constraint matrix (class "Matrix") for continuous decision variables. Must have the same number of rows as A_binary.

C_binary

A numeric vector of objective coefficients for binary decision variables.

C_real

A numeric vector of objective coefficients for continuous decision variables.

operators

A character vector of constraint operators, one per row of A_binary.

d

A numeric vector of right-hand-side values for the constraints.

sense

Always "min" for the goal_programming strategy.

decisionvar_type_new

A character vector of "B" (binary), same length as ncol(A_real).

decisionvar_name_new

Character vector indicating the names of decision variables, same length as ncol(A_real).

notes

information about "strategy" ("goal_programming") and "strategy_args" ("mode","weights")

Mathematical Formulation

For each objective term $k = 1, \ldots, K$:

$y_k = a_k^\top x,$

where:

• $a_k$ is the coefficient vector defined by the attribute, level, and application scope;

• $x$ is the vector of binary item-module-panel decision variables;

• $g_k$ is the target value.

Auxiliary deviation variables are introduced to linearize $|a_k^\top x - g_k|$, and the solver minimizes a weighted sum of these deviations.

All goal programming problems are compiled as minimization problems.

Examples

data("mini_itempool")

test_mstATA <- mst_design(
  itempool        = mini_itempool,
  design          = "1-3-3",
  exclude_pathway = c("1-1-3", "1-3-1"),
  pathway_length  = 8
)

obj1 <- objective_term(
  test_mstATA, "iif(theta=-1)", NULL,
  "Module-level", which_module = 1,
  sense = "min", goal = 12
)

obj2 <- objective_term(
  test_mstATA, "iif(theta=0)", NULL,
  "Module-level", which_module = 1,
  sense = "min", goal = 15
)

obj3 <- objective_term(
  test_mstATA, "iif(theta=1)", NULL,
  "Module-level", which_module = 1,
  sense = "min", goal = 12
)

# Example 1: One deviation per goal, equal weights
goal_programming_obj(
  x = test_mstATA,
  multiple_terms = list(obj1, obj2, obj3),
  strategy_args = list(mode = "one_dev",weights = NULL))

# Example 2: One deviation per goal, unequal weights
goal_programming_obj(
  x = test_mstATA,
  multiple_terms =  list(obj1, obj2, obj3),
  strategy_args = list(mode = "one_dev",weights = c(1,0.5,1)))

# Example 3: Two deviations per goal
goal_programming_obj(
  x = test_mstATA,
  multiple_terms = list(obj1, obj2, obj3),
  strategy_args = list(mode = "two_dev",weights = NULL))

---

Precomputed MST Panel: Goal_Programming Formulation

Description

A precomputed multistage testing (MST) panel assembled using the goal_programming objective formulation (one_dev) described in the Formulation for Multiple Objectives vignette.

Usage

goal_programming_panel

Format

An object of class mstATA_panel.

Details

This object is included to avoid long solver runtimes during vignette building and package checking.

Source

Generated using mstATA::assembled_panels() and mstATA::solve_model()with the HiGHS solver.

---

Precomputed Hybrid MST Assembly Example

Description

A precomputed MST panel assembled using the hybrid strategy demonstrated in the Three ATA Strategies Vignette.

Usage

Hy13_panel

Format

An object of class mstATA_panel.

Source

Generated using mstATA::assembled_panels() and mstATA::solve_model()with the HiGHS solver.

---

Inverse test characteristic curve

Description

Computes the inverse Test Characteristic Curve (ITCC) by mapping each possible observed total score to its corresponding estimated ability value ($\theta$). The inversion is performed numerically using a dense theta grid and root-finding.

The function supports mixed-format tests, including dichotomous (e.g., 1PL, 2PL, 3PL, 4PL) and polytomous models (e.g., GRM, PCM, GPCM, RSM, NRM), provided the required item parameters are correctly specified in item_par_cols.

For models with guessing (e.g., 3PL/4PL), scores below the lower asymptote are handled using linear interpolation toward the lower bound specified by range_tcc.

Usage

inverse_tcc(
  items,
  item_par_cols,
  model_col,
  D = 1,
  range_tcc = c(-5, 5),
  tol = 1e-04
)

Arguments

items	A data frame containing item metadata. Each row represents an item. The data frame must include a column specifying the item model (see model_col) and the parameter columns referenced in item_par_cols.
item_par_cols	A named list defining the IRT parameter columns required for each supported model. The list names must exactly match the model identifiers specified in items[[model_col]]: "1PL", "RASCH", "2PL", "3PL", "4PL", "GRM", "MGRM", "PCM", "GPCM", "RSM", and "NRM". Each list element is a character vector giving the column names in items that contain the required item parameters for the corresponding model.
model_col	A character string specifying the column name in items that indicates the IRT model used for each item. Values in this column must correspond to the supported model names: "1PL", "RASCH", "2PL", "3PL", "4PL", "GRM", "MGRM", "PCM", "GPCM", "RSM", or "NRM".
D	Scaling constant used in the IRT model. Default is D=1 (for logistic metric); D=1.702 yields approximately the normal metric.
range_tcc	A numeric vector of length two specifying the lower and upper bounds of the theta search interval. The estimated theta values are constrained within this range. Defaults to c(-5, 5).
tol	A numeric tolerance passed to the root-finding algorithm. Smaller values yield more precise solutions at increased computational cost. Default is 1e-4.

Value

A data frame with two columns:

sum.score

All possible observed total scores.

est.theta

Estimated theta corresponding to each total score.

Mathematical Formulation

Consider $I$ items are taken by an examinee. Let the score for item $i$ be a discrete random variable $Y_i$ taking values $\{0, 1, \dots, m\}$, where $m$ is the maximum item score for item i. Conditional on ability $\theta$, item responses are assumed to be locally independent, with category probabilities

$\Pr(Y_i = k \mid \theta) = p_{ik}(\theta),k = 0,\dots,m.$

The expected score for item $i$ at ability level $\theta$ is

$E(Y_i \mid \theta) = \sum_{k=0}^{m} k p_{ik}(\theta),$

and the expected total module score (the test characteristic curve) is

$T(\theta) = E(S \mid \theta) = \sum_{i=1}^{I} E(Y_i \mid \theta),$

where $S = \sum_{i=1}^{I} Y_i$ denotes the total module score.

Given a target score $s^\ast$, the inverse TCC problem is to find $\hat{\theta}$ such that

$T(\hat{\theta}) = s^\ast.$

Because $T(\theta)$ generally has no closed-form inverse, this function evaluates $T(\theta)$ on a grid of ability values using ICCs. A root-finding algorithm is then used to solve

$T(\theta) - s^\ast = 0$

on a specified ability interval.

3PL and Non-Invertible Scores

When items follow the three-parameter logistic (3PL) model with guessing parameters $g_i > 0$, the TCC has a nonzero lower bound:

$\lim_{\theta \to -\infty} TCC(\theta) = \sum_{i=1}^I g_i = G.$

Therefore, any NC score $S < G$ cannot be obtained from the TCC for any finite $\theta$, and the inverse TCC is undefined in the strict sense.

To ensure a monotone score-to-theta mapping, the minimum invertible NC score is defined as

$X = \lceil G \rceil,$

the smallest integer strictly greater than the guessing floor.

Let $\theta_{\min}$ denote the lower bound of the restricted ability range (given by range_tcc[1]), and let $\theta_X$ denote the inverse-TCC solution corresponding to score $X$.

For any score $Y$ such that $0 \le Y < X$, the ability estimate is obtained by linear interpolation between $(0, \theta_{\min}$ and $(X, \theta_X)$:

$\theta^*(Y) = \theta_{\min} + \frac{Y}{X} (\theta_X - \theta_{\min}).$

This construction:

• Preserves monotonicity of the score-to-theta function;

• Respects the lower bound imposed by guessing;

• Ensures continuity at $Y = X$;

• Avoids artificial extrapolation of the TCC.

Scores above the maximum attainable TCC value are mapped to the upper bound range_tcc[2].

Examples

# Example 1: dichotomous items (guessing is not allowed)
items<-data.frame(discrimination = c(1,1),difficulty = c(-1,0),
                  model= rep("2PL",2))
inverse_tcc(items = items,
                 item_par_cols = list("2PL"=c("discrimination","difficulty")),
                 model_col = "model",range_tcc = c(-5,5))

# Example 2: dichotomous items, (guessing is allowed)
items<-data.frame(discrimination = c(1,1),difficulty = c(-1,0),guessing = c(0.2, 0.2),
                  model= rep("3PL",2))
inverse_tcc(items = items,
                 item_par_cols = list("3PL"=c("discrimination","difficulty","guessing")),
                 model_col = "model", range_tcc = c(-5,5))

# Example 3: polytomous items
items <- data.frame(alphaj = c(1.169,1.052,0.828,0.892,0.965),
                    betaj1 = c(-0.006,-2.405,-0.799,-1.148,-0.299),
                    betaj2 = c(0.487,1.125,0.764,-0.289,1.512),
                    model = rep("GRM",5))
inverse_tcc(items = items,
                 item_par_cols = list("GRM"=c("alphaj","betaj1","betaj2")),
                 model_col = "model", range_tcc = c(-5,5))

# Example 4: dichotomous and polytomous items
items <- data.frame(discrimination = c(1,1,rep(NA,5)),
                    difficulty = c(-1,0,rep(NA,5)),
                    alphaj = c(rep(NA,2),1.169,1.052,0.828,0.892,0.965),
                    betaj1 = c(rep(NA,2),-0.006,-2.405,-0.799,-1.148,-0.299),
                    betaj2 = c(rep(NA,2),0.487,1.125,0.764,-0.289,1.512),
                    model = c(rep("2PL",2),rep("GRM",5)))
inverse_tcc(items = items,
                 item_par_cols = list("2PL"=c("discrimination","difficulty"),
                                      "GRM"=c("alphaj","betaj1","betaj2")),
                 model_col = "model", range_tcc = c(-5,5))

---

Generate Item-Level Constraints to Explicitly Select or Not Select Specific Items

Description

This function generates linear constraints that require specific items to be either must be selected or not selected in a multistage test (MST) panel assembly.

If item_module_eligibility is supplied in mst_design() and the requested item selection conflicts with module eligibility restrictions, an error is thrown.

For details about item_module_eligibility, see mst_design().

Constraints may be applied at the "Module-level", "Pathway-level", or "Panel-level".

If item_module_eligibility is NULL, the number of constraints is:

• Module-level: when which_module is provided and which_pathway = NULL

  The number of constraints is (number of items in item_ids) x (number of specified modules)

• Pathway-level: when which_pathway is provided and which_module = NULL

  The number of constraints is (number of items in item_ids) x (number of specified pathways)

• Panel-level: both which_module and which_pathway are NULL

  The number of constraints is (number of items in item_ids)

Usage

itemcat_con(
  x,
  item_ids,
  select = TRUE,
  which_module = NULL,
  which_pathway = NULL
)

Arguments

x	An object of class "mstATA_design" created by mst_design().
item_ids	A numeric vector of item row indices, or a character vector of item IDs from x$ItemPool.
select	Logical. Indicates whether items in item_ids must be TRUE (selected) or FALSE (not selected). Default = TRUE.
which_module	Optional integer vector of module indices to which the constraints apply.
which_pathway	Optional integer vector of pathway indices to which the constraints apply.

Details

1. Specification

The constraint enforced by this function is:

Items listed in item_ids must (or must not) be selected.

Key characteristics:

• The attribute type is categorical (each item has a unique ID).

• The attribute is defined at the item-level in the item pool.

• Application levels:

  • Module-level: enforce selection in specific module(s).

  • Pathway-level: enforce selection in any module of a pathway.

  • Panel-level: enforce selection somewhere in the panel.

2. Examples of Interpretation

• Item i must be selected in the routing module (Module-level): item_ids = i, which_module = 1

• Item i must be selected in Stage 2 easy and medium modules (modules not belonging to the same pathway) (Module-level): which_module = c(2,3)

• Item i must be selected in the RM pathway (Pathway-level): which_pathway = 2

• Item i must appear somewhere in the assembled panel (Panel-level): which_module = NULL, which_pathway = NULL

3. Interaction with panel_itemreuse_con()

When overlap = FALSE in panel_itemreuse_con(), each item can at most be selected once in a panel.

Therefore:

• which_module or which_pathway must be a scalar (not a vector).

• If both are NULL, the constraint simply enforces that the item must appear somewhere in the panel, without specifying the module/pathway.

When overlap = TRUE in panel_itemreuse_con(), each item can at most be selected once in a pathway, but each item may be selected in multiple modules within the same stage.

Therefore:

• which_module may be a vector (can not be modules that appear in the same pathway)

Value

An object of S3 class "mstATA_constraint" with named elements:

name

A character vector indicating the specifications in each row of A_binary

specification

A data.frame summarizing the constraint specification, including the requirement name, attribute, constraint type, application level, operator, and the number of constraint rows generated.

A_binary

A sparse binary matrix representing the linear constraint coefficients.

A_real

NULL for 'mstATA_constraint' object

operators

A character vector of constraint operators, one per row of A_binary.

d

A right-hand-side vector of 1s or 0s depending on whether select is TRUE or FALSE.

C_binary

NULL for 'mstATA_constraint' object

C_real

NULL for 'mstATA_constraint' object

sense

NULL for 'mstATA_constraint' object

Mathematical Formulation

Suppose the item pool contains (S - 1) stimulus-based item sets, indexed by $s = 1, \ldots, S - 1$. Each stimulus has a designated pivot item, indexed by $i^*_s$. In addition, the pool contains a set of discrete (non-stimulus-based) items, which are represented by a dummy stimulus $s = S$ to allow a unified indexing scheme. Items belonging to stimulus $s$ are indexed as $i_s = 1, 2, \ldots, I_s$.

Suppose there are $M$ modules in an MST panel. Let $m = 1, \ldots, M$ denote the module index.

1. Module-level item selection/not selection

In specified module m: for all $i_s$ specified in item_ids

$x_{i_s,m} = 1$ if item $i_s$ must be selected in module m.

$x_{i_s,m} = 0$ if item $i_s$ must not be selected in module m.

2. Pathway-level item selection/not selection

In specified pathway r: for all $i_s$ specified in item_ids

$\sum_{m \in r} x_{i_s,m} = 1$ if item $i_s$ must be selected in pathway r.

$\sum_{m \in r} x_{i_s,m} = 0$ if item $i_s$ must not be selected in pathway r.

3. Panel-level item selection/not selection

In a panel: for all $i_s$ specified in item_ids

$\sum_{m} x_{i_s,m} = 1$ if item $i_s$ must be selected in a panel.

$\sum_{m} x_{i_s,m} = 0$ if item $i_s$ must not be selected in a panel.

Here:

• $x_{i_s, m}$ is the binary decision variable indicating whether item $i_s$ is selected into module m.

• $m \in r$ denote modules belonging to pathway r.

See Also

mst_design(),

panel_itemreuse_con()

Examples

data("mini_itempool")
test_mstATA <- mst_design(
  itempool = mini_itempool,
  design = "1-3-3",
  module_length = c(4,2,2,2,2,2,2)
)

# Example 1: Item 2 must be selected in the routing module
itemcat_con(x = test_mstATA, item_ids = 2, select = TRUE, which_module = 1)

# Example 2: Item 2 must appear somewhere in the MST panel
itemcat_con(x = test_mstATA, item_ids = 2, select = TRUE)

# Example 3: Item 2 must be selected in Stage 2 easy and medium modules
itemcat_con(x = test_mstATA, item_ids = 2, select = TRUE, which_module = c(2,3))

# Example 4: Item 2 must be selected in the REE pathway
itemcat_con(x = test_mstATA, item_ids = 2, select = TRUE, which_pathway = 1)

# Example 5: Items 1 and 3 must be selected in the routing module
itemcat_con(x = test_mstATA, item_ids = c(1,3), select = TRUE, which_module = 1)

# Example 6: Items 1 and 3 must be selected in the REE pathway
itemcat_con(x = test_mstATA, item_ids = c(1,3), select = TRUE, which_pathway = 1)

# Example 7: Items 1 and 3 must appear somewhere in the panel
itemcat_con(x = test_mstATA, item_ids = c(1,3), select = TRUE)


# Example 8: With item_module_eligibility provided
mini_itempool <- mini_itempool[order(mini_itempool$difficulty), ]
item_module_eligibility <- list(
  `2` = 1:15,
  `3` = 11:25,
  `4` = 15:30
)

new_test_mstATA <- mst_design(
  itempool = mini_itempool,
  design = "1-3-3",
  module_length = c(6,4,4,4,3,3,3),
  item_module_eligibility = item_module_eligibility
)
itemcat_con(new_test_mstATA, item_ids = 2, select = TRUE, which_module = 2)

# This call produces an error because item 2 is not eligible for module 3
try(itemcat_con(new_test_mstATA, item_ids = 2, select = TRUE, which_module = c(2,3)))

---