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.

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.

Compute Item Response Category Probabilities and Derivatives

Description

Computes item response category probabilities under various IRT models at a given ability value \theta.

Usage

Pi_internal(theta, itempar_mat, model = NULL, D = 1)

Arguments

Details

(1) Dichotomous IRT models

For the models "1PL", "RASCH", "2PL", "3PL", and "4PL", the argument itempar_mat must be a numeric matrix with one row per item and four columns: discrimination (a_j), difficulty (b_j), guessing (c_j),upper (d_j).

(2) Polytomous IRT models

For a polytomous item j, let g_j denote the maximum score, so that the possible response categories are 0, 1, \ldots, g_j.

The number of response categories may vary across items under the "GRM", "PCM", "GPCM", and "NRM" models. In contrast, under the "MGRM" and "RSM" models, the number of response categories is assumed to be the same for all items.

The argument itempar_mat must be a numeric matrix with one row per item and a number of columns determined by the specified IRT model. The required structure is:

• GRM: A matrix with \max_j g_j + 1 columns, containing parameters (\alpha_j, \beta_{j1}, \ldots, \beta_{j g_j}), where \alpha_j is the discrimination parameter and \beta_{jk} are the ordered threshold parameters.

• MGRM: A matrix with g_j + 2 columns, containing parameters (\alpha_j, b_j, c_{j1}, \ldots, c_{j g_j}), where \alpha_j is the discrimination parameter, b_j is the location parameter, and c_{jk} are category step parameters.

• PCM: A matrix with \max_j g_j columns, containing step parameters (\delta_{j1}, \ldots, \delta_{j g_j}).

• GPCM: A matrix with \max_j g_j + 1 columns, containing parameters (\alpha_j, \delta_{j1}, \ldots, \delta_{j g_j}), where \alpha_j is the discrimination parameter and \delta_{jk} are step parameters.

• RSM: A matrix with g + 1 columns, containing parameters (\lambda_j, \delta_1, \ldots, \delta_g), where \lambda_j is the item location parameter and \delta_k are common step parameters across items.

• NRM: A matrix with 2 \max_j g_j columns, containing parameters (\alpha_{j1}, c_{j1}, \alpha_{j2}, c_{j2}, \ldots, \alpha_{j g_j}, c_{j g_j}), where \alpha_{jk} and c_{jk} are the slope and intercept parameters for category k.

Value

A list with components:

Pi

A matrix of category response probabilities. Rows correspond to items and columns correspond to categories.

dPi

Matrix of first derivatives \partial P_{jk}.

Item pool from Rmst for examples

Description

A data frame containing 400 3PL items, 20 GPCM items, and 20 GRM items. This item pool is adapted from the example item pool used to demonstrate multistage test assembly in the Rmst package.

Usage

data(Rmst_pool)

Format

A data frame with 440 rows and 14 variables:

Item_id

Unique identifier for each item.

model

IRT model specification for the item (e.g. "3PL", "GPCM", "GRM").

a

Discrimination parameter (a) for the 3PL model.

b

Difficulty parameter (b) for the 3PL model.

c

Guessing parameter (c) for the 3PL model.

alpha

Discrimination parameter (\alpha) for GPCM and GRM models.

delta1

First step parameter (\delta_1) for the GPCM model.

delta2

Second step parameter (\delta_2) for the GPCM model.

delta3

Third step parameter (\delta_3) for the GPCM model.

beta1

First threshold parameter (\beta_1) for the GRM model.

beta2

Second threshold parameter (\beta_2) for the GRM model.

content

Content category classification of the item.

time

Item time.

group

Item group identifier.

References

Luo, X. (2019). Rmst: Computerized Adaptive Multistage Testing. R package version 0.0.3. doi:10.32614/CRAN.package.Rmst. https://CRAN.R-project.org/package=Rmst

Examples

data(Rmst_pool)

Precomputed Top-Down MST Assembly Example (TD123)

Description

A precomputed MST panel assembled using the top-down strategy with the HiGHS solver. Included to avoid long runtime during vignette building.

Usage

TD123_panel

Format

An object of class mstATA_panel.

Source

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

Precomputed Top-Down MST Assembly Example (TD12)

Description

A precomputed MST panel assembled using the top-down strategy with the HiGHS solver demonstrated in the Three ATA Strategies Vignette.

Usage

TD12_panel

Format

An object of class mstATA_panel.

Source

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

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

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

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

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.

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

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.

Check the item-level categorical and quantitative attribute in the itempool

Description

Confirm that the specified column exists in the item pool.

Usage

check_attribute_column(itempool, attribute)

Arguments

Value

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

• Quantitative attribute: Returns a numeric vector. Missing values (NA) are not allowed; a warning message will be issued if they are detected.

• Categorical attribute: Returns a factor vector indicating the category to which each item belongs. Missing values (NA) are allowed and indicate that the corresponding item does not belong to any category for this attribute.

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

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

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()

Compile a Capped-Maximin Objective

Description

Implements the capped-maximin objective aggregation strategy, which seeks to maximize a common lower bound across multiple objective terms while penalizing excessive deviation above that bound.

The capped-maximin strategy balances multiple competing objectives by maximizing the worst-performing (scaled) objective, while allowing limited flexibility through an overflow parameter.

This function is automatically called by compile_objective() when strategy = "capped_maximin".

Usage

compile_capped_maximin_(
  x,
  obj_set,
  strategy = "capped_maximin",
  strategy_args = list()
)

Arguments

Details

Optimization Formulation

Let there be K objective terms, each defined by a linear score:

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

where:

• a_k is the coefficient vector constructed by objective_term();

• x denotes the binary item-module-panel decision variables;

• p_k > 0 is a user-specified proportions that scales the relative importance of objective k.

The capped-maximin strategy introduces two auxiliary continuous variables:

• y, representing a common lower bound on the scaled objective values;

• \delta, representing the maximum allowed overflow above this bound.

The optimization problem is:

\max y - \delta

subject to the constraints:

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

This formulation ensures that all objective scores are kept close to a common proportional baseline, while allowing controlled deviation when perfect balance is infeasible.

Interpretation

• The variable y captures the worst-case normalized objective value across all terms.

• The variable \delta controls how much any objective is allowed to exceed its proportional share.

• Maximizing y - \delta simultaneously encourages fairness across objectives and limits excessive dominance by any single objective.

Compared to standard maximin, capped-maximin provides greater numerical stability and flexibility, especially when objective terms differ substantially in scale.

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

Sparse matrix of coefficients for binary decision variables.

A_real

Sparse matrix of coefficients for real 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.

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

A list containing the strategy name, strategy arguments, and y_bounds.

Compile a Goal Programming Objective

Description

This internal helper constructs the compiled objective structure used by the solver when the optimization problem follows a goal programming strategy.

Goal programming minimizes deviations between achieved objective values and user-specified target goals. Each objective term contributes a deviation variable, and the solver minimizes a (weighted) sum of these deviations.

This function is automatically called by compile_objective() when strategy = "goal_programming".

Usage

compile_goal_programming_(
  x,
  obj_set,
  strategy = "goal_programming",
  strategy_args = list()
)

Arguments

Details

Optimization Form

Let there be K objective terms, each defined as a linear score

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 item-module-panel decision variables.

Each term has a target value g_k. Goal programming minimizes deviations between y_k and g_k.

\min \sum_k w_k d_k

where w_k > 0 are user-specified or default weights.

Two deviation modes are supported:

• One-deviation mode (mode = "one_dev"): Introduces a single non-negative deviation variable d_k \ge 0 per objective term such that

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

• Two-deviation mode (mode = "two_dev"): Introduces separate positive and negative deviations d_k^+ \ge 0 and d_k^- \ge 0, with

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

Interpretation The compiled objective minimizes a weighted sum of deviations:

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

in one-deviation mode, or

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

in two-deviation mode, where w_k are user-specified or default weights.

All goal programming objectives are compiled as minimization problems.

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

Sparse matrix of coefficients for binary decision variables.

A_real

Sparse matrix of coefficients for real 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.

C_binary

Penalty vector for binary variables (if any)

C_real

Penalty vector for real variables (if any)

sense

Always "min" for the goal_programming 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

A list containing the strategy name, strategy arguments, and y_bounds.

Compile a Maximin Objective

Description

Implements the maximin objective aggregation strategy, which maximizes the minimum normalized score across multiple objective terms.

The optimization problem is:

\max \min_{k = 1,\ldots,K} ( \frac{a_k^\top x}{p_k} ),

where each objective term is a linear score a_k^\top x, and p_k > 0 is a user-specified (or default) proportions that scales the relative importance of term k.

This function is automatically called by compile_objective() when strategy = "maximin".

Usage

compile_maximin_(x, obj_set, strategy = "maximin", strategy_args = list())

Arguments

Details

Optimization Formulation

Let there be K objective terms, each defined as a linear score:

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

where:

• a_k is the coefficient vector constructed by objective_term();

• x denotes the binary item-module-panel decision variables;

• p_k > 0 is the proportions used to normalize objective k.

The maximin strategy introduces a common auxiliary variable y representing the minimum normalized score across all objectives, and maximizes this value.

\max y

subject to:

\frac{a_k^\top x}{p_k} \ge y, k = 1, \ldots, K.

Overflow Control via delta

Two formulations are supported depending on the value of delta.

• Without overflow control (delta = Inf):

  a_k^\top x \ge p_k \, y, k = 1, \ldots, K.

  This is the classical maximin formulation, which only enforces a lower bound on each objective term.

• With overflow control (delta < Inf):

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

  This bounded formulation prevents any single objective from excessively exceeding the common minimum by more than \delta_k, improving numerical stability and solution balance.

  It is worth noting that when delta is included, the key difference between the "capped_maximin" and "maximin" strategies lies in how delta is treated in the optimization formulation.

  For "capped_maximin", delta appears directly in the objective function. In contrast, for "maximin", delta does not appear in the objective function.

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

Sparse matrix of coefficients for binary decision variables.

A_real

Sparse matrix of coefficients for real 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.

C_binary

Penalty vector for binary variables (if any)

C_real

Penalty vector for real variables (if any)

sense

Always "max" for the 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

A list containing the strategy name, strategy arguments, and y_bounds.

Compile a Minimax Objective

Description

Constructs the compiled objective structure for the minimax strategy, which minimizes the worst-case deviation from target values across multiple objective terms.

The minimax strategy seeks a solution that balances objectives by controlling the largest absolute mismatch between each linear score a_k^\top x and its target value g_k.

This function is automatically invoked by compile_objective() when strategy = "minimax".

Usage

compile_minimax_(x, obj_set, strategy = "minimax", strategy_args = list())

Arguments

Details

1. Overview

Let there be K objective terms, each defined as a linear score

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 vector of item-module-panel decision variables.

