mirt

Multidimensional Item Response Theory for Python

A comprehensive Python implementation of Item Response Theory (IRT) models with a high-performance Rust backend, inspired by R's mirt package.

Features

Core IRT Models

• Dichotomous: 1PL (Rasch), 2PL, 3PL, 4PL
• Polytomous: GRM, GPCM, PCM, NRM
• Multidimensional: Exploratory and confirmatory MIRT
• Bifactor: Bifactor and hierarchical models

Advanced Models

• Cognitive Diagnostic: DINA, DINO, G-DINA
• Testlet: Random effects for item bundles
• Nested Logit: Keyed multiple-choice items with informative distractors
• Mixture IRT: Latent class IRT models
• Zero-Inflated: ZI-2PL, ZI-3PL, Hurdle IRT
• Unfolding: GGUM, Ideal Point, Hyperbolic Cosine
• Nonparametric: Monotonic spline IRFs
• Network Psychometrics: Ising and sparse Gaussian graphical models

Estimation Methods

• EM Algorithm: Gauss-Hermite quadrature (with Rust acceleration)
• GVEM: Gaussian Variational EM for fast high-dimensional estimation
• Sparse Bayesian: Spike-slab LASSO for automatic structure discovery
• MHRM: Metropolis-Hastings Robbins-Monro
• MCMC: Gibbs sampling for Bayesian estimation
• MCEM/QMCEM: Monte Carlo EM for high dimensions

Computerized Adaptive Testing (CAT)

• Item selection: MFI, MEI, KL divergence, a-stratified, Urry
• Stopping rules: SE threshold, max items, classification
• Exposure control: Sympson-Hetter, randomesque, progressive
• Content balancing: Blueprint constraints
• MCAT: Multidimensional CAT with D-optimality and trace criteria

Diagnostics & DIF

• Item fit: Infit, outfit, S-X2
• Person fit: Zh, lz, infit/outfit
• Model fit: M2, RMSEA, CFI, TLI, SRMSR
• DIF analysis: Likelihood ratio, Wald, Lord, Raju
• GRDIF: Generalized Residual DIF for multiple groups with robust scaling (MAD/IQR)
• DTF/DRF: Differential test/response functioning
• SIBTEST: Simultaneous item bias test
• Local dependence: Q3, chi-square residuals

Additional Features

• Custom dichotomous, ordinal, multidimensional, and latent group models
• Multiple group analysis with invariance testing
• Bootstrap standard errors and confidence intervals
• Plausible values for population inference
• Missing data imputation
• Built-in sample datasets
• Plotting (ICC, information, Wright maps, DIF)
• DataFrame output (pandas or polars)
• Fixed-item calibration and test equating
• Vertical scaling: Grade-level linking with growth constraints
• Reliable Change Index (RCI) for clinical significance
• Profile-likelihood confidence intervals
• Posterior parameter sampling
• Result objects: Validated uncertainty, confidence intervals, and portable exports
• HTML reports: Safe standalone summaries with optional embedded plots

Installation

pip install mirt

With optional dependencies:

pip install mirt[pandas]
pip install mirt[polars]
pip install mirt[dev]

For plotting support:

pip install "mirt[plot]"

Quick Start

import mirt

dataset = mirt.load_dataset("LSAT7")
responses = dataset["data"]

result = mirt.fit_mirt(responses, model="2PL")
print(result.summary())

scores = mirt.fscores(result, responses, method="EAP")
print(scores.to_dataframe().head())

Examples

Simulating Data

import mirt
import numpy as np

responses = mirt.simdata(model="2PL", n_persons=500, n_items=20, seed=42)

a = np.random.lognormal(0, 0.3, size=20)
b = np.random.normal(0, 1, size=20)
responses = mirt.simdata(model="2PL", discrimination=a, difficulty=b, n_persons=1000)

likert_data = mirt.simdata(model="GRM", n_categories=5, n_persons=500, n_items=15)

