alterlab-sem-psychometrics

$npx mdskill add AlterLab-IEU/AlterLab-Academic-Skills/alterlab-sem-psychometrics

Fits and evaluates measurement models using SEM, EFA, CFA, IRT, and invariance testing.

  • Solves fitting and evaluating latent variable models like CFA and SEM.
  • Depends on semopy, factor_analyzer, pingouin, and optionally girth.
  • Decides based on keywords like CFA, SEM, factor loadings, IRT, or invariance.
  • Returns fit statistics, loadings, omega, and model comparison results.

SKILL.md

.github/skills/alterlab-sem-psychometricsView on GitHub ↗
---
name: alterlab-sem-psychometrics
description: "Fits and evaluates measurement models — confirmatory factor analysis, full structural equation models, exploratory factor analysis, item response theory, and multi-group measurement invariance — using the verified Python stack: semopy (model syntax =~ / ~ / ~~, Model.fit, inspect(std_est=True), calc_stats for CFI/TLI/RMSEA), factor_analyzer (EFA, KMO, Bartlett, ConfirmatoryFactorAnalyzer), and pingouin/girth, computing McDonald's omega from standardized loadings and judging fit against Hu & Bentler cutoffs. Use when the request mentions confirmatory factor analysis, structural equation modeling, a latent variable or construct model, factor loadings, IRT, or measurement invariance across groups. For deciding whether a scale is trustworthy at all prefer alterlab-ssci-measurement-gate; for plain regression prefer alterlab-statistical-analysis. Part of the AlterLab Academic Skills suite."
license: MIT
allowed-tools: Read Bash(python:*)
compatibility: "Requires (declare in-session, no runtime install on Anthropic API): semopy>=2.3, factor_analyzer>=0.5, pingouin>=0.5, optionally girth (IRT) (pip). SRMR and omega are not returned by semopy — compute omega with the bundled script; IRT beyond 2PL is often better in R mirt. Runs locally via `uv run python`; no API key."
metadata:
    skill-author: AlterLab
    version: "1.0.0"
    depends_on: "alterlab-ssci-measurement-gate (gates whether to trust the scale), alterlab-statistical-analysis; audited by alterlab-ssci-inference-gate"
---

# SEM & Psychometrics — Fit the Measurement Model, Judge It Honestly

**Skill type: ANALYSIS MODULE.** Fits CFA / SEM / EFA / IRT and tests measurement invariance.
The discipline: report fit against real cutoffs, report reliability with **omega** (not alpha
alone), and establish invariance before comparing groups. Whether the scale should be trusted at
all is the upstream call of `alterlab-ssci-measurement-gate`.

## Core Mission

```
A MEASUREMENT MODEL IS ONLY DONE WHEN FIT, RELIABILITY (OMEGA), AND INVARIANCE ARE ALL REPORTED.
```

## When to Use This Skill

- "Run a confirmatory factor analysis on my scale."
- "Fit a structural equation model / a latent-variable path model."
- "Do an exploratory factor analysis — how many factors?"
- "Fit an IRT model / get item difficulty and discrimination."
- "Test measurement invariance across countries before I compare latent means."

### Does NOT Trigger

| The request is really about… | Route to | Why not this skill |
|---|---|---|
| Whether the scale is valid/trustworthy at all (reliability≠validity discipline) | `alterlab-ssci-measurement-gate` | Gate decision, upstream of fitting. |
| Writing / wording the questionnaire items | `alterlab-survey-design` | Instrument construction. |
| Plain regression / descriptive stats | `alterlab-statistical-analysis` | No latent structure. |
| A causal treatment-effect estimate | `alterlab-causal-inference` | Different problem. |

## Verified calls (pinned)

**CFA / SEM — semopy (v2.3):**

```python
from semopy import Model, calc_stats
desc = """
# measurement model
Trust =~ q1 + q2 + q3
Efficacy =~ q4 + q5 + q6
# structural path
Trust ~ Efficacy
"""
m = Model(desc); m.fit(data)          # obj='MLW' default; 'FIML' for missing
est = m.inspect(std_est=True)          # standardized loadings for omega
stats = calc_stats(m)                  # DataFrame: chi2, CFI, TLI, RMSEA, AIC, BIC ...
```

Note: `calc_stats` returns CFI/TLI/RMSEA but **not SRMR** — report the indices it gives and
compute SRMR separately if required.

**EFA — factor_analyzer (v0.5):**

```python
from factor_analyzer import FactorAnalyzer, calculate_kmo, calculate_bartlett_sphericity
kmo_all, kmo_model = calculate_kmo(X)          # sampling adequacy > .60
chi2, p = calculate_bartlett_sphericity(X)      # sphericity
fa = FactorAnalyzer(n_factors=3, rotation="promax"); fa.fit(X)
fa.loadings_; fa.get_factor_variance()          # (variance, proportional, cumulative)
```