Each objective term has a user-specified target value g_k.

The minimax strategy minimizes the maximum deviation from these targets, producing a solution that controls the worst-performing objective.

Two deviation modes are supported:

• One-deviation mode (mode = "one_dev"): Introduces a common non-negative deviation variable d \ge 0 such that

  |a_k^\top x - g_k| \le d.

• Two-deviation mode (mode = "two_dev"): Introduces separate positive and negative deviations d^+ \ge 0 and d^- \ge 0, with

  a_k^\top x - g_k = d^+ - d^-.

2. Optimization Form

Introduce one/two continuous auxiliary variable d or d^+,d^- representing the maximum deviation across all objective terms. The optimization problem is:

\min d

or

\min d^+ + d^-

subject to:

one_dev

|a_k^\top x - g_k| \le d, k = 1, \ldots, K.

two_dev

a_k^\top x + d^- \le g_k , k = 1, \ldots, K

a_k^\top x -d^+ \le g_k, k = 1, \ldots, K

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

Sparse matrix of coefficients for binary decision variables.

A_real

Sparse matrix of coefficients for real 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.

C_binary

Penalty vector for binary variables (if any)

C_real

Penalty vector for real variables (if any)

sense

Always "min" for the minimax 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

A list containing the strategy name, strategy arguments, and y_bounds.

Compile a Single Linear Objective Term

Description

This internal helper constructs the compiled objective structure used by the solver when the optimization problem contains exactly one objective term.

In the single-objective case, the optimization reduces to maximizing or minimizing a single linear score:

\max y

\min y

where y = a^\top x is the linear objective term created by objective_term().

This function is automatically called by compile_objective() when strategy = "single" in objective_set().

Usage

compile_single_(x, obj_set, strategy = "single", strategy_args = list())

Arguments

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

Sparse matrix of coefficients for binary decision variables.

A_real

Sparse matrix of coefficients for real 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.

C_binary

Penalty vector for binary variables (if any)

C_real

Penalty vector for real variables (if any)

sense

"min" or "max"

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

A list containing the strategy name, strategy arguments, and y_bounds.

Compile a Weighted-Sum Objective

Description

This function compiles a weighted-sum objective when multiple objective components are present. Each component contributes a linear score, and the solver optimizes a weighted linear combination of these scores.

The weighted-sum strategy is the simplest and most flexible multi-objective formulation. It is appropriate when objective components are commensurate (i.e., comparable in scale) or when weights can be meaningfully justified based on operational priorities. It is also the only strategy that allows combining multiple compiled objectives produced by other multi-objective formulations (e.g., maximin, capped maximin, minimax, or goal programming) into a single final objective.

Under this strategy, multiple linear objective components are aggregated into one objective function by forming a weighted linear combination.

Usage

compile_weighted_sum_(
  x,
  obj_set,
  strategy = "weighted_sum",
  strategy_args = list()
)

Arguments

Details

Optimization Form

Let there be K objective terms, each defined as a linear score

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 item-module-panel decision variables.

The weighted-sum objective optimizes:

\min \sum_{k=1}^K w_k y_k

\max \sum_{k=1}^K w_k y_k

where w_k > 0 are user-specified or default weights.

Interpretation

This strategy is appropriate when:

• All objective terms can be meaningfully combined on a common scale, and

• The test developer is willing to trade off performance across multiple objectives using explicit weights.

The weighted-sum approach reduces a multi-objective optimization problem to a single linear objective that can be handled directly by standard mixed-integer solvers.

This function is automatically invoked by compile_objective() when strategy = "weighted_sum".

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

Sparse matrix of coefficients for binary decision variables.

A_real

Sparse matrix of coefficients for real 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.

C_binary

Penalty vector for binary variables (if any)

C_real

Penalty vector for real variables (if any)

sense

"min" or "max"

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 metadata.

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

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

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

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

Discrete convolution of score distributions

Description

Computes the probability distribution of the sum of two independent integer-valued score variables by discrete convolution.

Usage

convolve_probs(p, q)

Arguments

Details

Let X and Y be independent random variables representing scores with supports \{0,\dots,m\} and \{0,\dots,n\}, respectively. Suppose their probability mass functions are

\Pr(X = k) = p_k, k = 0,\dots,m

and

\Pr(Y = \ell) = q_\ell, \ell = 0,\dots,n.

The probability mass function of the sum S = X + Y is given by the discrete convolution

\Pr(S = s) = \sum_{k=0}^{s} p_k\,q_{s-k},s = 0,\dots,m+n.

This function evaluates the above convolution numerically using convolve. Since stats::convolve() computes cross-correlation by default, the second argument is reversed internally to obtain the true convolution.

In multistage testing (MST) and item response theory (IRT) applications, this operation is used to combine item- or module-level score distributions into a distribution for their total score at a given ability level \theta.

Value

A numeric vector of length m + n + 1 giving the probability distribution of the sum S = X + Y. The s-th element corresponds to \Pr(S = s) for s = 0,\dots,m+n.

See Also

convolve

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

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 an mstATA Optimization Model Object

Description

Constructs an "mstATA_model" object that encapsulates a mixed-integer linear optimization model used in automated test assembly (ATA).

The model consists of linear constraints defined over binary and continuous decision variables, optional model specifications for bookkeeping, and optimization metadata (objective sense and variable bounds). This function performs extensive input validation to ensure internal consistency between constraint matrices, decision variables, and bounds.

Usage

create_model(
  name,
  specification,
  A_binary,
  A_real,
  C_binary,
  C_real,
  operators,
  d,
  decisionvar_name,
  decisionvar_type,
  sense,
  lb_bound,
  ub_bound
)

Arguments

Details

The constraint system is represented as:

A_B x_B + A_C x_C (op) b

where x_B are binary decision variables and x_C are continuous decision variables.

The objective function is defined as:

\min/\max C_B^\top x_B + C_C^\top x_C

Continuous decision variables are subject to lower and upper bounds specified by lb_bound and ub_bound. Binary variables are implicitly bounded in \{0, 1\}.

Value

An object of class "mstATA_model", represented as a named list containing constraint matrices, objective coefficients, decision variable metadata, bounds, and optimization sense.

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 constraint matrix (class "Matrix") for binary decision variables. Rows correspond to constraints; columns correspond to binary decision variables.

A_real

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

A

Constraint coefficient matrix (sparse or dense).

C_binary

A numeric vector of objective coefficients for binary decision variables.

C_real

A numeric vector of objective coefficients for continuous decision variables.

obj

Objective function coefficient vector.

d

Right-hand-side vector of constraints.

operators

Constraint operators (e.g., "<=", ">=", "=").

vtype

Decision variable types ("B" for binary, "C" for continuous).

varname

Decision variable names.

lb

Lower bounds for decision variables.

ub

Upper bounds for decision variables.

sense

Optimization sense ("min" or "max").

Create Pathways Based an MST Design

Description

Generates all possible pathways implied by a multistage test (MST) design and assigns module difficulty labels when available. If difficulty levels are not supplied, default labels are applied for stages containing up to five modules.

Usage

create_pathways(design, diff_levels = NULL, exclude_pathways = NULL)

Arguments

Details

1. Difficulty labels

When diff_levels = NULL, default difficulty labels are assigned for stages with up to five modules:

• 1 module: "M"

• 2 modules: "E", "H"

• 3 modules: "E", "M", "H"

• 4 modules: "XE", "E", "H", "XH"

• 5 modules: "XE", "E", "M", "H", "XH"

If any stage contains more than five modules and diff_levels is not provided, a message is issued and pathway difficulty labels are omitted from the output. In such cases, users are encouraged to supply a custom diff_levels list to ensure meaningful interpretation of module difficulty.

2. Excluding pathways

The exclude_pathways argument allows users to remove specific module combinations from the set of possible pathways.

For example, under a "1-3-3" MST design:

• All possible pathways (1 x 3 x 3 = 9) are: c("1-1-1", "1-1-2", "1-1-3", "1-2-1", "1-2-2", "1-2-3", "1-3-1", "1-3-2", "1-3-3")

• If extreme transitions are not permitted, one may specify: exclude_pathways = c("1-1-3", "1-3-1")

• This excludes transitions such as easy-to-hard ("1-1-3") and hard-to-easy ("1-3-1").

Value

A list with two data frames:

Modules

A data frame containing module-level information with columns stage, module, and module_index.

Pathways

A data frame describing all constructed pathways. Includes one column per stage (e.g., stage1, stage2, ...), a pathway identifier, and an allowed indicator. If difficulty labels are available, an additional column pathway_label is included.

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

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

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

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

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

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

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

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

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.

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

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

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)))

Generate Item-Level Constraints Requiring Quantitative Attributes to Satisfy Lower, Upper, or Range Bounds (Not for Operational Use)

Description

This function constructs linear constraints enforcing that every selected item satisfies a quantitative attribute requirement (e.g., difficulty greater than c, item length less than c, discrimination within a range).

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

This function is for demonstration only and is not intended for operational use. It generates an excessively large number of rows in the constraint matrix and requires item-level attributes to be strictly positive.

The number of generated linear constraints depends on the application level:

• Module-level: when which_module is provided

  The number of constraints is (number of items) x (number of modules specified) x side

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

  The number of constraints is (number of items) x (number of unique modules in specified pathways) x side

• Panel-level: both which_module and which_pathway are NULL

  The number of constraints is (number of items) x (total number of modules) x side

where side = 1 for one-sided constraints (min-only or max-only) and side = 2 when both min and max are provided and min is not equal to max.

Usage

itemquant_con(
  x,
  attribute,
  min = NULL,
  max = NULL,
  which_module = NULL,
  which_pathway = NULL
)

Arguments

Details

1. Specification

The constraint enforces:

Each selected item must satisfy the specified quantitative lower bound, upper bound, or both.

Key characteristics:

• The attribute type is quantitative.

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

• Application levels:

  • Module-level: enforce items selected in specific module(s) satisfy the quantitative requirement.

  • Pathway-level: enforce items selected in any module of a pathway satisfy the quantitative requirement.

  • Panel-level: enforce items selected in the panel satisfy the quantitative requirement.

2. Important Restriction

There are two reasons this approach is discouraged. First, item-level quantitative constraints generate an excessively large number of constraint rows, leading to poor computational efficiency. Second, the formulation requires scaling item-selection variables by the attribute value q_{i_s}. If q_{i_s} is zero or negative, the resulting inequalities become invalid.

Because many commonly used item attributes (e.g., IRT difficulty parameters or centered text indices) may take zero or negative values, this function is not suitable for operational MST assembly.

Instead, per-item quantitative rules should be enforced during the design stage using item_module_eligibility() within mst_design(), which excludes ineligible items prior to module assembly.

Value

This function always throws an error indicating that it is not for operational use.