pcm_params = mirt.generate_item_parameters(
    n_items=15, model="PCM", n_categories=5, seed=42
)
pcm_data = mirt.simdata(
    model="PCM", n_persons=500, n_items=15, n_categories=5, **pcm_params
)

nrm_params = mirt.generate_item_parameters(
    n_items=10, model="NRM", n_categories=4, n_factors=2, seed=42
)
nrm_data = mirt.simdata(
    model="NRM", n_persons=500, n_items=10, n_categories=4,
    n_factors=2, **nrm_params
)

Fitting Models

result_1pl = mirt.fit_mirt(responses, model="1PL")
result_2pl = mirt.fit_mirt(responses, model="2PL")
result_3pl = mirt.fit_mirt(responses, model="3PL")

result_grm = mirt.fit_mirt(likert_data, model="GRM", n_categories=5)
result_gpcm = mirt.fit_mirt(likert_data, model="GPCM", n_categories=5)

result_mirt = mirt.fit_mirt(responses, model="2PL", n_factors=2)

Person Scoring

eap = mirt.fscores(result, responses, method="EAP")
map_scores = mirt.fscores(result, responses, method="MAP")
ml = mirt.fscores(result, responses, method="ML")

print(eap.theta)
print(eap.standard_error)

Diagnostics

item_fit = mirt.itemfit(result, responses)
print(item_fit)

person_fit = mirt.personfit(result, responses)
aberrant = person_fit[person_fit["Zh"] < -2]

fit_indices = mirt.compute_fit_indices(result.model, responses)
print(fit_indices)

results = [result_1pl, result_2pl, result_3pl]
comparison = mirt.compare_models(results)

DIF Analysis

groups = np.array([0] * 250 + [1] * 250)

dif_lr = mirt.dif(responses, groups, method="likelihood_ratio")

dif_wald = mirt.dif(responses, groups, method="wald")
dif_lord = mirt.dif(responses, groups, method="lord")
dif_raju = mirt.dif(responses, groups, method="raju")

from mirt.diagnostics.dif import compute_grdif

groups_multi = np.array(["A"] * 200 + ["B"] * 200 + ["C"] * 200)
grdif_result = compute_grdif(
    responses, groups_multi,
    model="2PL",
    scaling_method="mad",
)
print(f"Flagged items: {np.where(grdif_result['flagged_rs'])[0]}")

Multiple Group Analysis

from mirt.multigroup import fit_multigroup, compare_invariance

result = fit_multigroup(responses, groups, model="2PL", invariance="metric")

results = compare_invariance(responses, groups, model="2PL", verbose=True)

Computerized Adaptive Testing

from mirt.cat import CATEngine

cat = CATEngine(result.model, se_threshold=0.3, max_items=20)

sim_results = cat.run_batch_simulation(
    true_thetas=np.linspace(-2, 2, 11),
    n_replications=100,
)

state = cat.get_current_state()
while not state.is_complete:
    item = state.next_item
    response = get_examinee_response(item)
    state = cat.administer_item(response)

final = cat.get_result()
print(final.summary())

from mirt.cat import MCATEngine

mcat = MCATEngine(
    mirt_model,
    selection_method="D-optimality",
    max_items=30,
)
mcat_result = mcat.run_simulation(true_theta=np.array([0.5, -0.3]))
print(f"Estimated theta: {mcat_result.theta}")
print(f"Covariance: {mcat_result.theta_cov}")

Advanced Models

from mirt import fit_cdm
q_matrix = np.array([[1, 0], [1, 1], [0, 1], [1, 1]])
cdm_result = fit_cdm(responses, q_matrix, model="DINA")

from mirt import fit_mixture_irt
mix_model, class_posteriors = fit_mixture_irt(
    responses, n_classes=2, base_model="2PL"
)

from mirt import TestletModel, create_testlet_structure
testlet_struct = create_testlet_structure(n_items=20, testlet_sizes=[5, 5, 5, 5])

Custom Item Models

import numpy as np

from mirt import CustomItemModel, create_item_type