`ConfirmatoryFactorAnalyzer` + `ModelSpecificationParser.parse_model_specification_from_dict`
give a CFA alternative when semopy is unavailable.

**Reliability — omega (not alpha alone):** pingouin gives `cronbach_alpha` but **no omega**, and
semopy does not return omega. Compute McDonald's omega from the standardized loadings with
`scripts/omega.py` (ω = (Σλ)² / [(Σλ)² + Σ(1−λ²)]). Report alpha + omega together.

**IRT:** `girth` (`twopl_mml`, `rasch_mml`) for dichotomous 2PL/Rasch; `py-irt` for Bayesian/
scalable. For polytomous/multidimensional IRT with full fit statistics, R `mirt` is the practical
standard — say so rather than forcing a thin Python path.

## Fit cutoffs (Hu & Bentler 1999, as guidelines not gates)

CFI/TLI ≥ .95 · RMSEA ≤ .06 · SRMR ≤ .08. Use a two-index combination; do not chase a single
number. Report the χ² and df alongside (χ² is sample-size sensitive, so not decisive).

## Measurement invariance (before any group comparison)

Multi-group CFA sequence — **configural → metric → scalar → strict** — judged by ΔCFI ≤ .01 /
ΔRMSEA ≤ .015, not only Δχ². Scalar invariance is the prerequisite for comparing **latent means**;
without it a group "difference" may be a measurement artifact. Fit each nested model and compare.

## Output Template

```
MODEL:        <CFA/SEM/EFA/IRT + the semopy/factor_analyzer spec>
FIT:          CFI= TLI= RMSEA= (chi2/df=)   vs Hu & Bentler cutoffs
RELIABILITY:  omega= (alpha= )              per factor, from standardized loadings
VALIDITY:     <AVE, HTMT if convergent/discriminant claimed>
INVARIANCE:   <configural|metric|scalar|strict established; ΔCFI reported>
```

## References

- `references/fit_and_invariance.md` — omega math, fit-index nuance, the invariance sequence, IRT notes.
- `scripts/omega.py` — stdlib McDonald's omega from standardized loadings.

Part of the AlterLab Academic Skills suite.

More from AlterLab-IEU/AlterLab-Academic-Skills