It is retained solely as an illustrative example of how item-level quantitative constraints propagate through different hierarchical levels of an MST design.

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 q_{i_s} be the quantitative attribute value of item i_s.

Upper-bound constraint:

q_{i_s} \, x_{i_s, m} \le b_q^{item,max}

Lower-bound constraint:

b_q^{item,min} \, x_{i_s, m} \le q_{i_s}

For two-sided range constraints, both inequalities are included. (min and max both provided and not equal), the number of constraints is doubled (side = 2). For one-sided constraints, side = 1.

Here:

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

• q_{i_s} (must be positive values) denote the values of a quantitative attribute for item i_s.

• b_q^{item,min} and b_q^{item,max} are the lower and upper allowable bounds for the attribute q_{i_s}.

See Also

mst_design()

Compute joint/cumulative score distribution under routing

Description

Computes the joint (cumulative) score distribution after administering a next-stage module, conditional on routing into a branch defined by a set of reachable previous scores.

This function performs a convolution between:

• the conditional score distribution from previous stages, and

• the score distribution of the next module.

The returned distribution is not normalized: for each theta column, the column sum equals the probability of routing into this branch at that theta, which does not necessarily have to be 1.

Usage

joint_module_score_dist(
  cdist_by_prev,
  prev_scores,
  icc_by_next_mod,
  possible_joint_score
)

Arguments

Details

Let S_{prev} denote the cumulative score prior to the current stage, and S_{next} the score from the next-stage module. This function computes:

P(S = s \mid \theta) = \sum_{k} P(S_{prev} = k \mid \theta) \, P(S_{next} = s - k \mid \theta)

for all s in possible_joint_score.

Value

A numeric matrix with:

• rows corresponding exactly to possible_joint_score,

• columns corresponding to theta points.

Each column represents the (unnormalized) joint score distribution at that theta.

Examples

## toy previous score distribution
prev_scores <- 0:2
cdist_by_prev <- matrix(
  c(0.2, 0.3,
    0.5, 0.4,
    0.3, 0.3),
  nrow = 3,
  dimnames = list(NULL, c("theta=-1", "theta=0"))
)

## simple ICC: two items, dichotomous
icc <- matrix(
  c(0.4, 0.6,
    0.7, 0.3),
  nrow = 2,
  byrow = TRUE
)
colnames(icc) <- c("0", "1")

icc_by_next_mod <- list(
  "theta=-1" = icc,
  "theta=0"  = icc
)

possible_joint_score <- c(1, 2, 3)

joint_module_score_dist(
  cdist_by_prev,
  prev_scores,
  icc_by_next_mod,
  possible_joint_score
)

Maximin objective (with optional overflow band)

Description

Implements a maximin objective that maximizes a common floor value y across K linear objective scores u_k = a_k^\top x.

The compiled constraints enforce:

a_k^\top x \ge p_k y, k = 1,\dots,K,

and, if an overflow bound delta is finite for term k,

a_k^\top x \le p_k y + \delta_k.

Usage

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

Arguments

Details

1. Overview

The maximin strategy applies when there are two or more objective terms. Each objective term represents a linear score of the form

y_k = a_k^\top x,

constructed by objective_term().

The goal is to maximize the minimum (normalized) score across all terms, ensuring balanced performance rather than optimizing any single criterion.

Key characteristics for each objective term:

(1) Attribute type

Each objective term may be defined using either:

• a categorical attribute – maximizing or minimizing the number of items belonging to a specific category level; or

• a quantitative attribute – maximizing or minimizing the sum of item-level attribute values (e.g., difficulty, discrimination, item information function values).

(2) Application level

Objective terms may be applied at one of three hierarchical levels:

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

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

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

(3) Objective type

The maximin strategy supports relative objectives only:

• Relative objective: maximize a_k^\top x.

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

2. Proportions and normalization

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

By default, p_k = 1 for all terms.

3. Overflow control via delta

Two formulations are supported depending on the value of delta:

• Without overflow control (delta = Inf):

  a_k^\top x \ge p_k y, k = 1, \ldots, K.

  This is the classical maximin formulation, enforcing only a lower bound on each objective score.

• With overflow control (delta < Inf):

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

  This bounded formulation limits how far any single objective score may exceed the common floor, improving balance and numerical stability.

Value

A list of class "compiled_objective"

name

A character vector indicating the specifications in each row of A_binary

specification

A data.frame including "Requirement","Attribute","Type","Application Level","Operator","Num of Constraints"

A_binary

A sparse constraint matrix (class "Matrix") for binary decision variables. Rows correspond to constraints; columns correspond to binary decision variables.

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 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 metadata.

Mathematical Formulation

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

y_k = a_k^\top x.

Introduce a continuous auxiliary variable y representing the minimum normalized score. The maximin optimization problem is:

\max y

subject to:

y_k \ge p_k y, k = 1,\ldots,K,

and optionally,

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

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
)

# Example 1: 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"
)


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

Precomputed MST Panel: Maximin Formulation

Description

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

Usage

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.

Example mini item pool for MST

Description

A simulated mini item pool for demonstrating MST functionality.

Usage

data(mini_itempool)

Format

A data frame with 30 rows and 7 columns:

item_id

Unique identifier for each item

content

Content area classification (e.g., content1, content2, content3, content4).

itemtype

Item format (e.g., MC, TEI).

time

Expected response time for the item.

discrimination

Discrimination parameter (a) for the 3PL model.

difficulty

Difficulty parameter (b) for the 3PL model.

guessing

Guessing parameter (c) for the 3PL model.

model

Item response theory (IRT) model used for the item (3PL).

nrCat

Integer specifying the maximum number of response categories generated for the item.

enemy_cluing

enemy information 2

enemy_similarity

enemy information 1

stimulus

associated stimulus information

iif(theta=-1)

item information value at -1

iif(theta=0)

item information value at 0

iif(theta=1)

item information value at 1

Examples

data(mini_itempool)

Minimize A Common Maximum Deviation From Target Goals

Description

Implements a minimax (goal-based) objective that minimizes a common ceiling on deviations from multiple target values.

Let there be K objective terms with linear scores y_k = a_k^\top x and target values g_k. The minimax objective minimizes the largest deviation from these targets across all terms.

A common deviation variable is introduced so that no objective deviates from its target by more than this value.

Usage

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

Arguments

Details

1. Overview

Each objective term is created using objective_term() and represents a linear score of the form:

y_k = a_k^\top x,

where a_k is a coefficient vector defined by the attribute, attribute level, and application scope, and x denotes the item-module-panel decision variables.

Each term has an associated target value g_k.

The minimax strategy seeks a solution that minimizes the worst-case deviation across all objective terms.

Key characteristics for each objective term:

(1) Categorical or Quantitative

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

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

(2) Applied at One of Three Levels

• "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) Only Absolute Objectives

The minimax strategy applies only to absolute (goal-based) objectives. Relative objectives without targets are not supported.

2. Deviation modes

Two equivalent deviation formulations are supported via strategy_args$mode:

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

  Introduces a single nonnegative deviation variable d \ge 0 representing the largest absolute deviation across all objectives.

  For each objective term:

  |a_k^\top x - g_k| \le d.

  The optimization problem is:

  \min d.

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

  Introduces two nonnegative deviation variables: d^+ \ge 0 (maximum overflow) and d^- \ge 0 (maximum shortage).

  For each objective term:

  a_k^\top x - g_k \le d^+

  g_k - a_k^\top x \le d^-

  The optimization problem is:

  \min (d^+ + d^-).

Interpretation

• d (one-dev) measures the largest absolute deviation from any target;

• d^+ measures the largest amount by which any objective exceeds its target;

• d^- measures the largest amount by which any objective falls short of its target.

Value

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

name

A string indicating the objective function name.

A_binary

A sparse constraint matrix (class "Matrix") for binary decision variables. Rows correspond to constraints; columns correspond to binary decision variables.

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 "min" for the minimax strategy.

decisionvar_type_new

Types of auxiliary variables (continuous).

decisionvar_name_new

Names of auxiliary variables.

notes

Metadata including strategy name and deviation mode.

Mathematical Formulation

For k = 1, \ldots, K, let

y_k = a_k^\top x,

where:

• a_k is the coefficient vector defined by the objective term;

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

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

The minimax objective minimizes the maximum deviation across all objectives by introducing auxiliary deviation variables and solving a linear program that controls the worst-case mismatch.

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(
  x = test_mstATA,
  attribute = "iif(theta=-1)",
  applied_level = "Module-level",
  which_module = 1,
  sense = "min",
  goal = 12
)

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

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

# One-deviation minimax
minimax_obj(x = test_mstATA,
           multiple_terms = list(obj1,obj2,obj3),
           strategy_args = list(mode = "one_dev"))

# Two-deviation minimax
minimax_obj(x = test_mstATA,
            multiple_terms = list(obj1,obj2,obj3),
            strategy_args = list(mode = "two_dev"))

Example Mixed-Format Item Pool for MST

Description

A simulated item pool containing both standalone items and stimulus-based items. This dataset is designed to demonstrate multistage testing (MST) functionality under a mixed-format item pool, including stimulus-based selection, multiple-objective formulations, and multiple-panel assembly.

Usage

data(mixed_format_pool)

Format

A data frame with 1000 rows and the following variables:

item_id

Unique identifier for each item.

enemyitem

Identifier(s) of items that cannot be administered together (enemy-item information).

content

Content area classification (e.g., content 1, content 2, content 3, content 4).

dok

Depth-of-Knowledge (DOK) level (dok 1, dok 2, or dok 3).

itemtype

Item type (e.g., MC for multiple choice, TEI for technology-enhanced item).

time

Estimated item response time.

discrimination

Discrimination parameter (a) for the 2PL model.

difficulty

Difficulty parameter (b) for the 2PL model.

model

Item response theory (IRT) model for all items (2PL).

stim

Identifier of the associated stimulus (if applicable).

pivot

Indicator for pivot items. A pivot item is selected if and only if its associated stimulus is selected; non-pivot items are NA.

stimtype

Stimulus type (e.g., graphic-based, text-based).

stimcomplexity

complexity score of the associated stimulus.

Examples

data(mixed_format_pool)

Module Score Distribution at One or More Ability Values

Description

Compute the conditional score distributions in a module given one or more ability values (\theta).

This function assumes that item category probabilities have already been computed and are provided on a common category scale.

Usage

module_score_dist(icc)

Arguments

Details

Consider a module consisting of I items. Let the score for item i be a discrete random variable Y_i taking values \{0,1,\dots,m_i\}. Conditional on ability \theta, assume local independence:

\Pr(Y_1,\dots,Y_I \mid \theta) = \prod_{i=1}^{I} \Pr(Y_i \mid \theta).

The total module score is