def adjacent_categories(theta, shift):
    weights = np.column_stack((
        np.ones_like(theta),
        np.exp(theta - shift),
        np.exp(2 * (theta - shift)),
    ))
    return weights / weights.sum(axis=1, keepdims=True)

spec = create_item_type(
    "AdjacentCategories",
    adjacent_categories,
    par_bounds={"shift": (-4, 4)},
    par_defaults={"shift": 0},
    n_categories=3,
)
model = CustomItemModel(n_items=10, item_type=spec)
probabilities = model.probability(np.linspace(-3, 3, 61))

Exploratory Factor Analysis with Automatic Structure Discovery

from mirt import TwoParameterLogistic
from mirt.estimation import SparseBayesianEstimator, GVEMEstimator

model = TwoParameterLogistic(n_items=20, n_factors=5)
estimator = SparseBayesianEstimator(k_max=5, lambda_0=0.04, lambda_1=1.0)
result = estimator.fit(model, responses)

print(f"Effective dimensions: {result.effective_dimensionality}")
print(f"Sparsity ratio: {1 - result.sparsity_pattern.mean():.1%}")
print(result.loading_table())

estimator = GVEMEstimator(max_iter=200, tol=1e-4)
result = estimator.fit(model, responses)

Test Equating & Calibration

from mirt.utils import fixed_calib, equate, Q3, residuals

calib_result = fixed_calib(
    responses=combined_responses,
    anchor_model=existing_model,
    anchor_items=[0, 1, 2, 3, 4],
)
print(f"New item difficulties: {calib_result.new_difficulty}")

equating = equate(
    model_old=form_a_model,
    model_new=form_b_model,
    anchor_items_old=[0, 1, 2],
    anchor_items_new=[0, 1, 2],
    method="stocking_lord",
)
print(f"Scale transformation: theta_new = {equating.A:.3f} * theta_old + {equating.B:.3f}")

q3_matrix = Q3(result.model, responses, scores.theta)
resid = residuals(result.model, responses, scores.theta)
print(f"Max Q3 (off-diagonal): {np.max(np.abs(np.triu(q3_matrix, 1))):.3f}")

Vertical Scaling

from mirt.equating import vertical_scale, GradeData, compute_vertical_diagnostics

grade_data = [
    GradeData("Grade 3", responses_g3, anchor_items_above=[0, 1, 2, 3, 4]),
    GradeData("Grade 4", responses_g4, anchor_items_below=[10, 11, 12, 13, 14],
              anchor_items_above=[0, 1, 2, 3, 4]),
    GradeData("Grade 5", responses_g5, anchor_items_below=[10, 11, 12, 13, 14]),
]

result = vertical_scale(
    grade_data,
    method="chain",
    enforce_monotonicity=True,
)

print(f"Grade means: {result.grade_means}")
print(f"Growth curve: {result.growth_curve}")

diagnostics = compute_vertical_diagnostics(result, grade_data)
print(f"Grade separation (effect sizes): {diagnostics.grade_separation}")

Plotting

from mirt import (
    plot_category_curves,
    plot_icc,
    plot_information,
    plot_person_item_map,
)

plot_icc(result.model, item_idx=[0, 1, 2])

plot_information(result.model)

# Polytomous category response curves
plot_category_curves(result.model, item_idx=0)

plot_person_item_map(result.model, scores.theta)

Supported Models

Dichotomous Models

Polytomous Models

Advanced Models

API Reference

Main Functions

Estimator Classes

Diagnostic Functions

Utility Functions

Data Transformation Functions

Information Functions

Comparison with R mirt

Rust Acceleration

When the Rust backend is available (automatically built during installation), the following operations are accelerated with parallel processing:

Fallback contract