SkillDescription
alterlab-abm-mesaBuilds agent-based models of social systems with Mesa 3 — the current AgentSet API (model.agents.shuffle_do('step'), auto-assigned unique_id, mandatory super().__init__(seed=...)), cell spaces (mesa.discrete_space OrthogonalMooreGrid / classic mesa.space grids), the DataCollector, batch_run parameter sweeps, and SolaraViz — for emergence, segregation, diffusion, opinion dynamics, and cooperation models. It uses the Mesa 3.x API (the old mesa.time schedulers like RandomActivation are removed) and treats the model as a generative theory to be validated, not just run. Use when the request mentions an agent-based model, Mesa, simulating interacting agents, or emergent macro behavior from micro rules. For discrete-event (queueing/process) simulation prefer alterlab-simpy; for reinforcement learning prefer alterlab-stable-baselines3. Part of the AlterLab Academic Skills suite.
alterlab-academic-careerPrepares academic career documents and professional-development materials for faculty and researchers. Use when drafting academic CVs, research statements, teaching philosophies, diversity statements, faculty-position cover letters, tenure dossiers, promotion narratives, academic portfolios, or mentorship statements, and when planning conference-networking strategy, building academic web presence, setting up ORCID profiles, or understanding impact metrics. Part of the AlterLab Academic Skills suite.
alterlab-accreditation-aolScaffolds program-level Assurance-of-Learning (AoL) documentation for AACSB (2020 Standard 5) and ABET (Criterion 3 Student Outcomes, Criterion 4 Continuous Improvement) accreditation — program learning outcomes / competency goals, curriculum-to-outcome mapping matrices, direct- and indirect-assessment plans, rubric design, and closing-the-loop continuous-improvement narratives — and validates the structure of an outcome-mapping matrix with scripts/aol_matrix.py. Use when the user needs AACSB or ABET assurance-of-learning material, a program-learning-outcomes set, a curriculum/outcome map or coverage matrix, a direct/indirect assessment plan, a closing-the-loop report, or accreditation self-study text. For single-course design or course rubrics prefer alterlab-teaching-design; for post-award grant reports prefer alterlab-grant-reporting. Part of the AlterLab Academic Skills suite.
alterlab-adaptyvSubmits and tracks protein-testing experiments on the Adaptyv Bio Foundry cloud lab (wet-lab validation), and optimizes protein sequences before submission with computational tools (NetSolP, SoluProt, SolubleMPNN, ESM). Use when designing proteins that need wet-lab validation - binding/affinity screening, expression testing, thermostability, or fluorescence assays - or when submitting experiments to the Foundry API, browsing the target catalog, tracking experiment status, retrieving results, or pre-screening sequences for solubility/expression. Triggers on "Adaptyv", "Foundry API", "cloud lab", "biolayer interferometry / BLI", "wet-lab validation". Part of the AlterLab Academic Skills suite.
alterlab-aeonRuns time series machine learning with the aeon library — classification, regression, clustering, forecasting, anomaly detection, segmentation, and similarity search via scikit-learn compatible APIs. Use when working with temporal data, sequential patterns, or time-indexed observations (univariate or multivariate) that need specialized algorithms beyond standard ML approaches. Part of the AlterLab Academic Skills suite.
alterlab-akademik-tesvikComputes the annual Turkish academic-incentive (akademik teşvik) score for Devlet (state) university öğretim elemanı (academic staff) from a classified activity list, applying the verified Akademik Teşvik Ödeneği Yönetmeliği (2018/11834) Faaliyet Hesaplama Tablosu headline puanları (Proje 20, Araştırma 15, Yayın 30, Patent 30, Atıf 30, Tebliğ 20, Ödül 20) with the k (author-count), p (Q1 1/Q2 0.8/Q3 0.5/Q4 0.25), and r (project-role) coefficients via türü puanı = Σ(faaliyet oranları) × headline (MADDE 8/2), then enforcing the per-type headline ceilings, the 100 cap (MADDE 8/3), and the net-30 payment gate (MADDE 10/3) in a deterministic scripts/tesvik_score.py. Use when the user wants to calculate akademik teşvik puanı, check the en az 30 (net-30) threshold, apply TABLO 4 ceilings, or estimate teşvik eligibility; keeps its coefficients separate from doçentlik scoring. For doçentlik point eligibility prefer alterlab-docentlik-eligibility. Part of the AlterLab Academic Skills suite.
alterlab-alpha-vantageAccesses real-time and historical stock market data, forex rates, cryptocurrency prices, commodities, economic indicators, and 50+ technical indicators via the Alpha Vantage API (requires a free API key from alphavantage.co). Use when fetching stock prices (OHLCV), company fundamentals (income statement, balance sheet, cash flow), earnings, options data, market news/sentiment, insider transactions, GDP, CPI, treasury yields, gold/silver/oil prices, Bitcoin/crypto prices, forex exchange rates, or calculating technical indicators (SMA, EMA, MACD, RSI, Bollinger Bands). Part of the AlterLab Academic Skills suite.
alterlab-alphafoldPredict protein 3D structures with AlphaFold2 via ColabFold — MMseqs2-accelerated MSAs, monomer and AlphaFold2-Multimer complex folding, and confidence-based validation (pLDDT, pTM/ipTM, PAE). Use when folding a protein sequence or complex from FASTA, generating a predicted structure with confidence metrics, ranking models, or checking self-consistency of a design. For co-folding a protein WITH a small-molecule ligand or predicting binding affinity prefer alterlab-boltz; for antibody–antigen or one-FASTA multi-entity complexes prefer alterlab-chai; to LOOK UP an already-computed structure prefer alterlab-alphafold-db; for ESM embeddings or inverse folding prefer alterlab-esm. Part of the AlterLab Academic Skills suite.
alterlab-alphafold-dbAccess the AlphaFold DB of 200M+ AI-PREDICTED protein structures — retrieve models by UniProt accession, download PDB/mmCIF files, and analyze prediction confidence metrics (pLDDT, PAE). Use when a UniProt ID needs a computationally predicted 3D structure or when no experimental structure exists, for homology modeling, protein engineering, or structure-based drug discovery; for EXPERIMENTALLY determined structures (X-ray, cryo-EM, NMR) prefer alterlab-pdb, and for protein sequences, annotations, or accession ID mapping prefer alterlab-uniprot instead. Part of the AlterLab Academic Skills suite.
alterlab-anndataBuild, slice, concatenate, read, and write AnnData annotated data matrices (obs, var, X, layers, obsm, uns) — the scverse data STRUCTURE, not an analysis pipeline. Use when creating or wrangling .h5ad/zarr files, managing cell and gene annotations, concatenating batches, or handling layers/obsm/backed-mode; for the QC, normalization, clustering, UMAP, and differential-expression analysis pipeline prefer alterlab-scanpy instead, and for RNA velocity from spliced/unspliced layers prefer alterlab-scvelo instead. Part of the AlterLab Academic Skills suite.