S = \sum_{i=1}^{I} Y_i,

with support \{0,\dots,\sum_i m_i\}. For a fixed ability level \theta, the conditional distribution of S is obtained by discrete convolution of the item-level category probability vectors:

\Pr(S = s \mid \theta) = (p_{1} * p_{2} * \cdots * p_{I})(s),

where p_i = (p_{i0}(\theta),\dots,p_{im_i}(\theta)) and * denotes convolution.

This function applies the above operation independently at each ability level.

Value

A numeric matrix giving conditional module score distributions at target theta values. Rows correspond to total scores s = 0,\dots,\sum_i m_i. Columns correspond to ability values \theta. Each column sums to one.

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)

module_score_dist(icc_mat[[1]])
module_score_dist(icc_list)

## 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")
module_score_dist(icc_mat[[1]])
module_score_dist(icc_list)

## Example 3: multiple IRT models (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 = 0,model_col = "model")
module_score_dist(icc_mat[[1]])
module_score_dist(icc_list)

Create an mstATA_design Object

Description

Constructs an mstATA_design object from an item pool and a multistage test (MST) design. The resulting object encodes the full structural information required for automated test assembly, including module structure, pathway structure, decision variables, and optional preprocessing artifacts such as stimulus mappings and enemy relationships.

Usage

mst_design(
  itempool,
  item_id_col = "item_id",
  design,
  rdps = NULL,
  diff_levels = NULL,
  exclude_pathways = NULL,
  module_length = NULL,
  pathway_length = NULL,
  item_module_eligibility = NULL,
  pivot_stim_map = NULL,
  enemyitem_set = NULL,
  enemystim_set = NULL
)

Arguments

Details

1. Routing decision points

The list must have length NumStages - 1. Each element corresponds to routing after a given stage and must be a numeric vector whose length equals the number of modules in the next stage minus one.

For example, in a three-stage 1-3-3 design:

rdps = list(
  c(-0.5, 0.5),  # routing after stage 1
  c(-1, 1)       # routing after stage 2
)

The ordering of values within each vector defines adjacency among modules in the next stage.

2. module_length or pathway_length

Exactly one of module_length or pathway_length must be specified.

• If module_length is provided, modules at the same stage are checked (must have equal length). Pathway lengths are computed automatically.

• If pathway_length is provided, all pathways are assumed to have equal length and module lengths are not explicitly stored.

• If both are provided, consistency between the implied and supplied pathway lengths is checked.

3. item_module_eligibility set

By default, all items are eligible for all modules, yielding a fully flexible module-explicit formulation with decision variables x_{i,m} indicating whether item i is selected in module m in a panel. Panel-level item exposure constraints ensure uniqueness across modules within a pathway/panel.

When item_module_eligibility is supplied, decision variables are created only for eligible item-module combinations. This reduces model size while preserving flexibility near module boundaries and avoids rigid item partitioning in original hybrid assembly strategy (Xiong, 2018).

Value

An object of class "mstATA_design" with the following components:

ItemPool

The original item pool.

item_id_col

A character string giving the column name in ItemPool that uniquely identifies items.

pivot_stim_map

Optional verified stimulus mapping object with components pivot_item_id, stimulus_name, stimulus_members, and numItems_stimulus.

enemyitem_set

Optional verified enemy item set containing ExclusionPair, EnemySet, and derived ItemIndex.

enemystim_set

Optional verified enemy stimulus set containing ExclusionPair, EnemySet, and derived PivotIndex.

NumStages

Number of stages in the MST design.

NumModules

Number of modules in the MST design.

NumPathways

Number of allowed pathways.

RDP

Optional verified routing decision points.

ModuleIndex

A data.frame describing module structure by stage. If module_length is supplied, includes a ModuleLength column.

PathwayIndex

A data.frame describing allowed pathways and their total lengths. If difficulty labels are available, includes pathway labels.

decisionvar_name

Character vector of decision variable names (one panel).

decisionvar_type

Character vector of decision variable types (currently all binary).

References

Xiong, X. (2018). A hybrid strategy to construct multistage adaptive tests. Applied Psychological Measurement, 42(8), 630-643.doi:10.1177/0146621618762739

See Also

create_pivot_stimulus_map(),

create_enemy_sets(),

concat_enemy_sets()

Examples

# mini item pool
data("mini_itempool")
# Example 1: 1-3-3 design with varying module lengths
mst_design(itempool = mini_itempool,design = "1-3-3",
               module_length = c(6, 4, 4, 4, 3, 3, 3),pathway_length = NULL)

# Example 2: 1-3-3 design with fixed pathway length and excluded REH and RHE pathways
mst_design(itempool = mini_itempool,design = "1-3-3",
               exclude_pathways = c("1-1-3", "1-3-1"),
               module_length = NULL,pathway_length = 13)
# Example 3: 1-3-3 design, with item_module_eligibility provided
item_module_eligibility<-list(`1`=1:nrow(mini_itempool),
                              `2`=which(mini_itempool$difficulty<=0),
                              `4`=which(mini_itempool$difficulty>=0))
### selected items in routing module no item-level requirement,
### selected items in S2E, difficulty below 0
### selected items in S2H, difficulty above 0

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)

Construct MST Structural Constraints for an MST Panel

Description

Translates the structural specifications of a MST panel into a set of mandatory linear constraints that must be satisfied regardless of the assembly strategy (e.g., bottom-up, top-down, or hybrid).

The resulting constraints enforce:

• Module-level item count requirements or Pathway-level item count + module min/max + equal module length within each stage requirements

• Information balance at routing decision points (RDPs), if specified.

These constraints are intrinsic to the MST panel configuration and are independent of the assembly strategy.

Usage

mst_structure_con(x, stage_length_bound = NULL, info_tol = 0.5)

Arguments

Details

This function bundles structural constraints that are required for all MST panel assembly problems.

When routing constraints are requested, the item pool must already contain item-level information functions of the form iif(theta = theta_point). These can be prepared using compute_iif().

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

See Also

mst_design(),

test_itemcount_con(),

test_rdp_con(),

compute_iif()

Examples

data("mini_itempool")
iif_matrix<-compute_iif(mini_itempool,
                        item_par_cols = list("3PL"=c("discrimination","difficulty","guessing")),
                        theta = c(-0.5,0.5),model_col = "model")
mini_itempool[,paste0("iif(theta=",c(-0.5,0.5),")")]<-iif_matrix
test_mstATA <- mst_design(
  itempool = mini_itempool,module_length = c(3,4,4,4),
  design = "1-3",rdps = list(c(-0.5,0.5))
)
## build mandatory structural constraints: module-level item count and rdp constraint
mst_structure_con(x = test_mstATA,info_tol = 0.4)

Define a Multi-Panel mstATA Model

Description

Constructs a multi-panel ATA model by expanding single-panel specifications to multiple panels and turning it into a solver-ready formulation.

Solution-level constraints and decision-variable linking between item-module-panel variables and solution-level variables are handled at this stage.

Usage

multipanel_spec(
  x,
  panel_model,
  num_panels,
  solution_con = NULL,
  global_min_use = 0,
  global_max_use = Inf,
  item_min_use = NULL,
  item_max_use = NULL
)

Arguments

Details

1. Parallel Panels

The single-panel specification is expanded to num_panels panels by replicating constraint matrices in a block-diagonal structure. All panels share identical constraints and objectives.

Solution-level constraints, if provided, are appended after panel expansion.

Specification traceability

The returned model contains an expanded specification table that records, for each requirement:

• the originating panel,

• the number of constraints generated,

• the contiguous row ranges in the final solver matrix.

This information can be used to diagnose infeasibility and to prioritize or relax groups of constraints programmatically.

2. Consistency between item-module-panel selection and solution-level item indicators

The decision-variable linking constraints (e.g., dvlink_item_solution()) are automatically added to link item-module-panel selection and solution-level item selection.

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".

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 class "mstATA_model", represented as a named list containing constraint matrices, objective coefficients, decision variable metadata, bounds, and optimization sense.

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 constraint matrix (class "Matrix") for binary decision variables. Rows correspond to constraints; columns correspond to binary decision variables.

A_real

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

A

Constraint coefficient matrix (sparse or dense).

C_binary

A numeric vector of objective coefficients for binary decision variables.

C_real

A numeric vector of objective coefficients for continuous decision variables.

obj

Objective function coefficient vector.

d

Right-hand-side vector of constraints.

operators

Constraint operators (e.g., "<=", ">=", "=").

vtype

Decision variable types ("B" for binary, "C" for continuous).

varname

Decision variable names.

lb

Lower bounds for decision variables.

ub

Upper bounds for decision variables.

sense

Optimization sense ("min" or "max").

See Also

onepanel_spec(),

dvlink_item_solution()

Create a Single Linear Objective Term

Description

Creates a linear objective term of the form a^\top x, where the vector a represents categorical or quantitative attribute values for the involved items (or stimuli), and the decision variables x represent item selections within a single MST panel.

Depending on the attribute supplied, the objective can target:

• maximize or minimize the number of items belong to a specific category level, or

• maximize or minimize the sum of quantitative attribute values across items (e.g., difficulty, IIF values, discrimination).

Objective terms may be applied at three hierarchical levels:

• "Module-level" – aggregates only items belonging to one specific module;

• "Pathway-level" – aggregates items in all modules that compose a single MST pathway; and

• "Panel-level" – aggregates all item selections across all modules in a panel.

The function supports two types of objectives:

• Relative objective - maximize or minimize a^\top x.

• Absolute deviation objective - minimize |a^\top x - g| where g is the target value.

Usage

objective_term(
  x,
  attribute,
  cat_level = NULL,
  applied_level = c("Module-level", "Pathway-level", "Panel-level"),
  which_module = NULL,
  which_pathway = NULL,
  sense = "max",
  goal = NULL
)

Arguments

Details

1. Application scope

• Module-level: which_module must be supplied and must be a scalar. which_pathway must be NULL.

• Pathway-level: which_pathway must be supplied and must be a scalar. which_module must be NULL.

• Panel-level: Neither which_module nor which_pathway may be supplied.

2. Objective meaning

If cat_level = NULL, the vector a consists of quantitative attribute values. If cat_level is specified, a is an indicator vector for items in the corresponding category.

The objective term therefore represents:

• the sum of attribute values (quantitative), or

• the count of items in a category (categorical).

Value

An object of class "mstATA_objective" with components:

name

Character description of the objective term.

coef_val

A 1-row sparse matrix containing the objective coefficients.

goal

The target value for absolute deviation objectives, or NULL.

sense

The optimization direction ("max" or "min").

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
)

# Example 1: Maximize information at ability = 0 in the routing module
objective_term(
  x = test_mstATA,
  attribute = "iif(theta=0)",
  cat_level = NULL,
  applied_level = "Module-level",
  which_module = 1,
  sense = "max"
)

