mfrmpy 0.1.0__tar.gz

mfrmpy-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+__pycache__/
+*.py[cod]
+*$py.class
+.Python
+.venv/
+.venv-win/
+venv/
+env/
+.pytest_cache/
+.playwright-cli/
+.mypy_cache/
+.ruff_cache/
+/dist/
+/build/
+/*.egg-info/
+.DS_Store
+.streamlit/secrets.toml
+benchmark_*.csv
+*_benchmark.csv
+parity_fixture/
+validation/generated/
+*.log
+backups/
+
+# Local source archives for retained research evidence
+/validation/source_snapshots/

mfrmpy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryuya-dot-com
+
+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.

mfrmpy-0.1.0/LICENSE_NOTICE.md

@@ -0,0 +1,30 @@
+# License and Responsible Use Notice
+
+This repository is released under the MIT License unless a file explicitly
+states otherwise. The MIT License permits commercial and non-commercial use,
+copying, modification, distribution, sublicensing, and sale, provided that the
+copyright notice and license notice are included in substantial copies of the
+software or associated documentation.
+
+The project intentionally does not use a NonCommercial license such as
+CC BY-NC, because that would conflict with the intended permission for
+commercial use, including paid teaching, consulting, training, and hosted
+demonstrations.
+
+The software and documentation are provided "as is", without warranty of any
+kind. Users are responsible for checking data privacy, model assumptions,
+statistical suitability, external validation evidence, and institutional
+requirements before using outputs for reports, assessment decisions, placement,
+certification, employment, or other high-stakes purposes.
+
+Do not imply that the project authors, external package authors, or referenced
+software projects endorse your analysis, deployment, product, service, or
+publication unless you have separate written permission.
+
+## 日本語の案内
+
+このアプリはMITライセンスで提供し、研究・教育・業務・商用での利用を許可します。
+データの取扱い、分析の適用判断、結果の解釈・利用、およびそれに基づく判断は利用者の責任です。
+アプリと文書は無保証で提供されます。再配布時は著作権表示とライセンス表示を保持してください。
+第三者の構成要素にはそれぞれのライセンスが適用されます。
+MITライセンスの全文は[LICENSE](LICENSE)を参照してください。

mfrmpy-0.1.0/PKG-INFO

@@ -0,0 +1,289 @@
+Metadata-Version: 2.5
+Name: mfrmpy
+Version: 0.1.0
+Summary: Many-facet Rasch analysis and balanced generalizability studies
+Project-URL: Homepage, https://github.com/Ryuya-dot-com/MFRM_Python_Application
+Project-URL: Documentation, https://github.com/Ryuya-dot-com/MFRM_Python_Application/blob/main/docs/python_library.md
+Project-URL: Issues, https://github.com/Ryuya-dot-com/MFRM_Python_Application/issues
+Author: Ryuya Komuro
+License-Expression: MIT
+License-File: LICENSE
+License-File: LICENSE_NOTICE.md
+Keywords: MFRM,Rasch,generalizability,psychometrics,rating
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=3.0
+Requires-Dist: pyarrow>=16.0
+Requires-Dist: scipy>=1.10
+Provides-Extra: figures
+Requires-Dist: matplotlib>=3.8; extra == 'figures'
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# mfrmpy: Many-facet Rasch analysis in Python
+
+`mfrmpy` brings the supported MFRM Desktop calculations to Python scripts and
+notebooks. It uses the same Python engine as the existing MFRM Web and desktop
+applications. It does not require R, FACETS, Streamlit or Tkinter for analysis.
+
+Version **0.1.0 is the first stable library release**. Available analyses are RSM/PCM with JMLE
+or fixed-population-SD MML, diagnostics, conditional bias, selected structural
+intervals, a separate joint-interaction model, and balanced observed-score G/D
+studies. Numerical eligibility checks and interpretation limits remain in
+force. Availability on PyPI is not statistical validation or certification.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+python -m pip install mfrmpy
+```
+
+For Matplotlib figures and offline HTML reports:
+
+```bash
+python -m pip install 'mfrmpy[figures]'
+```
+
+To upgrade an earlier installation, including an alpha release:
+
+```bash
+python -m pip install --upgrade mfrmpy
+```
+
+Python 3.11 and 3.12 are the initial validation targets. Core dependencies are
+NumPy >=1.26, pandas >=3.0, SciPy >=1.10 and PyArrow >=16.0. pandas 3 and
+PyArrow preserve the string storage and missing-value types recorded in Web
+and desktop `.mfrm` projects, including their content fingerprints. This
+distribution provides a library, not the
+standalone desktop executable or the Web app launcher. Those applications
+remain available from the
+[application repository](https://github.com/Ryuya-dot-com/MFRM_Python_Application).
+
+## First analysis
+
+Ratings must be in long form: one row per observed rating, with separate
+person, facet and score columns. Specify the full intended integer rating
+range, even when an endpoint is absent from the observations. Missing ratings
+are not zero scores. The bundled example is synthetic.
+
+```python
+import mfrmpy
+
+data = mfrmpy.load_example()
+analysis = mfrmpy.analyze(
+    data,
+    person_col="Person",
+    facet_cols=["Rater", "Task", "Criterion"],
+    score_col="Score",
+    rating_min=0,
+    rating_max=5,
+    model="RSM",
+    method="JMLE",
+)
+
+for title, frame, note in mfrmpy.tables(analysis):
+    print(title)
+    print(frame.head())
+    print(note)
+
+mfrmpy.save_project("writing.mfrm", analysis)
+restored = mfrmpy.load_project("writing.mfrm")  # no refitting
+```
+
+Use `pandas.read_csv("ratings.csv", dtype={"Person": str, "Rater": str})`
+for your own data, adjusting the ID columns as needed. Explicit string types
+preserve leading zeroes. The input/design audit remains part of the returned
+analysis and tables; inspect it before interpreting estimates.
+
+## Models and supplementary requests
+
+`analyze` is the shared application service, not a second implementation of
+the estimators. It returns a retained-analysis dictionary and does not display
+an interface. Its MFRM settings are:
+
+| Setting | Meaning / default |
+|---|---|
+| `person_col`, `facet_cols`, `score_col` | Required column names; `facet_cols` is a list |
+| `rating_min`, `rating_max` | Required integer rubric endpoints, minimum < maximum |
+| `model`, `method` | `"RSM"` / `"PCM"`; `"JMLE"` / `"MML"`; defaults RSM and JMLE |
+| `step_facet` | Required for PCM; one selected facet with separate step structures |
+| `maxit`, `reltol` | Maximum iterations (400) and stopping tolerance (1e-6) |
+| `quad_points`, `population_prior_sd` | Fixed-SD MML quadrature count (15) and normal population SD (1.0) |
+| `anchors`, `group_anchors` | Fixed-level / group-mean anchor records under the existing identification rules |
+| `compute_pca` | Optional residual diagnostics; default `False` |
+| `umean`, `uscale` | Reporting origin (0) and positive scale multiplier (1); canonical logits are retained |
+| `progress` | Optional callback receiving phase names, not percentages |
+
+Keep `keep_original=True`, `estimate_population_sd=False` and `mml_engine="EM"`.
+Other choices, bounded GPCM and latent regression are outside this initial
+public interface. A numerical termination flag alone is not evidence that
+inference is valid; the returned output qualifications also matter.
+
+Example requests, supplied **when fitting**, are:
+
+```python
+analysis = mfrmpy.analyze(
+    data,
+    person_col="Person",
+    facet_cols=["Rater", "Task", "Criterion"],
+    score_col="Score",
+    rating_min=0,
+    rating_max=5,
+    model="PCM",
+    step_facet="Criterion",
+    method="MML",
+    population_prior_sd=1.0,
+    bias_requests=[{"facet_a": "Rater", "facet_b": "Task"}],
+    interval_requests=[{"facet": "Rater", "difference": ["R1", "R2"], "level": 0.95}],
+    joint_settings={"facet_a": "Rater", "facet_b": "Task"},
+)
+```
+
+Replace the contrast labels with levels that actually occur in your data.
+Conditional bias holds the main calibration fixed and does not establish
+statistical significance or fairness. Joint interaction fits a **separate**
+fixed-N(0,1), unit-weight model and retains its result separately. Selected
+structural intervals require fixed-SD, unit-weight RSM/PCM and suitable
+identification, termination, boundaries, information and quadrature checks.
+They are pointwise asymptotic intervals, with no finite-sample coverage
+guarantee. Holm adjustment of joint tests does not make intervals simultaneous.
+
+Unavailable/failed interval or joint requests remain recorded with a reason;
+they do not silently erase a completed baseline fit. For details, see the
+[analysis scope](https://github.com/Ryuya-dot-com/MFRM_Python_Application/blob/main/docs/analysis_scope.md).
+
+## G study and D study without an MFRM fit
+
+These analyze observed scores in a complete, balanced design with one or two
+random facets, at least two levels of each factor and one observation per cell.
+The score need not be an integer for G/D analysis. For example:
+
+```python
+import pandas as pd
+
+ratings = pd.DataFrame([
+    {"Person": str(p), "Rater": str(r), "Task": str(t),
+     "Score": 0.4*p + 0.3*r + 0.2*t + 0.1*((p+r+t) % 3)}
+    for p in range(8) for r in range(3) for t in range(2)
+])
+gd_analysis = mfrmpy.analyze(
+    ratings,
+    workflow="gd",
+    gd_settings={
+        "object_facet": "Person",
+        "random_facets": ["Rater", "Task"],
+        "score_col": "Score",
+        "target_population": "Comparable persons, raters and tasks",
+        "selected_plan": {"Rater": 4, "Task": 2},
+    },
+)
+for title, frame, note in mfrmpy.tables(gd_analysis):
+    print(title, frame, note, sep="\n")
+```
+
+Unsupported designs return an unavailable result with a reason. G is for
+relative decisions and Phi for absolute decisions. These are not MFRM person
+reliability. G/Phi intervals and multivariate G-theory are unavailable. A fixed
+conditioning facet can be specified through `gd_settings["fixed_condition"]`
+under the existing desktop rules; it does not add another random facet.
+
+## Results, plots and saved projects
+
+The stable public surface is the names in `mfrmpy.__all__`. The bundled
+`mfrm_app` modules are implementation details, including experimental methods
+outside the supported scope. Do not rely on their private functions or treat
+their presence as a supported public API.
+
+| Function | Result |
+|---|---|
+| `analyze(data, **settings)` | Retained analysis dictionary, including inputs, settings, identities and qualification |
+| `tables(analysis)` | List of `(title, pandas.DataFrame, note)` tuples, with current output restrictions applied |
+| `load_example()` | A new DataFrame containing the bundled synthetic writing example |
+| `save_project(path, analysis)` | Atomically write a validated `.mfrm` archive |
+| `load_project(path)` | Validate and restore an archive without refitting; malformed archives raise `ProjectError` |
+| `plot(analysis, kind="wright", **options)` | Matplotlib Figure; requires `figures` extra |
+| `report_html(analysis, **options)` | Standalone HTML string; requires `figures` extra |
+
+`analysis["result"]` and `analysis["diagnostics"]` retain raw MFRM output;
+`analysis["gd_analysis"]` retains G/D results. The nested implementation
+schema is internal; use `.mfrm` files to retain analyses across sessions rather
+than serializing or modifying this dictionary yourself. For reporting, use `tables`, keeping
+the notes and `Use`/`Reason` information. A blank interval or SE is unavailable,
+not zero. General MML tables, person-score uncertainty and automatic equivalence
+claims retain their existing inferential restrictions.
+
+With the optional figures dependency installed:
+
+```python
+from pathlib import Path
+
+step_facet = analysis["fit_settings"].get("step_facet")
+level = str(data[step_facet].iloc[0]) if step_facet else None
+figure = mfrmpy.plot(analysis, "wright", level=level)
+figure.savefig("wright.png", dpi=300)
+Path("report.html").write_text(mfrmpy.report_html(analysis), encoding="utf-8")
+```
+
+Other figure kinds include `"pathway"`, `"category"`, `"bias"`, `"interval"`,
+`"joint"`, `"gd"` and `"pca"` when the required results are present. PCM Wright
+maps and category curves require `level` (a step-facet level); supplementary requests use their
+zero-based `index`. Retained results are reused; plotting and reopening must
+not recompute estimation. Unsupported requests can produce a reason-bearing
+figure rather than a numerical result.
+
+Saved `.mfrm` projects use the existing desktop/Web archive format. New source
+or dependency versions can cause current qualification checks to withhold old
+interval output without altering the archived estimates. Record
+`mfrmpy.__version__` and `analysis["source"]` when reporting an analysis.
+The package API version and the shared engine version are distinct.
+
+## API and compatibility policy
+
+The supported API is the exported functions documented above, `ProjectError`
+and `__version__`. `analyze` accepts the settings and workflows documented in
+this guide. `ProjectError` is a `ValueError` subclass for invalid/unsupported
+project contents; filesystem errors such as a missing file remain normal
+Python I/O errors.
+
+Within **0.1.x**, patch releases preserve these public names, documented
+arguments and return types. Additive options and bug fixes are allowed. Before
+1.0, an incompatible public API change requires a new minor release, such as
+0.2.0, with migration instructions in the changelog. Private `mfrm_app` helpers,
+nested raw-result fields, table display order and exact wording are outside
+this compatibility promise. Keep interpretation notes with exported results.
+
+Version 0.1.0 reads the supported schema-1 RSM/JMLE and schema-2 `.mfrm` archives,
+including those written by 0.1.0a2 and the corresponding Web/desktop workflows.
+The 0.1.x series will retain read compatibility with these supported archives;
+malformed or unsupported records are rejected without refitting. Future archive
+changes will be documented, and older applications may not read newer formats.
+
+Numerical bug fixes or updated qualification rules can change reported results
+or withhold an output; such changes belong in the changelog. For reproducible
+research, retain the original `.mfrm` file and record the package, source and
+dependency versions. The first stable release uses the same calculation and
+archive code as 0.1.0a2, with the same analysis scope and interpretation limits.
+
+## Privacy, license and citation
+
+Calculations run locally. Saved projects and exported reports can retain
+ratings and person/rater IDs; store and share them according to your research
+requirements. Use synthetic data for bug reports.
+
+MIT licensed; see
+[LICENSE](https://github.com/Ryuya-dot-com/MFRM_Python_Application/blob/main/LICENSE)
+and the
+[responsible-use notice](https://github.com/Ryuya-dot-com/MFRM_Python_Application/blob/main/LICENSE_NOTICE.md).
+Cite Ryuya Komuro, *mfrmpy*, the installed package version, and
+https://github.com/Ryuya-dot-com/MFRM_Python_Application, together with the
+statistical methods actually used. Source and issue reporting are maintained
+in that repository.

mfrmpy-0.1.0/docs/analysis_scope.md

@@ -0,0 +1,158 @@
+# Analyses, interpretation and reporting limits
+
+[Start here](../README.md) · [Windows guide](desktop_user_guide.en.md) · [日本語の操作・結果の読み方](desktop_user_guide.ja.md#分析を選ぶ)
+
+Use this page to choose an analysis and understand what its results can support.
+It describes the Web application and the desktop preview documented in this
+source branch. The desktop preview includes RSM/PCM, bias diagnostics, selected
+intervals, joint interactions and G/D studies; it is not yet a general desktop
+release. The published Web release and this desktop preview do not have
+identical controls or export formats.
+
+## Choose the analysis for your question
+
+| Question | Analysis | What to distinguish |
+|---|---|---|
+| How do person measures, rater severity and task difficulty compare? | Many-facet RSM or PCM | RSM shares category steps. PCM allows separate steps for levels of the chosen step facet. A main rater effect is not a rater-by-task interaction. |
+| Does a particular combination of facet levels differ from the main-effects pattern? | Conditional bias diagnostics | These hold the original calibration fixed. They identify patterns to investigate, without confirming the presence or absence of bias. |
+| What is the uncertainty in a facet level or a planned difference? | Specified structural intervals for fixed-SD MML | Only targets passing the checks receive intervals. A difference uses the full covariance, not the sum of marginal SEs. |
+| What happens when an interaction is fitted together with main effects and steps? | Desktop joint interaction analysis | This refits a separate model. It does not turn the fixed-calibration diagnostic into a joint test. |
+| How would numbers of raters or tasks affect score reliability? | G study and D study | These use observed scores and a declared random-facet design, not the MFRM logit scale. |
+
+The Web interface also provides advanced workflows such as bounded GPCM,
+latent regression, anchors and linking review, residual PCA, prediction and
+simulation. Their availability does not establish that every displayed
+statistic can support inference. Read the explanation for the selected output.
+
+## Estimation and standard errors
+
+JMLE jointly estimates person and facet parameters. Desktop MML uses EM with
+a fixed normal population SD; the SD is a setting, not an estimated result.
+The Web interface offers additional MML controls, including optional population
+SD estimation, whose uncertainty and model-ranking uses remain unavailable.
+
+A standard error must be interpreted for its stated target and method.
+Conditional-information errors hold other parameters fixed. Structural
+observed-information errors use a covariance calculation for the model
+parameters. An MML person's EAP posterior SD describes a posterior distribution
+with calibration fixed; it is not the ML standard error of a structural effect.
+Do not treat these quantities as interchangeable because each is labelled SE.
+
+The application does not support inferential use of general MML tables,
+Person-score uncertainty, estimated population-SD uncertainty or automatic
+equivalence conclusions. Selected structural intervals have the separate,
+limited scope below. An available selected interval does not remove the
+restrictions on other outputs.
+
+## Specified structural intervals
+
+For supported unit-weight, fixed-SD RSM/PCM analyses, this output provides
+pointwise asymptotic normal intervals for selected levels of a non-person
+facet and a prespecified difference. It uses the full structural covariance.
+
+The calculation checks termination, identification, parameter boundaries,
+observed information and sensitivity to quadrature settings. These checks
+assess numerical suitability. They do not prove that the response model fits
+the population, give a strict quadrature error bound, or guarantee
+finite-sample coverage.
+
+The approximation assumes the specified response model and fixed normal
+population, independent persons, ignorable assignment/missingness, an
+identified interior parameter and growing information. It does not provide
+simultaneous intervals, Person-score intervals or a test of equivalence.
+
+The [English](fixed_sd_quadrature_check.en.md) and
+[Japanese](fixed_sd_quadrature_check.ja.md) Web guides explain selecting,
+saving and rechecking these intervals. In Desktop, register the requests in
+**Settings → Bias / intervals** before running the analysis.
+
+## Bias diagnostics and joint interactions
+
+Conditional bias diagnostics describe cells with the original calibration
+held fixed. Sparse cells, extreme scores and disconnected rating designs can
+limit what can be estimated or compared. Displayed diagnostic values do not
+establish statistical significance, absence of bias or assessment fairness.
+
+The desktop joint-interaction option fits main effects, steps and one selected
+structural-facet interaction together in a separate RSM/PCM model. It uses
+unit weights and a normal person population fixed at mean 0 and SD 1.
+Eligible requested cells and prespecified contrasts receive pointwise
+approximate Wald intervals and p values. Holm adjustment applies to the
+recorded family of requested tests; it does not make the intervals simultaneous.
+
+This model assumes independent persons, the stated response/population model,
+ignorable assignment/missingness and an identified interior solution with
+growing information. Numerical checks are not a finite-sample error-rate
+guarantee. An interaction is evidence about the fitted model, not a verdict
+about fairness or a person. The original main-effects results remain separate.
+
+## G studies and D studies
+
+The supported design is completely crossed and balanced, with one or two
+random facets besides the object of measurement, at least two levels of each
+factor, one observation per cell and unit observation weights. Missing or
+repeated cells and unsupported designs produce a reason rather than an
+unsupported coefficient.
+
+G describes relative decisions and Phi describes absolute decisions. The D
+study changes planned numbers of observations under the stated design and
+population assumptions. Negative estimated variance components are shown
+alongside the zero-clipped components used for the coefficients. A coefficient
+alone does not establish an acceptable assessment or validate a future design.
+
+The desktop G/D entry uses the original observed scores without requiring an
+MFRM fit. Multivariate G-theory and uncertainty intervals for G/Phi are not
+implemented. These restrictions also apply when G/D is requested alongside MFRM.
+
+## When a result cannot support inference
+
+Read the message for the particular table or figure.
+
+- **Input or design problem:** correct the indicated column mapping, score
+  range, missingness or design problem. For example, unrelated rating groups
+  may lack a common scale. Keep the original data and document any change.
+- **Numerical or boundary problem:** review the stopping reason, identification
+  and extreme scores. A finite displayed estimate or an optimizer stopping
+  flag does not establish valid inference.
+- **Unsupported uncertainty method or use:** the application has not
+  established that use for this output. Repeatedly changing the data or
+  rerunning the same settings does not resolve that limitation.
+- **Changed settings or a saved result from another implementation:** check
+  which analysis the displayed output belongs to. Reopened results retain the
+  saved values but are checked against current output-specific rules.
+
+A blank SE or interval means it is unavailable, not zero. Do not infer equality,
+absence of bias or a reliable ranking from missing uncertainty or a
+non-significant result. Use an eligible dedicated output only within its
+stated scope.
+
+## Comparing programs and reporting results
+
+Match the model, data, weights, constraints, population distribution, scoring
+method and numerical settings before comparing software.
+
+In particular, this application's non-person PTMEA/PtMeaCorr correlates
+observed scores with person measures. FACETS PtMea uses the signed sum of
+measures for each observation. They are different diagnostics. The application's
+RSM/PCM fit ZSTD follows a FACETS-style fourth-moment/Wilson–Hilferty convention
+with an absolute cap of 9; the GPCM adaptation is approximate. Agreement in one
+diagnostic does not establish equivalence of the programs.
+
+AIC/AICc/BIC, model-choice LR values and automatic model recommendations remain
+restricted to technical review. Residual PCA is a diagnostic requiring attention
+to sparse observations, overlap and stability, not an automatic dimensionality
+decision. Simulations describe their specified data-generating conditions;
+they do not validate a different empirical design.
+
+When reporting, retain the model, estimator, constraints, scoring rubric,
+population-SD treatment, analysis version, uncertainty method and relevant
+limitations. Preserve captions and notes with exported figures and tables.
+Software citation does not replace citations for the statistical methods.
+
+Implementation references for technical readers:
+[output rules](../mfrm_app/output_qualification.py),
+[structural intervals](../mfrm_app/structural_intervals.py),
+[joint interactions](../mfrm_app/joint_interaction.py),
+[G/D calculations](../mfrm_app/generalizability.py).
+The [FACETS comparison](../validation/FACETS_WINDOWS_DESKTOP_REVIEW_20261029.md)
+states the conditions and limits of its numerical checks.