rasch-per 0.1.0__tar.gz

rasch_per-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint
+        run: |
+          ruff check .
+          ruff format --check .
+      - name: Type check
+        run: mypy
+      - name: Test with coverage gate
+        # Coverage gate (85%) is enforced now that the library modules are
+        # implemented (Phases 0-5).
+        run: pytest --cov=rasch_per --cov-fail-under=85 --cov-report=xml
+      - name: Upload coverage
+        if: matrix.python-version == '3.13'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage.xml
+          path: coverage.xml

rasch_per-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,45 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docsrc/**"
+      - "mkdocs.yml"
+      - ".readthedocs.yaml"
+      - "pyproject.toml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install docs extra
+        run: python -m pip install --upgrade pip && python -m pip install ".[docs]"
+      - name: Build site
+        run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

rasch_per-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,60 @@
+name: Publish to PyPI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*.*.*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    # Requires Trusted Publishing configured on testpypi.org for this repo
+    # (manual one-time setup, done in Phase 7). Until then, opt in by setting
+    # the repository variable ENABLE_TESTPYPI_PUBLISH=true; the job skips
+    # otherwise so pushes to main stay green.
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/heads/main') && vars.ENABLE_TESTPYPI_PUBLISH == 'true'
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI (Trusted Publisher)
+        uses: pypa/gh-action-pypi-publish@release/v1

rasch_per-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# FirstHQ workflow files (never commit)
+docs/
+AGENT.md
+CONTEXT.json
+TODO.md
+update.md
+log.md
+.opencode/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+site/
+.mkdocs_cache/
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/

rasch_per-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: mypy
+        language: system
+        pass_filenames: false

rasch_per-0.1.0/.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

rasch_per-0.1.0/.validation.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+set -e
+
+cd "$(dirname "$0")"
+
+if [ ! -d ".venv" ]; then
+    echo "Creating virtualenv..."
+    uv venv --python 3.13 .venv
+    uv pip install -e ".[dev]" -p .venv
+fi
+PY=".venv/bin/python"
+
+echo "=== Validation Loop ==="
+
+echo "[1/4] Building..."
+$PY -m compileall -q src/rasch_per
+
+echo "[2/4] Type checking..."
+$PY -m mypy src/
+
+echo "[3/4] Linting..."
+$PY -m ruff check .
+$PY -m ruff format --check .
+
+echo "[4/4] Testing..."
+$PY -m pytest --cov=rasch_per -q
+# Coverage gate (85%) is enforced in CI (.github/workflows/ci.yml), not locally.
+
+echo "=== All checks passed ==="

rasch_per-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Project scaffolding: package skeleton, CLI entry point, CI and publish workflows.

rasch_per-0.1.0/CITATION.cff

@@ -0,0 +1,25 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: rasch-per
+abstract: >-
+  Rasch model and Classical Test Theory (CTT) psychometric analysis for
+  education research, built for physics / STEM / discipline-based education
+  researchers (PER / DBER). Provides person abilities, item difficulties,
+  fit statistics, dimensionality checks, differential item functioning (DIF)
+  analysis, and a self-contained HTML validity report from dichotomous
+  item-response data.
+authors:
+  - family-names: Anil
+    given-names: Aditya
+    email: aditya.anil.productions@gmail.com
+repository-code: "https://github.com/aditya-an1l/rasch-per"
+url: "https://github.com/aditya-an1l/rasch-per"
+license: MIT
+version: 0.1.0
+date-released: 2026-08-27
+keywords:
+  - psychometrics
+  - rasch
+  - item response theory
+  - education research
+  - physics education research

rasch_per-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing to rasch-per
+
+Thanks for your interest in contributing.
+
+## Development setup
+
+```bash
+git clone https://github.com/aditya-an1l/rasch-per
+cd rasch-per
+uv venv --python 3.13 .venv
+uv pip install -e ".[dev]" -p .venv
+```
+
+Or with plain pip:
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Running checks
+
+```bash
+./.validation.sh          # build + type check + lint + tests
+python -m pytest          # tests only (with coverage)
+python -m ruff check .    # lint only
+python -m mypy            # types only
+```
+
+CI runs the same checks on Python 3.10-3.13 and enforces a 85% coverage gate.
+Both `ruff check` and `mypy` must pass before any PR is merged.
+
+## Code style expectations
+
+- Full NumPy-style docstrings (Parameters, Returns, worked mini-example) on
+  every public function/class.
+- Type hints everywhere; no new hard dependencies without discussion first.
+- Statistical formulas follow the conventions fixed in the project spec; do
+  not swap in alternative conventions from other sources without raising it
+  for discussion first.
+- All example/test data comes from `rasch_per.simulate` - never vendor
+  third-party data or item text.
+
+## Publishing (maintainers)
+
+The GitHub Actions workflow `.github/workflows/publish.yml` builds and
+publishes via PyPI Trusted Publishing on tagged releases (`v*.*.*`). TestPyPI
+publishes on every push to `main`.
+
+Manual publish (first-time alternative):
+
+```bash
+python -m pip install --upgrade build twine
+python -m build
+twine check dist/*
+twine upload --repository testpypi dist/*     # sanity check first
+twine upload dist/*                            # real release
+```

rasch_per-0.1.0/GRILL.md

@@ -0,0 +1,20 @@
+# Grill Session — 2026-08-27
+
+## Project: rasch-per
+
+### Shortcomings
+
+- AGENT.md references `docs/skills/SPEC.md` as the authoritative source for resolved conventions (Q3 adjustment, ETS delta sign, Ferguson delta), but that file does not exist in the repo. Phase 3 implemented `fit.py` (Yen's Q3) and `dimensionality.py` (PCAR) using the standard published formulas rather than a spec-pinned variant. Risk: if the spec specified a non-standard Q3 adjustment or PCAR centering, current output diverges from intended behavior.
+
+### Unresolved Questions
+
+- Where is the original build spec (the SPEC.md source)? It drove Phases 0-2 but is not on disk. Does the user have it, or was it only in the earlier chat session?
+- Should the Q3 / PCAR implementation use the classic residual-correlation form (current) or a spec-specific adjustment once recovered?
+
+### Next Steps
+
+- Recover or re-supply SPEC.md (or the relevant convention snippets) and re-verify fit.py / dimensionality.py against it before Phase 5 (DIF, which also depends on the ETS delta sign convention).
+
+## Resolved 2026-08-27
+
+- The SPEC.md gap (shortcoming above) was closed by reconstructing `docs/skills/SPEC.md` from the implemented code. The original Phase 0-2 spec remains unavailable; the reconstructed conventions use the standard published forms (Yen 1984 Q3, ETS delta sign positive = easier for focal, Ferguson delta per Ferguson 1949). If the original spec is recovered, diff and correct before a public release.

rasch_per-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aditya Anil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rasch_per-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.5
+Name: rasch-per
+Version: 0.1.0
+Summary: Rasch model and CTT psychometric analysis for education research
+Project-URL: Homepage, https://github.com/aditya-an1l/rasch-per
+Project-URL: Repository, https://github.com/aditya-an1l/rasch-per
+Project-URL: Issues, https://github.com/aditya-an1l/rasch-per/issues
+Author-email: Aditya Anil <aditya.anil.productions@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: education research,item response theory,physics education research,psychometrics,rasch
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: jinja2>=3.1
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scipy>=1.10
+Requires-Dist: typer>=0.9
+Provides-Extra: cfa
+Requires-Dist: semopy; extra == 'cfa'
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pandas-stubs; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: scipy-stubs; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.5; extra == 'docs'
+Provides-Extra: pdf
+Requires-Dist: weasyprint; extra == 'pdf'
+Description-Content-Type: text/markdown
+
+# rasch-per
+
+Rasch model and Classical Test Theory (CTT) psychometric analysis for
+education research, built for physics / STEM / discipline-based education
+researchers (PER / DBER).
+
+Feed it a CSV of dichotomous (0/1) item responses and get person abilities,
+item difficulties, fit statistics, dimensionality checks, DIF analysis, and a
+full self-contained HTML validity report.
+
+Status: implemented and validated (119 tests, ~97% coverage). The library is
+Beta; the public API is stable for the analyses listed below.
+
+## Quickstart (CLI)
+
+```bash
+pip install rasch-per
+rasch-per simulate --output demo.csv
+rasch-per analyze demo.csv --output report.html
+```
+
+`simulate` writes a synthetic response CSV (with a `person_id` index). `analyze`
+reads it back (the first column is the person index), runs the full pipeline,
+and writes a self-contained HTML report.
+
+```bash
+# With differential item functioning (DIF) by a group column
+rasch-per analyze demo.csv --groups groups.csv --dif-group gender \
+    --reference Man --focal Non-man --output report.html
+```
+
+## Python API
+
+```python
+import pandas as pd
+from rasch_per import (
+    ResponseData,
+    CTTAnalysis,
+    RaschModel,
+    DIFAnalysis,
+    generate_report,
+)
+
+# Load a response matrix (persons as rows, items as columns)
+df = pd.read_csv("responses.csv", index_col=0)
+data = ResponseData(df)
+
+# Classical Test Theory
+ctt = CTTAnalysis(data).run()
+print(ctt.summary())
+print(ctt.reliability.cronbach_alpha)  # attribute, not a method
+
+# Rasch (MML is the default estimator)
+model = RaschModel().fit(data, estimator="MML")
+print(model.item_difficulties)  # pandas Series indexed by item name
+print(model.fit_statistics())  # infit / outfit mean-squares
+
+# Differential Item Functioning
+groups = pd.read_csv("groups.csv", index_col=0)["gender"].reindex(data.person_ids)
+dif = DIFAnalysis(model, groups=groups.to_numpy(), reference="Man", focal="Non-man").analyze()
+print(dif.summary())  # ETS delta classification + BH flags
+
+# Self-contained HTML validity report
+generate_report(
+    df,
+    output="validity_report.html",
+    groups=groups.to_numpy(),
+    reference="Man",
+    focal="Non-man",
+)
+```
+
+Notes on the API:
+
+- `generate_report` takes a `pandas.DataFrame`, not a `ResponseData`. When you
+  pass `groups`, they must be aligned to the DataFrame's row order (here, the
+  person index).
+- `CTTResults.reliability` is an attribute (`cronbach_alpha`, `mcdonald_omega`,
+  `ferguson_delta`), not a callable.
+- `DIFAnalysis` is run with `.analyze()` (it returns a `DIFResults`).
+
+## What's inside
+
+- **CTT**: item difficulty (p-values), discrimination (corrected item-total,
+  rest-score based) with bootstrap SEs; Cronbach's alpha, McDonald's omega,
+  Ferguson's delta.
+- **Rasch**: JML and MML estimation (MML default), standard errors.
+- **Fit**: infit/outfit mean-square with low-stakes/high-stakes presets;
+  Yen's Q3 local independence check.
+- **Dimensionality**: PCAR first-contrast eigenvalue diagnostic.
+- **DIF**: Lord's chi-square, mean/mean linking, ETS delta effect sizes,
+  Benjamini-Hochberg correction.
+- **Report**: single-file HTML validity report with embedded plots.
+
+## Methodology & References
+
+This package implements standard, published psychometric methods used
+throughout physics / discipline-based education research:
+
+- Rasch model (Rasch, 1960; Wright & Stone, 1979)
+- Joint and marginal maximum likelihood estimation (e.g., as in R packages
+  `TAM`, `eRm`)
+- Infit/outfit mean-square fit statistics (Smith, 2000; Linacre, 2002)
+- Yen's Q3 local independence statistic (Yen, 1984)
+- Principal components analysis of residuals (Linacre, 1998)
+- Lord's chi-square DIF test (Lord, 1980)
+- ETS delta scale DIF classification (ETS categories A/B/C)
+- Benjamini-Hochberg false discovery rate control (Benjamini & Hochberg, 1995)
+- Cronbach's alpha (Cronbach, 1951), McDonald's omega (McDonald, 1999),
+  Ferguson's delta (Ferguson, 1949)
+
+No third-party assessment content or data is included; all examples use
+synthetic data from the package's own simulator.
+
+## Documentation & Examples
+
+- API and usage docs: `mkdocs serve` (source in `docsrc/`, requires the
+  `docs` extra: `pip install "rasch-per[docs]"`).
+- Worked notebooks: `examples/notebooks/quickstart.ipynb` and
+  `examples/notebooks/report_walkthrough.ipynb`.
+- Optional analyses (PDF export, CFA, Stocking-Lord linking, R cross-validation)
+  live in `scripts/` and use the `pdf` / `cfa` extras where needed.
+
+## Screenshots
+
+Key diagnostic plots produced by the package's plotting API on simulated data
+(500 persons, 20 items, seed 42):
+
+| Plot | Description |
+|------|-------------|
+| ![Wright map](images/wright_map.png) | Person ability vs item difficulty (Wright map) |
+| ![Test information](images/test_information.png) | Test information and standard error of measurement across the ability scale |
+| ![ICC](images/icc.png) | Item characteristic curve with empirical overlay (item 1) |
+| ![Item difficulty](images/item_difficulty.png) | CTT item difficulty with bootstrap standard-error bars |
+| ![Item discrimination](images/item_discrimination.png) | CTT item point-biserial discrimination |
+| ![DIF contrasts](images/dif_contrasts.png) | DIF contrasts with ETS A/B/C classification |
+
+The figures are generated from `simulate_rasch_data` and the analysis pipeline
+(CTT, Rasch MML, DIF).
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Validation loop: `./.validation.sh`.
+
+## License
+
+MIT