# Example 2: Target a test information value at ability = -1 for pathway 1
objective_term(
  x = test_mstATA,
  attribute = "iif(theta=-1)",
  cat_level = NULL,
  applied_level = "Pathway-level",
  which_pathway = 1,
  sense = "max",
  goal = 10
)

# Example 3: Maximize the number of MC items in a panel
objective_term(
  x = test_mstATA,
  attribute = "itemtype",
  cat_level = "MC",
  applied_level = "Panel-level",
  sense = "max"
)

Define a Single-Panel mstATA Model

Description

Constructs a single-panel ATA specification by assembling constraints, optional objective formulations, and required decision-variable linking rules into a solver-ready model with full semantic traceability.

This function validates that all supplied constraints apply to a single panel, automatically injects decision-variable linking constraints when required, and records row-index ranges that map semantic requirements to solver constraint rows.

Usage

onepanel_spec(x, constraints, objective = NULL)

Arguments

Details

1. Constraint scope

All constraints supplied to onepanel_spec() must apply to a single panel. This includes requirements defined at the item, stimulus, itemset, module, pathway, or panel level.

Constraints that operate across panels (solution-level reuse or exposure constraints) must be specified during multi-panel expansion and are not permitted in a single-panel specification.

2. Automatic decision-variable linking

If module-level logical constraints involving item-stimulus relationships are detected, and stim_itemcount_con() is not included, onepanel_spec() automatically injects item-stimulus gating constraints via all-in/all-out selection. This ensures that item-level and stimulus-level selections remain logically consistent.

3. Row-index traceability

All constraint rows–including those introduced by objectives and automatically injected decision-variable linking constraints–are assigned contiguous row-index ranges in the compiled constraint matrix.

These ranges are recorded in the returned specification table, allowing users to:

• diagnose infeasibility,

• identify binding constraint groups, and

• programmatically relax or prioritize subsets of constraints.

Value

An object of class "mstATA_model", represented as a named list containing constraint matrices, objective coefficients, decision variable metadata, bounds, and optimization sense.

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 constraint matrix (class "Matrix") for binary decision variables. Rows correspond to constraints; columns correspond to binary decision variables.

A_real

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

A

Constraint coefficient matrix (sparse or dense).

C_binary

A numeric vector of objective coefficients for binary decision variables.

C_real

A numeric vector of objective coefficients for continuous decision variables.

obj

Objective function coefficient vector.

d

Right-hand-side vector of constraints.

operators

Constraint operators (e.g., "<=", ">=", "=").

vtype

Decision variable types ("B" for binary, "C" for continuous).

varname

Decision variable names.

lb

Lower bounds for decision variables.

ub

Upper bounds for decision variables.

sense

Optimization sense ("min" or "max").

Examples

data("reading_itempool")

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

test_mstATA <- mst_design(
  itempool = reading_itempool,
  design   = "1-3-3",
  module_length = c(14,12,12,12,12,12,12),
  pivot_stim_map = pivot_stim_map
)
spec1<-test_itemcount_con(x=test_mstATA)
spec2<-test_stimcat_con(
  x = test_mstATA,
  attribute = "stimulus_type",
  cat_levels = c("history","social studies"),
  operator = "=",
  target_num = c(1,1),
  which_module = 1)
spec3<-test_stimcat_con(
  x = test_mstATA,
  attribute = "stimulus_type",
  cat_levels = "history",
  operator = "=",
  target_num = 2,
  which_module = 2:4)
spec4<-test_stimcat_con(
  x = test_mstATA,
  attribute = "stimulus_type",
  cat_levels = "social studies",
  operator = "=",
  target_num = 2,
  which_module = 5:7)
spec5<-stim_itemcount_con(
  x = test_mstATA,
  min = 5,
  max = 7
)
obj_term<-objective_term(x = test_mstATA,attribute = "discrimination",
                         applied_level = "Module-level",which_module = 1,sense = "max")

panel_spec <- onepanel_spec(
  x = test_mstATA,
  constraints = list(spec1,spec2,spec3,spec4,spec5),
  objective = single_obj(x=test_mstATA,single_term = obj_term)
)

Generate Panel-Level Constraints for the Min/Exact/Max Number of Items from Specific Categorical Levels

Description

This function generates a linear constraint matrix that restricts the number of items belonging to specified categorical levels (e.g., content area, format type) across all modules/pathways in an MST panel.

The constraint may enforce:

• a minimum number of items in category c,

• a maximum number of items in category c, or

• an exact (equality) requirement for category c.

The total number of constraints equals the number of category levels supplied in cat_levels.

Usage

panel_itemcat_con(x, attribute, cat_levels, operator, target_num)

Arguments

Details

1. Specification

The constraint enforces:

A minimum, exact, or maximum number of items from specified categorical levels must be selected within a panel.

Key characteristics:

• The attribute type is categorical.

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

• The constraints are applied at the Panel-level.

Users may restrict the constraints to any subset of categories via the cat_levels argument.

Value

An object of S3 class "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.

C_binary

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_c^{item} denote the set of items that belong to category c.

\sum_{m} \sum_{s = 1}^{S} \sum_{i_s \in V_c^{item}} x_{i_s,m} \substack{\le \\ \ge \\ =} n_{c}^{item} , s = 1, \ldots, S, i_s = 1, \ldots, I_s.

Here:

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

• The stacked operator, \substack{\leq \\ \geq \\ =} denotes that the specification may take the form of an upper bound, lower bound, or exact value.

• n_c^{item} specify the required number of items from category level c in a panel.

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: Require at least 10 multiple-choice items in the panel
panel_itemcat_con(
  x         = test_mstATA,
  attribute = "itemtype",
  cat_levels    = "MC",
  operator  = ">=",
  target_num = 10
)

# Example 2: Require at least 10 multiple-choice items, at least 3 TEI items in the panel
panel_itemcat_con(
  x         = test_mstATA,
  attribute = "itemtype",
  cat_levels    = c("MC","TEI"),
  operator  = ">=",
  target_num = c(10,5)
)

Generate Panel-Level Constraints for Item Reuse Across Modules/Pathways

Description

This function constructs panel-level constraints that limit how many times an item may be selected across the modules and pathways contained within a single MST panel.

Two reuse-control modes are supported via overlap:

• overlap = FALSE – No item reuse anywhere in the panel (the item may appear in at most one module across the entire panel).

• overlap = TRUE – Item reuse is permitted across adaptive modules within the same stage, but items must remain unique within each individual pathway.

If item_module_eligibility = NULL in mst_design(), the total number of constraints depends on overlap:

• overlap = FALSE:

  The number of constraints = number of items in the item pool.

• overlap = TRUE:

  The number of constraints = (number of items) x (number of pathways).

Usage

panel_itemreuse_con(x, overlap = FALSE)

Arguments

Details

1. Specification

The constraint enforces:

An item can be selected at most once within a pathway/panel.

Key characteristics:

• The attribute type is logical (if..., then...) with item identifier: each item has an unique ID.

• The attribute is defined at the itemset level (item-itself set) in the item pool.

• The constraint is enforced at the Panel-level, i.e., across all modules and pathways in a panel.

2. Interpretation of overlap

(a) overlap = FALSE – Strict item uniqueness within the entire panel

Under this condition:

• An item may appear in at most one module anywhere in the panel.

• Selecting the item in any module automatically prevents its selection in all other modules of the panel.

• The overlap among pathways are only due to the MST structure.

(b) overlap = TRUE – Item reuse allowed within stage, but not within pathway

Under this condition:

• Items may be reused across adaptive modules in the same stage.

• Items must not be reused within the same pathway (i.e., an item may appear at most once per pathway).

• The overlap among pathways not only due to the MST structure, but also due to some common items across modules in the same stage.

Example interpretation for a 1-3-3 design:

• (1) If an item is selected in the routing module implies it cannot appear in any S2 or S3 module.

• (2) If selected in an S2 module implies it may appear in other S2 modules (same stage), but not in S1R or any S3 module.

• (3) If selected in an S3 module implies it may appear in other S3 modules, but not in S1R or any S2 module.

3. Why This Is a Panel-Level Constraint

Although the constraint logic differs for the two overlap conditions, both versions govern item allocation across the set of modules that comprise a full panel. In other words, the constraint concerns how an item may or may not appear within the assembled panel as a whole, rather than applying to a specific module or pathway in isolation. For this reason, both cases are formally categorized as Panel-level item-reuse constraints.

Value

An object of S3 class "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.

Case 1: overlap = TRUE Item must be unique within each pathway:

\sum_{m \in r} x_{i_s,m} \le 1

Case 2: overlap = FALSE Item must be unique across the entire panel:

\sum_{m} 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.

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: No item overlap within a panel
panel_itemreuse_con(x = test_mstATA, overlap = FALSE)

# Example 2: Allow item reuse within the same stage
panel_itemreuse_con(x = test_mstATA, overlap = TRUE)


# Example 3: item_module_eligibility supplied -- disjoint module eligibility
# No need for panel_itemreuse_con() in this case
item_module_eligibility <- list(
  `1` = intersect(which(mini_itempool$difficulty >= -1),
                  which(mini_itempool$difficulty < 0)),
  `2` = intersect(which(mini_itempool$difficulty >= -2),
                  which(mini_itempool$difficulty < -1)),
  `3` = intersect(which(mini_itempool$difficulty >= 0),
                  which(mini_itempool$difficulty < 1)),
  `4` = intersect(which(mini_itempool$difficulty >= 1),
                  which(mini_itempool$difficulty < 2))
)

new_test_mstATA <- mst_design(
  itempool               = mini_itempool,
  design                 = "1-3",
  module_length          = c(6,7,7,7),
  item_module_eligibility = item_module_eligibility
)

## The generated constraint matrix are redundant and will be omitted in the ATA model.
try(panel_itemreuse_con(x = new_test_mstATA, overlap = FALSE))


# Example 4: Overlapping module eligibility -- reuse constraints required
item_module_eligibility <- list(
  `1` = which(mini_itempool$difficulty < 2),
  `2` = which(mini_itempool$difficulty < 0),
  `3` = intersect(which(mini_itempool$difficulty >= -1),
                  which(mini_itempool$difficulty < 1)),
  `4` = intersect(which(mini_itempool$difficulty >= 0),
                  which(mini_itempool$difficulty < 2))
)

new_test_mstATA <- mst_design(
  itempool               = mini_itempool,
  design                 = "1-3",
  module_length          = c(6,7,7,7),
  item_module_eligibility = item_module_eligibility
)

# Items eligible for multiple modules require reuse control
panel_itemreuse_con(x = new_test_mstATA, overlap = FALSE)