Rust wrappers declare one of four modes (see each module's FALLBACK_MODE):

Most hot paths (likelihood, E-step, scoring, diagnostics, simulation) are numpy. A few full-fit helpers such as em_fit_2pl are required — fit_mirt(..., estimation="EM") still works without Rust via EMEstimator.

Disable Rust globally with:

import mirt
mirt.set_backend("numpy")

Per-call use_rust=False also disables Rust for that call. mirt.should_use_rust() reports the effective decision.

The Rust backend provides significant speedups for large datasets (1000+ persons) due to:

• Rayon parallelization: Computation across persons or items runs in parallel
• SIMD optimizations: Vectorized arithmetic where available
• Memory efficiency: Reduced allocations compared to NumPy broadcasting

To check if Rust acceleration is available:

import mirt
print(mirt.get_backend_info())
print(f"Rust extension: {mirt.is_rust_available()}")

Requirements

Core Dependencies (always required)

• Python >= 3.11
• numpy >= 1.24
• scipy >= 1.9

Optional Dependencies

When neither pandas nor polars is installed, functions that return DataFrames will raise an ImportError with installation instructions. Plotting functions similarly require matplotlib.

To set your preferred DataFrame backend explicitly:

import mirt
mirt.set_dataframe_backend("pandas")

Restore automatic selection at any time with mirt.set_dataframe_backend("auto") (or None). Use mirt.get_dataframe_backend() to inspect the active backend.

Development

git clone https://github.com/Cameron-Lyons/mirt.git
cd mirt
uv venv
uv pip install -e ".[dev]"

uv run maturin develop --release

uv run pytest

uv run mypy src/mirt

uv run ruff format src tests
uv run ruff check src tests

uv run pytest -m slow

uv run pytest tests/test_performance_smoke.py

uv run python benchmarks/run_benchmarks.py

API Stability (v1.1)

Starting with v1.0, this package follows semantic versioning. The current release is 1.1.0.

Stable Public API

The following are guaranteed stable and will not have breaking changes in v1.x releases:

• Core functions: fit_mirt(), fscores(), simdata(), itemfit(), personfit(), dif()
• Result classes: FitResult, ScoreResult, CVResult, BatchFitResult
• Model classes: All IRT models (TwoParameterLogistic, GradedResponseModel, etc.)
• CAT: CATEngine, CATResult, CATState
• Diagnostics: compare_models(), anova_irt(), compute_fit_indices(), sibtest()
• Utilities: bootstrap_se(), bootstrap_ci(), generate_plausible_values(), cross_validate(), fit_models()
• Data functions: load_dataset(), list_datasets(), set_dataframe_backend(), get_dataframe_backend()
• Backend selection: set_backend(), get_backend(), get_backend_info(), should_use_rust(), is_rust_available()

Experimental (may change in minor releases)

• Internal _rust_backend / backends.rust module functions (use public wrappers instead)
• MCMC samplers (GibbsSampler, MHRMEstimator) - API may be refined
• Cognitive Diagnostic Models (DINA, DINO, fit_cdm()) - under active development

Versioning Policy

• Major version (2.0, 3.0): Breaking API changes
• Minor version (1.1, 1.2): New features, backward compatible
• Patch version (1.0.1, 1.0.2): Bug fixes only

License

MIT License - see LICENSE

Citation

If you use this package in your research, please cite:

@software{mirt_python,
  author = {Lyons, Cameron},
  title = {mirt: Multidimensional Item Response Theory for Python},
  url = {https://github.com/Cameron-Lyons/mirt},
  version = {1.1.0}
}

References

• Chalmers, R. P. (2012). mirt: A Multidimensional Item Response Theory Package for the R Environment. Journal of Statistical Software, 48(6), 1-29.
• Bock, R. D., & Aitkin, M. (1981). Marginal maximum likelihood estimation of item parameters: Application of an EM algorithm. Psychometrika, 46(4), 443-459.
• Cho, A. E., Wang, C., Zhang, X., & Xu, G. (2021). Gaussian variational estimation for multidimensional item response theory. British Journal of Mathematical and Statistical Psychology, 74, 52-85.
• Rockova, V., & George, E. I. (2018). The spike-and-slab LASSO. Journal of the American Statistical Association, 113(521), 431-444.
• de la Torre, J. (2011). The generalized DINA model framework. Psychometrika, 76(2), 179-199.