# Overlap within stage implies item may appear in more modules
panel_itemreuse_con(x = new_test_mstATA, overlap = TRUE)

Generate Panel-Level Constraints for the Min/Exact/Max Number of Stimuli from Specific Categorical Levels

Description

This function generates a linear constraint matrix based on a stimulus-level categorical attribute (e.g., stimulus type, passage theme) across all modules and pathways within a single panel.

The constraint may enforce:

• a minimum number of stimuli in category c,

• a maximum number of stimuli in category c, or

• an exact (equality) requirement in category c.

The number of linear constraints generated equals the number of category levels supplied in levels.

Usage

panel_stimcat_con(x, attribute, cat_levels, operator, target_num)

Arguments

Details

1. Specification

The constraint enforces:

A minimum, exact, or maximum number of stimuli from specified categories must be selected somewhere within a panel.

Key characteristics:

• The attribute type is categorical.

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

• The constraints are applied at the Panel-level.

Users may restrict the constraint to specific categories using the cat_levels argument.

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_c^{stim} denote the set of stimuli that belong to category c.

\sum_{m} \sum_{s \in V_c^{stim}} x_{i_s^{*},m} \substack{\le \\ \ge \\ =} n_{c}^{stim}

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.

• The stacked operator, \substack{\leq \\ \geq \\ =} denotes that the specification may take the form of an upper bound, lower bound, or exact value.

• n_c^{stim} specify the required number of stimuli from category level c across modules/pathways in a panel.

Examples

data("reading_itempool")

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

# Example: Require at most 4 history passages in an assembled panel
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
)

panel_stimcat_con(
  x             = test_mstATA,
  attribute     = "stimulus_type",
  cat_levels        = "history",
  operator      = "<=",
  target_num    = 4
)

Plot Test Category Probability Curves

Description

Plots category probability curves aggregated at the module or pathway level.

The function supports both single-panel and multi-panel visualization and automatically adjusts color and faceting to facilitate meaningful comparisons across modules, pathways, and panels.

Usage

plot_panel_tcc(
  assembled_panel,
  item_par_cols,
  model_col,
  D = 1,
  theta = seq(-5, 5, 0.1),
  unit = "module",
  mode = "within_panel",
  legend = TRUE
)

Arguments

Details

For a single panel, category probability curves are colored by module or pathway.

For multiple panels, two visualization modes are supported:

• "within_panel": curves are colored by module or pathway and faceted by panel.

• "across_panel": curves are colored by panel and faceted by module or pathway.

For dichotomously-scored items (two response categories), only the probability curve for the correct-response category (cat1) is displayed.

For polytomously-scored items (more than two response categories), probability curves for all response categories are displayed.

Category probability curves represent the average probability of each response category across items within the selected module or pathway at each ability value.

Value

A ggplot object.

Plot Test Information Functions

Description

Plots test information functions (TIFs) aggregated at the module or pathway level.

The function supports both single-panel and multi-panel visualization and automatically adjusts color and faceting to facilitate meaningful comparisons across modules, pathways, and panels.

Usage

plot_panel_tif(
  assembled_panel,
  item_par_cols,
  model_col,
  D = 1,
  theta = seq(-5, 5, 0.1),
  unit = "module",
  mode = "within_panel",
  legend = TRUE
)

Arguments

Details

For a single panel, information curves are colored by module or pathway.

For multiple panels, two visualization modes are supported:

• "within_panel": curves are colored by module or pathway and faceted by panel.

• "across_panel": curves are colored by panel and faceted by module or pathway.

Value

A ggplot object.

Plot Test Information Functions

Description

Plots testing information functions (TIFs).

Usage

plot_tif(items, item_par_cols, theta = seq(-3, 3, 0.1), model_col, D = 1)

Arguments

Value

A ggplot object.

Example Polytomous Item Pool for MST

Description

A simulated item pool consisting exclusively of polytomously scored items, designed to demonstrate multistage testing (MST) functionality under a partial credit modeling framework.

Usage

data(poly_itempool)

Format

A data frame with 50 rows and the following columns:

item_id

Unique identifier for each item.

content

Content area classification (e.g., content1, content2, content3, content4).

deltaj1

First step (threshold) parameter in the Partial Credit Model (PCM).

deltaj2

Second step (threshold) parameter in the Partial Credit Model (PCM).

deltaj3

Third step (threshold) parameter in the Partial Credit Model (PCM).

model

Item response theory (IRT) model used for all items (PCM).

nrCat

Integer specifying the maximum number of response categories generated for the item.

Examples

data(poly_itempool)

Print mstATA Model

Description

Prints a concise, human-readable summary of a compiled mstATA_model object which is produced by onepanel_spec() or multipanel_spec().

This print method is a diagnostic and inspection utility. It reports:

• the number of binary and continuous decision variables,

• the total number of linear constraints,

• the objective sense ("min" or "max"),

• and a formatted specification table mapping semantic requirements to solver constraint rows.

The specification table provides row-range traceability for debugging infeasibility and constraint prioritization.

Usage

## S3 method for class 'mstATA_model'
print(x, ...)

Arguments

Value

The input object x, returned invisibly.

See Also

onepanel_spec(),

multipanel_spec()

Print a formatted specification table for a panel specification

Description

This function is a low-level formatting utility intended for inspecting specification tables extracted from "mstATA_panel_spec" objects.

It reorders columns, optionally adds a human-readable row-range column (e.g., "rows 15-28"), and prints the result for interactive inspection. The function is strictly non-mutating: it does not modify global options, solver models, or the underlying panel specification object.

Usage

print_specification(spec)

Details

The printed specification table provides a semantic summary of how high-level requirements (constraints, objectives, and automatically injected decision-variable linking rules) map onto contiguous row ranges in the compiled constraint matrix.

This view is particularly useful for:

• diagnosing infeasibility by identifying conflicting constraint blocks;

• understanding which rows correspond to auto-injected constraints (e.g., decision-variable linking);

• prioritizing or relaxing groups of constraints programmatically; and

• debugging solver output with respect to original test specifications.

Reading Item Pool

Description

A reading item pool for demonstrating MST functionality.

Usage

data(reading_itempool)

Format

A data frame with 500 rows and 15 columns:

item_id

Unique identifier for each item.

content

Content area classification (e.g., content1, content2, content3, content4).

itemtype

Item format (e.g., MC, TEI).

time

Expected response time for the item.

discrimination

Discrimination parameter (a) for the 3PL model.

difficulty

Difficulty parameter (b) for the 3PL model.

guessing

Guessing parameter (c) for the 3PL model.

model

Item response theory (IRT) model used for the item (3PL).

nrCat

Integer specifying the maximum number of response categories generated for the item.

enemy_item

enemy item pairs/sets information

stimulus

associated stimulus information

pivot_item

the indicator of pivot items. A pivot item is defined as an item that is always selected for the test if and only if its stimulus is selected

enemy_stimulus

enemy stimulus pairs/sets information

stimulus_type

Stimulus types: history, social studies

stimulus_words

Stimulus words

Examples

data(reading_itempool)

Precomputed Stimulus-Based Assessment (MST Assembly Example)

Description

A precomputed MST panel assembled with the HiGHS solver demonstrated in Stimulus Based Assessment vignettes.

Usage

reading_panel

Format

An object of class mstATA_panel.

Source

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

Summarize Categorical Item Attributes in Assembled MST Panels

Description

Summarizes the number of selected items belonging to specified categorical attribute levels (e.g., content area, item type) within assembled MST panels. Summaries can be produced at the module level or pathway level, depending on the constraint scope.

Usage

report_test_itemcat(
  assembled_panel,
  attribute,
  cat_levels,
  which_module = NULL,
  which_pathway = NULL
)

Arguments

Details

This function operates on the output of assembled_panel() and is primarily intended for evaluating categorical test constraints.

The scope of the summary is determined by which_module and which_pathway:

• If which_module is provided, a module-level summary is returned for the specified modules.

• If which_pathway is provided, a pathway-level summary is returned for the specified pathways.

• If both which_module and which_pathway are NULL, the function defaults to a module-level summary over all modules.

The attribute specified by attribute must be a categorical attribute. This is verified internally using check_attribute_column(), and an error is thrown if the attribute is not categorical.

Counts are reported separately for each requested attribute level. For example, if cat_levels = c("MC", "TEI"), the output will contain separate rows for MC and TEI items within each module or pathway.

Value

A data frame with one row per panel-module (or panel-pathway) combination. The returned data frame contains:

panel_id

Panel identifier.

module_id or pathway_id

Module or pathway identifier.

cat_level_1, cat_level_2, ...

Number of selected items belonging to each specified categorical level within the corresponding module or pathway. Each category level appears as a separate column.

See Also

assembled_panel()

Summarize Quantitative Item Attributes in Assembled MST Panels

Description

Summarizes quantitative item attributes (e.g., test information, time, difficulty) within assembled multistage test (MST) panels. The summary can be computed as either the sum or the average of the attribute values, at the module level or pathway level, depending on the constraint scope.

Usage

report_test_itemquant(
  assembled_panel,
  attribute,
  statistic = c("average", "sum"),
  which_module = NULL,
  which_pathway = NULL
)

Arguments

Details

This function operates on the output of assembled_panel() and is primarily intended for evaluating quantitative test constraints.

The scope of the summary is determined by which_module and which_pathway:

• If which_module is provided, a module-level summary is returned for the specified modules.

• If which_pathway is provided, a pathway-level summary is returned for the specified pathways.

• If both which_module and which_pathway are NULL, the function defaults to a module-level summary over all modules.

The attribute specified by attribute must be a quantitative attribute. This is verified internally using check_attribute_column(), and an error is thrown if the attribute is not quantitative.

Value

A data frame with one row per panel-module (or panel-pathway) combination. The returned data frame contains:

panel_id

Panel identifier.

module_id or pathway_id

Module or pathway identifier.

attribute

The name of the quantitative attribute being summarized.

sum or average

The computed summary statistic (sum or average) of the specified quantitative attribute within the corresponding module or pathway.

See Also

assembled_panel()

Report Test Characteristic Curves (TCC)

Description

Computes and reports TCC curves aggregated at the module or pathway level for assembled MST panels.

Item-level category probabilities are obtained from compute_icc().

Usage

report_test_tcc(
  assembled_panel,
  theta,
  item_par_cols,
  model_col,
  D = 1,
  which_module = NULL,
  which_pathway = NULL
)

Arguments

Value

A data frame containing the following columns:

panel_id

Identifier of the assembled panel.

module_id / pathway_id

Identifier of the module or pathway.

theta

Ability level at which the statistics are evaluated.

TCC

Test characteristic curve value, defined as the expected total score \sum E[P(Y = k \mid \theta)].

max_score

Maximum possible score for the module or pathway.

TCC_norm

Normalized TCC value defined as TCC / max_score.

See Also

compute_icc()

Report Test Information Functions (TIF)

Description

Computes and reports test information functions aggregated at the module or pathway level for assembled MST panels.

Item information functions are computed using compute_iif(), and then summed across items within specified module or pathway.

Usage

report_test_tif(
  assembled_panel,
  theta,
  item_par_cols,
  model_col,
  D = 1,
  which_module = NULL,
  which_pathway = NULL
)

Arguments

Value

A data frame with one row per panel-module (or panel-pathway)-ability combination. The returned data frame contains:

panel_id

Panel identifier.

module_id or pathway_id

Module or pathway identifier.

theta

Ability value at which test information is evaluated.

information

Sum of item information functions for all selected items within the corresponding module or pathway, evaluated at the given ability value.

See Also

compute_iif()

Maximize or Minimize a Single Objective Term

Description

This function compiles a single-objective optimization problem for MST assembly. The optimization is to maximize or minimize a single linear score.

\max y

or

\min y

where y = a^\top x is the linear objective term created by objective_term().

Usage

single_obj(x, single_term)

Arguments

Details

1. Overview

There is only one objective term, representing a linear score of the form a^\top x, constructed by objective_term().

Key characteristics for the objective term:

(1) Categorical or Quantitative

• maximize or minimize the number of items belonging to a specific categorical level, or

• maximize or minimize the sum of quantitative item-level attribute values, such as difficulty, discrimination, or item information function values.

(2) Module-, Pathway- or Panel-level

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

• "Pathway-level" – items in all modules belonging to one pathway contribute; and

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

(3) Relative or Absolute Objective

• Relative objective: maximize/minimize a^\top x.

• Absolute deviation objective: minimize the deviation from a specified target: |a^\top x - g|, where g is the target value.

Examples include:

• Relative objective – "Maximize the number of items in category c selected in Module 1."

• Absolute objective – "Minimize the deviation between the test information at \theta = 0 and the target value 15."

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 constraint matrix (class "Matrix") for binary decision variables. Rows correspond to constraints; columns correspond to binary decision variables.

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

"min" or "max"

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

A list containing the strategy name, strategy arguments, and y_bounds.

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.

Let V_c^{item} denote the set of items that belong to category c and q_{i_s} be the quantitative attribute value of item i_s.

For absolute-deviation objectives, let T be the target value and d be a non-negative deviation variable.

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

1. Module-level Objective (Module m)

(1a) Categorical attribute – relative objective

Specification: maximize or minimize the number of items from category c in module m.

\max/\min \sum_{s=1}^S \sum_{i_s \in V_c^{item}} x_{i_s,m}.

(1b) Quantitative attribute – relative objective

Specification: maximize or minimize the sum of item-level quantitative attribute values in module m.

\max/\min \sum_{s=1}^S \sum_{i_s} q_{i_s} x_{i_s,m}.

(1c) Categorical attribute – absolute deviation objective

Specification: minimize deviation between the number of items from category c in module m and the target value T.

\min d

subject to

\sum_{s=1}^S \sum_{i_s \in V_c^{item}} x_{i_s,m} - T \le d

T - \sum_{s=1}^S \sum_{i_s \in V_c^{item}} x_{i_s,m} \le d

(1d) Quantitative attribute – absolute deviation objective

Specification: minimize deviation between the sum of item-level attribute values and the target value T.

\min d

subject to

\sum_{s=1}^S \sum_{i_s} q_{i_s} x_{i_s,m}- T \le d

T - \sum_{s=1}^S \sum_{i_s} q_{i_s} x_{i_s,m} \le d

2. Pathway-level Objective (Pathway r)

Let \mathcal{M} denote the set of modules belonging to pathway r.

(2a) Categorical attribute – relative objective

\max/\min \sum_{m \in \mathcal{M}(r)} \sum_{s=1}^S \sum_{i_s \in V_c^{item}} x_{i_s,m}

(2b) Quantitative attribute – relative objective

\max/\min \sum_{m \in \mathcal{M}(r)} \sum_{s=1}^S \sum_{i_s} q_{i_s} x_{i_s,m}

(2c) Categorical attribute – absolute deviation objective

\min d

subject to

\sum_{m \in \mathcal{M}(r)}\sum_{s=1}^S \sum_{i_s \in V_c^{item}} x_{i_s,m} - T \le d

T - \sum_{m \in \mathcal{M}(r)}\sum_{s=1}^S \sum_{i_s \in V_c^{item}} x_{i_s,m} \le d

(2d) Quantitative attribute – absolute deviation objective

\min d

subject to

\sum_{m \in \mathcal{M}(r)} \sum_{s=1}^S \sum_{i_s} q_{i_s} x_{i_s,m} - T \le d,

T -\sum_{m \in \mathcal{M}(r)} \sum_{s=1}^S \sum_{i_s} q_{i_s} x_{i_s,m} \le d,

3. Panel-level Objective

(3a) Categorical attribute – relative objective

\max/\min \sum_{m=1}^{M} \sum_{s=1}^S \sum_{i_s \in V_c^{item}} x_{i_s,m}.

(3b) Quantitative attribute – relative objective

\max/\min \sum_{m=1}^{M} \sum_{s=1}^S \sum_{i_s} q_{i_s} x_{i_s,m}.

(3c) Categorical attribute – absolute deviation objective

\min d

subject to

\sum_{m=1}^{M} \sum_{s=1}^S \sum_{i_s \in V_c^{item}} x_{i_s,m} - T \le d,

T - \sum_{m=1}^{M} \sum_{s=1}^S \sum_{i_s \in V_c^{item}} x_{i_s,m} \le d,

(3d) Quantitative attribute – absolute deviation objective

\min d

subject to

\sum_{m=1}^{M}\sum_{s=1}^S \sum_{i_s} q_{i_s} x_{i_s,m} - T \le d,

T - \sum_{m=1}^{M}\sum_{s=1}^S \sum_{i_s} q_{i_s} x_{i_s,m} \le d,

Let V_c^{stim} denote the set of stimuli that belong to category c and q_s be the quantitative attribute value of stimulus s.

The Module-/Pathway-/Panel level requirements can also be related with stimulus-level categorical/quantitative requirements.

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
)

# Example 1: relative objective for information at theta = 0 in the routing module
single_term <- objective_term(
  x             = test_mstATA,
  attribute     = "iif(theta=0)",
  cat_level         = NULL,
  applied_level = "Module-level",
  which_module  = 1,
  sense         = "max"
)
single_obj(x = test_mstATA, single_term = single_term)

# Example 2: absolute objective for information at theta = 0 in the routing module
single_term <- objective_term(
  x             = test_mstATA,
  attribute     = "iif(theta=0)",
  cat_level         = NULL,
  applied_level = "Module-level",
  which_module  = 1,
  sense         = "min",
  goal = 10
)
single_obj(x = test_mstATA, single_term = single_term)

Generate Solution-Level Constraints for the Min/Exact/Max Number of Unique Items from Specific Categorical Levels

Description

This function constructs solution-level constraints that regulate the number of unique items–across all panels–that belong to specified categorical levels.

This constraint may enforce:

• a minimum number of unique items in category c,

• a maximum number of unique items in category c, or

• an exact number of unique items in category c

across the entire multi-panel MST solution.

Constraints are evaluated at the Solution-level, meaning that an item is considered 'selected' if it appears in any module of any panel.

The total number of constraints equals the number of categories in cat_levels.

Usage

solution_itemcat_con(x, attribute, cat_levels, operator, target_num)

Arguments

Details

1. Specification

The constraint enforces:

A minimum, exact, or maximum number of unique items from specified categories must be selected across all assembled panels.

Key characteristics:

• The attribute is type is categorical.

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

• The constraint is applied at the Solution-level, i.e., across all panels.

Users may limit the constraint to a subset of categories using cat_levels.

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.

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

The solution-level variables track whether an item appears anywhere in the assembled multi-panel solution.

Let V_c^{item} denote the set of items that belong to category c.

\sum_{s = 1}^{S} \sum_{i_s \in V_c^{item}} s_{i_s} \substack{\le \\ \ge \\ =} n_c^{item} .

Here:

• s_{i_s} is the binary decision variable indicating whether item i_s is used at least once across all panels.

• \substack{\leq \\ \geq \\ =} denotes that the specification may take the form of an upper bound, lower bound, or exact value.

• n_c^{item} is the required number of unique item from category c across all panels.

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)
)

# Require at least 2 unique content1 items and at least 6 unique content3 items
solution_itemcat_con(
  x        = test_mstATA,
  attribute = "content",
  cat_levels    = c("content1", "content3"),
  operator  = ">=",
  target_num = c(2, 6)
)

Generate Solution-Level Constraints for the Number of Unique Items Selected Across Panels

Description

Constructs solution-level constraints on the total number of distinct items selected across all panels in a multistage test (MST) assembly.

This requirement enforces a user-specified:

• minimum number of unique items,

• maximum number of unique items, or

• exact (fixed) number of unique items

that may appear anywhere across all assembled panels.

These constraints operate at the solution level, using decision variables that indicate whether an item appears in any module of any panel.

The number of constraints generated is 1. If both a range needs to be specified, call this function twice.

Usage

solution_itemcount_con(x, operator, target_num)

Arguments

Details

1. Specification

This constraint enforces:

A minimum, exact, or maximum number of unique items must be selected across all panels in one solution.

Key characteristics:

• The attribute type is categorical: each item is assigned a unique ID.

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

• The constraint is applied at the Solution-level, i.e., across all panels.

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.

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

The solution-level variables track whether an item appears anywhere in the assembled multi-panel solution.

The total number of unique item selected at the solution level is controlled through:

\sum_{s=1}^{S} \sum_{i_s=1}^{I_s} s_{i_s} \substack{\le \\ \ge \\ =} n^{item} .

Here:

• s_{i_s} is the binary decision variable indicating whether item i_s is used at least once across all panels.

• \substack{\leq \\ \geq \\ =} denotes that the specification may take the form of an upper bound, lower bound, or exact value.

• n^{item} is the user-specified minimum, exact, or maximum number of unique items.

Examples

data("mini_itempool")

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

# Require at least 20 unique items across all panels
solution_itemcount_con(test_mstATA, operator = ">=",target_num = 20)

# Require at least 20 at most 30 unique items across all panels
con1<-solution_itemcount_con(test_mstATA, operator = ">=",target_num = 20)
con2<-solution_itemcount_con(test_mstATA, operator = "<=",target_num = 30)

Generate Solution-Level Constraints for the Min/Exact/Max Number of Unique Stimuli in Specified Categories

Description

This function constructs solution-level constraints that regulate the number of unique stimuli–across all panels–that belong to specified categorical levels.

The constraint may enforce:

• a minimum number of stimuli in category c,

• a maximum number of stimuli in category c, or

• an exact (equality) requirement in category c.

across the entire multi-panel MST solution.

Constraints are evaluated at the Solution-level, meaning that a stimulus is considered 'selected' if it appears in any module of any panel.

The total number of constraints equals the number of categories in cat_levels.

Usage

solution_stimcat_con(x, attribute, cat_levels, operator, target_num)

Arguments

Details

1. Specification

The constraint enforces:

A minimum, exact, or maximum number of unique stimuli belonging to specified categories must be selected across all panels in the multi-panel MST assembly.

Key characteristics:

• The attribute type is categorical.

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

• The constraint is applied at the Solution-level, i.e., across all panels.

Users may limit the constraint to a subset of categories using cat_levels.

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.

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

The solution-level variables track whether an item appears anywhere in the assembled multi-panel solution.

Let V_c^{stim} denote the set of stimuli that belong to category c.

\sum_{s \in V_c^{stim}} s_{i_s^{*}} \substack{\le \\ \ge \\ =} n_c^{stim} .

Here:

• s_{i_s^{*}} indicates whether the pivot item for stimulus s is selected in any panel, thereby indicating whether the stimulus s is selected in any panel.

• \substack{\leq \\ \geq \\ =} denotes that the specification may take the form of an upper bound, lower bound, or exact value.

• n_c^{stim} is the required number of unique stimuli from category c across all panels.

Examples

data("reading_itempool")

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

test_mstATA <- mst_design(
  itempool     = reading_itempool,
  design       = "1-3-3",
  module_length = c(14,12,12,12,12,12,12),
  pivot_stim_map = pivot_stim_map
)

# Require at least 3 history passages and 4 social studies passages
solution_stimcat_con(
  x             = test_mstATA,
  attribute     = "stimulus_type",
  cat_levels        = c("history", "social studies"),
  operator      = ">=",
  target_num    = c(3, 4)
)

Generate Solution-Level Constraints on the Number of Unique Stimuli Selected Across Panels

Description

This function constructs a solution-level constraint that controls the number of distinct stimuli appearing in the final multi-panel MST assembly.

The constraint may impose a:

• minimum number of unique stimuli,

• maximum number of unique stimuli, or

• fixed (exact) number of unique stimuli.

that may appear anywhere across all assembled panels.

The number of constraints generated is 1. If both a range needs to be specified, call this function twice.

Usage

solution_stimcount_con(x, operator, target_num)

Arguments

Details

1. Specification

This constraint enforces:

A minimum, exact, or maximum number of unique stimuli must be selected across all panels in the assembled MST solution.

Key characteristics:

• The attribute type is categorical: each stimulus is assigned a unique ID.

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

• The constraint is enforced at the Solution-level, i.e., across all panels.

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.

For each item i_s,

s_{i_s} if item i_s is used in any module in any panel. s_{i_s} otherwise.

The solution-level variables track whether an item appears anywhere in the assembled multi-panel solution.

The total number of unique stimuli selected at the solution level is controlled through:

\sum_{s=1}^{S-1} s_{i_s^{*}} \substack{\le \\ \ge \\ =} n^{stim} .

Here:

• s_{i_s^{*}} indicates whether the pivot item for stimulus s is selected in any panel, thereby indicating whether the stimulus s is selected in any panel.

• \substack{\leq \\ \geq \\ =} denotes that the specification may take the form of an upper bound, lower bound, or exact value.

Examples

data("reading_itempool")

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

test_mstATA <- mst_design(
  itempool = reading_itempool,
  design = "1-3-3",
  module_length = c(5,7,7,7,8,8,8),
  pivot_stim_map = pivot_stim_map
)

# Require between 5 and 10 unique stimuli across all assembled panels
con1<-solution_stimcount_con(test_mstATA,">=",5)
con2<-solution_stimcount_con(test_mstATA,"<=",10)

Solve an ATA Model Using a Mathematical Programming Solver

Description

Solves an automated test assembly (ATA) model in the mstATA framework. The input model specification is optionally presolved to remove redundant rows and columns, checked for feasibility, and then solved using the requested solver.

Usage

solve_model(
  model_spec,
  continuous_bound_source = "compiled",
  continuous_bounds = NULL,
  solver = c("gurobi", "lpsolve", "HiGHS", "Symphony", "GLPK"),
  time_limit = 99999,
  check_feasibility = FALSE,
  show_progress = FALSE
)

Arguments

Value

A list with the following components:

solution

A list containing the solver results with the following elements:

solution_found

A character string indicating the solver status (e.g., "OPTIMAL", "FEASIBLE", or "INFEASIBLE", or "UNBOUNDED" or "TIME_LIMIT" or "OTHER").

best_solution

A numeric vector of decision variable values corresponding to the best solution found.

objval

The objective function value associated with best_solution.

solution_list

Either NULL or a list of optimal solutions. If multiple optimal solutions exist, only the "gurobi" solver may return more than one solution.

check

Either NULL or a data frame summarizing constraint evaluation at the solution, including left-hand side values, constraint operators, right-hand side values, and residual values.

runtime

The total runtime of the solver in seconds.

iis

If solver = "gurobi" and model is infeasible, an irreducible inconsistent subsystem (IIS) will also be returned. It should be mentioned that an infeasible model may have multiple IISs. The one returned by Gurobi is not necessarily the smallest one; there may exist others with fewer constraints or bounds.

model

An object of class "mstATA_model" representing the MILP formulation used by the solver. This includes the constraint matrix A, right-hand side rhs, constraint senses, objective coefficients, bounds, variable types, variable names, model sense, and row names.

solver

A character string indicating the solver used (as requested by solver).

Solve An Infeasible mstATA Model Using Block-level Slack Variables

Description

Attempts to recover feasibility for an infeasible mstATA_model by relaxing selected non-core constraint blocks using slack variables with user-specified penalties. A single continuous slack variable is introduced for each relaxable constraint block, allowing controlled violations while preserving the core structure of the MST design.

This function is intended as a diagnostic and fallback tool rather than a replacement for strict feasibility checks.

Usage

solve_with_slack(
  model_spec,
  cat_penalty,
  quant_penalty,
  solver = c("gurobi", "lpsolve", "HiGHS", "Symphony", "GLPK"),
  time_limit = 99999
)

Arguments

Details

The relaxed model is constructed as follows:

• Hard constraints (never relaxed):

  • Objective-related constraints.

  • Essential MST structure constraints (e.g., module- and pathway-level item count constraints, optional requirements for routing decision points).

  • Logical constraints (e.g., enemy relationships, item-stimulus grouping relationships, item exposure control).

  • Equality constraints, identified by specification$Operator == "(exact)" at the block level.

• Soft constraints (relaxed with slack):

  • Categorical constraint blocks.

  • Quantitative constraint blocks.

For each relaxable constraint block, one nonnegative continuous slack variable is introduced and shared across all rows in that block. Slack coefficients are assigned according to the row operator:

• For "<=" rows, the slack enters with coefficient -1.

• For ">=" rows, the slack enters with coefficient +1.

Soft constraint blocks must contain only "<=" or ">=" rows.

The objective function is augmented by adding penalty terms for each slack variable. Categorical slack variables are penalized more heavily than quantitative slack variables to reflect their higher priority.

Value

A solver result object returned by solve_model(), containing the optimized solution, solver status, and objective value for the relaxed model. Slack variable values indicate the magnitude of constraint violations at the block level.

Mathematical Formulation

Consider an infeasible mstATA model consisting of a set of constraint blocks indexed by b = 1,\dots,B. Each block b corresponds to one row in the specification table and may contain multiple linear constraint rows indexed by r \in \mathcal{R}.

For each constraint row, let a_r^\top x denote the left-hand side linear expression and d_r the right-hand side constant.

Soft constraint blocks and slack variables. For each relaxable constraint block b (categorical or quantitative), a single nonnegative continuous slack variable s_b \ge 0 is introduced and shared across all rows in that block.

Original (hard) constraints. For a row r \in \mathcal{R}, the original linear constraint takes one of the following forms:

• Upper-bound constraint:

  a_r^\top x \le d_r

• Lower-bound constraint:

  a_r^\top x \ge d_r

Equality constraints (a_r^\top x = d_r) are not relaxable and therefore are excluded from slack construction.

Relaxed constraints with block-level slack. For a relaxable block b, each row r \in \mathcal{R} is modified as follows:

• If the original row is a_r^\top x \le d_r, the relaxed form is

  a_r^\top x \le d_r + s_b.

• If the original row is a_r^\top x \ge d_r, the relaxed form is

  a_r^\top x \ge d_r - s_b.

Equivalently, in matrix form, the slack variable s_b enters each row with coefficient -1 for "<=" constraints and +1 for ">=" constraints. A single slack variable therefore bounds the maximum violation across all rows in the block.

Categorical vs quantitative constraints. The mathematical relaxation is identical for categorical and quantitative constraint. They differ only in the penalty applied to their slack variables in the objective function. Categorical constraints are penalized more heavily to reflect higher priority.

Objective function with slack penalties. Let \mathcal{B}_{cat} and \mathcal{B}_{quant} denote the sets of categorical and quantitative soft constraint blocks, respectively. The relaxed optimization problem augments the original objective by adding slack penalties:

\min f(x) + \sum_{b \in \mathcal{B}_{cat}} \lambda_{cat}\, s_b + \sum_{b \in \mathcal{B}_{quant}} \lambda_{quant}\, s_b,

where f(x) denotes the original objective function, and \lambda_{cat} are user-specified penalty coefficients.

If the original problem is a maximization problem, the equivalent formulation is obtained by subtracting the slack penalties from the objective:

\max f(x) - \sum_{b \in \mathcal{B}_{cat}} \lambda_{cat}\, s_b - \sum_{b \in \mathcal{B}_{quant}} \lambda_{quant}\, s_b.

The resulting solution represents a best-compromise feasible design that minimizes violations of high-priority constraints before lower-priority ones.

See Also

solve_model()

Generate Itemset-Level Constraints for Minimum, Exact, or Maximum Numbers of Stimulus-Linked Items from Specific Categorical Levels

Description

This function constructs linear constraints ensuring that, for every selected stimulus, the items associated with that stimulus meet the required minimum, exact, or maximum counts from specified categorical levels (e.g., content area, skill type, item format).

The total number of generated linear constraints =

(number of stimuli) x (number of category levels) x (number of involved modules)

For a range constraint (i.e., both a minimum and a maximum number of items requirement), the function must be called twice:

• once with target_num = min and operator = ">=", and

• once with target_num = max and operator = "<=".

Usage

stim_itemcat_con(
  x,
  attribute,
  cat_levels,
  operator,
  target_num,
  which_module = NULL,
  which_pathway = NULL
)

Arguments