factominer 0.1.0.dev0__tar.gz

factominer-0.1.0.dev0/.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Venvs
+.venv/
+.venv-factominer/
+venv/
+env/
+
+# Testing / type-checking caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Docs build
+docs/_build/
+
+# OS / editor
+.DS_Store
+*.swp
+
+# Local R fixtures generated at build time (committed when stable)
+.r-fixture-stage/
+
+# Jupyter outputs
+.ipynb_checkpoints/
+
+# Local elves state
+.elves-session.json

factominer-0.1.0.dev0/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to FactoMinePy are tracked here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) once
+out of pre-release.
+
+## [Unreleased]
+
+### Added
+
+- Full FactoMineR 2.14 schema parity for `dimdesc` / `catdes` / `condes`
+  (`n` column on quanti tables; `Cla/Mod` / `Mod/Cla` / `Global` /
+  hypergeometric `v.test` on catdes category; `Eta2` / `P-value` on
+  catdes quanti.var; `sd in category` / `Overall sd` / `n` on catdes
+  per-level quanti; `Estimate` / `p.value` on condes category).
+- PCA now exposes `quali.sup$eta2` (per-variable, not per-category).
+- PCA / CA / MCA `res$eig` now carries all eigenvalues (only the
+  coord / cos² / contrib blocks are truncated to `ncp`); `res$svd$vs`
+  keeps the full singular spectrum.
+- MCA `res$eig` truncated to `total_cat - q_vars` to match R's
+  "useful" axis count.
+- HCPC `data_clust` holds the original input X + `clust` column (was:
+  PC coordinates); `desc_var` populated via the parity-verified
+  `catdes`; `desc_axes` via `condes` per axis.
+- CI: `rpy2-parity` workflow installs FactoMineR 2.14 from CRAN, runs
+  the parity suite against freshly generated fixtures, and uploads the
+  fresh fixtures + drift diff as artifacts. Triggerable on-demand via
+  `workflow_dispatch`; runs weekly on Monday cron.
+- README: experimental-use-with-caution callout, known limitations
+  section, tightened parity-tolerance documentation.
+- Open-source meta files (this CHANGELOG, CONTRIBUTING.md, CITATION.cff,
+  SECURITY.md, issue + PR templates).
+
+### Fixed
+
+- MCA `var$eta2` and `var$v.test`: dropped erroneous `/lambda_k` and
+  `/sqrt(lambda_k)` factors. R FactoMineR's MCA `var$coord` is the
+  standard category coordinate ψ_c, so:
+  - `eta²(v,k) = sum_c n_c * ψ_c² / N`
+  - `v.test(c,k) = ψ_c * sqrt(n_c (N-1) / (N - n_c))`
+  Output now matches R to 1e-9 on the tea fixture (previously off by
+  ~6.7× on eta² and ~2.6× on v.test).
+- Sphinx build: enabled `myst-nb` so example notebooks under
+  `docs/examples/` actually render. (Listing both `myst_parser` and
+  `myst_nb` in `extensions` double-invokes `setup_sphinx` and crashes
+  myst-parser 5.1.0; only `myst_nb` is loaded now.)
+- `docs/api/datasets.md`: relative PROVENANCE.md link rewritten to an
+  absolute GitHub URL so it resolves outside the repo tree.
+
+### Changed
+
+- `tools/refresh_r_fixtures.R` adds two richer fixtures
+  (`condes/tea_age.json`, `dimdesc/pca_decathlon_proba50.json`) that
+  exercise the populated-quali + populated-category branches of the
+  desc functions.
+- Test tolerances tightened across the suite:
+  - eigenvalues: `1e-8 → 1e-10`
+  - coord / cos² / cor / eta²: `1e-6 → 1e-9`
+  - contrib: `1e-6 → 1e-8`
+  - v.test: still 1e-6 (limited by chained qnorm / hypergeometric)
+  - p-values: `1e-5` relative (new — previously untested at column level)
+
+## [0.1.0.dev0] — 2026-05-16
+
+Initial port: PCA, CA, MCA, HCPC, dimdesc / catdes / condes with R-parity
+tests. FAMD / MFA / HMFA / DMFA / GPA importable as `NotImplementedError`
+stubs.
+
+[Unreleased]: https://github.com/aigorahub/FactoMinePy/compare/v0.1.0.dev0...HEAD
+[0.1.0.dev0]: https://github.com/aigorahub/FactoMinePy/releases/tag/v0.1.0.dev0

factominer-0.1.0.dev0/CITATION.cff

@@ -0,0 +1,62 @@
+cff-version: 1.2.0
+title: FactoMinePy
+message: >-
+  If you use FactoMinePy in published work, please cite both this software
+  package and the original R FactoMineR, which it ports.
+type: software
+authors:
+  - name: Aigora
+    website: https://aigora.com
+repository-code: https://github.com/aigorahub/FactoMinePy
+url: https://github.com/aigorahub/FactoMinePy
+abstract: >-
+  A Python port of the R package FactoMineR for multivariate exploratory data
+  analysis (PCA, CA, MCA, HCPC, dimdesc / catdes / condes). Reimplemented from
+  primitives on NumPy / SciPy / Pandas; validated for byte-identical fixture
+  output and column-by-column schema parity against R FactoMineR 2.14.
+keywords:
+  - factor-analysis
+  - PCA
+  - CA
+  - MCA
+  - HCPC
+  - multivariate-analysis
+  - exploratory-data-analysis
+  - python
+  - factominer
+license: MIT
+preferred-citation:
+  type: software
+  title: FactoMinePy
+  authors:
+    - name: Aigora
+  url: https://github.com/aigorahub/FactoMinePy
+references:
+  - type: software
+    title: FactoMineR
+    scope: The reference implementation this package ports.
+    authors:
+      - family-names: Lê
+        given-names: Sébastien
+      - family-names: Josse
+        given-names: Julie
+      - family-names: Husson
+        given-names: François
+    url: https://cran.r-project.org/package=FactoMineR
+    repository-code: https://github.com/husson/FactoMineR
+  - type: article
+    title: "FactoMineR: An R Package for Multivariate Analysis"
+    authors:
+      - family-names: Lê
+        given-names: Sébastien
+      - family-names: Josse
+        given-names: Julie
+      - family-names: Husson
+        given-names: François
+    journal: Journal of Statistical Software
+    year: 2008
+    volume: 25
+    issue: 1
+    start: 1
+    end: 18
+    doi: 10.18637/jss.v025.i01

factominer-0.1.0.dev0/CONTRIBUTING.md

@@ -0,0 +1,117 @@
+# Contributing to FactoMinePy
+
+Thanks for your interest. This is an early-alpha port of the R package
+[FactoMineR](https://cran.r-project.org/package=FactoMineR) to Python. Below is
+how to get a local dev environment going, what the parity bar is, and how to
+get a change merged.
+
+## Quick start
+
+```bash
+git clone https://github.com/aigorahub/FactoMinePy.git
+cd FactoMinePy
+python3.12 -m venv .venv
+.venv/bin/pip install -e '.[dev]'
+.venv/bin/pytest -q
+```
+
+Python **3.10 or newer** is required; CI runs on 3.11 and local development is
+exercised on 3.12.
+
+## What this project's parity bar is
+
+Every method in the "live" column of the README's status table is validated
+against R FactoMineR (currently 2.14 on CRAN) using committed JSON fixtures.
+The committed fixtures must be byte-identical to what live R FactoMineR
+produces on a clean Linux runner with the current CRAN release.
+
+When you change anything that could affect numerical output:
+
+1. Run the full test suite locally: `.venv/bin/pytest -q`.
+2. If you have R + FactoMineR installed locally, regenerate fixtures with
+   `Rscript tools/refresh_r_fixtures.R` and confirm the tests still pass
+   against them. If you don't have R locally, the `rpy2-parity` GitHub
+   Actions workflow does the same on a runner with R 4.6 + FactoMineR 2.14
+   from CRAN. Trigger it manually from the Actions tab via
+   `workflow_dispatch`, or wait for the weekly cron.
+3. Don't loosen tolerances to make tests pass. Investigate the divergence
+   instead — the current tolerances are deliberate (1e-10 on eigenvalues,
+   1e-9 on coord/cos²/cor/eta², 1e-8 on contrib, 1e-6 on v.test, 1e-5
+   relative on p-values).
+
+## Style and lint
+
+- Source is formatted to ruff defaults; `ruff check factominer tests` must be
+  clean before pushing.
+- We don't enforce ruff *format* yet — match the surrounding style.
+- Type annotations are encouraged but not strictly required (mypy is
+  advisory in CI). New public APIs should be typed.
+- Docstrings: short, in the style of the existing modules
+  (`factominer/desc/catdes.py` is a good model). Reference the R FactoMineR
+  source path that the implementation tracks when the behaviour is
+  non-obvious.
+
+## Where to look in the source
+
+- `factominer/pca.py`, `ca.py`, `mca.py` — the three core dimensionality-
+  reduction methods. Each one builds row + column blocks plus supplementary
+  blocks and stashes the input frames in `res.call` so downstream methods
+  (dimdesc / catdes / condes / HCPC) can recompute against the original
+  variables.
+- `factominer/desc/` — `dimdesc.py` delegates to `condes.py`; `catdes.py`
+  is the heavy one (test_chi2, category with Cla/Mod/Mod/Cla/Global +
+  hypergeometric, quanti.var with Eta²/P-value, per-level quanti).
+- `factominer/hcpc.py` — Ward + k-means consolidation. `data_clust` holds
+  the original X + `clust`, and `desc_var` delegates to `catdes`.
+- `factominer/_svd.py`, `_sign.py`, `_scaling.py` — shared primitives.
+- `tools/refresh_r_fixtures.R` — the single source of truth for what R
+  output we compare against. Edit this script (not the JSON files
+  directly) if you need a new fixture.
+
+## Opening a pull request
+
+1. Branch from `main`. The history is rebased-merged and reasonably linear.
+2. Keep the change focused. If you're rewriting a method to fix one
+   parity bug, don't also reformat the file.
+3. Reference the R FactoMineR source line numbers (in
+   `husson/FactoMineR/R/<file>.r`) when claiming a formula matches R.
+4. Make sure the PR description has a "Test plan" checklist. The default
+   PR template will populate one.
+5. CI gates merge on `lint-and-test` and CodeQL. `rpy2-parity` is
+   non-blocking on PRs (it's expensive and depends on R availability);
+   trigger it manually if your change is numerical.
+
+## Scope
+
+Out of scope without discussion:
+
+- Wholesale rewrites of the parity-test layout. The current fixture
+  harness is what lets us regenerate against any CRAN FactoMineR release.
+- Replacing pandas/NumPy/SciPy with another stack. The point of the port
+  is *no* exotic runtime dependencies.
+- A drop-in `from FactoMineR import *` Python API. We deliberately follow
+  Python conventions (snake_case args, 0-based indices, pandas DataFrames
+  with documented column names).
+
+In scope and welcome:
+
+- Implementing the deferred methods (`FAMD`, `MFA`, `HMFA`, `DMFA`,
+  `GPA`). Each has a stub in `factominer/_deferred.py`.
+- New parity fixtures exercising untested R FactoMineR options (row
+  weights, missing values, `method="burt"` MCA, etc.).
+- Plotly backend (currently stubs in `factominer/plot/`).
+- Documentation fixes, example notebooks, migrating-from-R additions.
+
+## Reporting bugs
+
+File a GitHub issue with:
+
+- A minimal reproducer (a script + the dataset, or one of the bundled
+  loaders).
+- The R FactoMineR call that produces the expected output, if you have
+  one.
+- The Python output you got and the R output you expected.
+
+If your reproducer needs R to demonstrate the discrepancy, please include
+the R version (`R --version | head -1`) and FactoMineR version
+(`packageVersion("FactoMineR")`).

factominer-0.1.0.dev0/LICENSE

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

factominer-0.1.0.dev0/NOTICE.md

@@ -0,0 +1,45 @@
+# Notices and attributions
+
+FactoMinePy is a from-primitives Python reimplementation of R FactoMineR. It
+does **not** redistribute any R or C source code from FactoMineR. The runtime
+package is MIT-licensed (see [LICENSE](LICENSE)).
+
+## R FactoMineR
+
+R FactoMineR is GPL-licensed and authored by:
+
+> Sébastien Lê, Julie Josse, François Husson — *FactoMineR: An R Package for
+> Multivariate Analysis* — Journal of Statistical Software 25(1), 2008 —
+> doi:[10.18637/jss.v025.i01](https://doi.org/10.18637/jss.v025.i01) —
+> CRAN: https://cran.r-project.org/package=FactoMineR
+
+The Python source in this repository implements the same statistical methods
+following the published documentation and the R source code at
+https://github.com/husson/FactoMineR. Each implementation file references the
+specific R function it tracks. The Python re-implementation is original work
+and is offered under the MIT license; it does not relicense R FactoMineR.
+
+## Bundled datasets
+
+The CSV files under [factominer/datasets/data/](factominer/datasets/data/)
+are re-extracted from the data exports shipped with R FactoMineR for the
+purpose of validating numerical parity. The values themselves are facts
+(athletics results, survey responses) and are not subject to copyright. The
+specific tabulations distributed with R FactoMineR carry the GPL alongside
+the rest of the R package; we keep these tabulations bundled solely so the
+parity tests are reproducible without a working R installation.
+
+If you need a strictly GPL-free data bundle (for example, if you are
+redistributing a derivative of this package in a non-GPL-compatible
+context), re-derive each dataset from its primary source as documented in
+[factominer/datasets/data/PROVENANCE.md](factominer/datasets/data/PROVENANCE.md).
+
+## Inspiration
+
+API shape and visualization patterns were informed by:
+
+- [`factoextra`](https://rpkgs.datanovia.com/factoextra/) — the canonical
+  ggplot2 visualization companion for FactoMineR.
+- [`prince`](https://github.com/MaxHalford/prince) and
+  [`scientisttools`](https://pypi.org/project/scientisttools/) — earlier
+  Python ports that informed the API shape (no code copied).

factominer-0.1.0.dev0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: factominer
+Version: 0.1.0.dev0
+Summary: FactoMineR-compatible multivariate exploratory data analysis for Python
+Project-URL: Homepage, https://github.com/aigorahub/FactoMinePy
+Project-URL: Issues, https://github.com/aigorahub/FactoMinePy/issues
+Author-email: Aigora <hello@aigora.com>
+License: MIT
+License-File: LICENSE
+License-File: NOTICE.md
+Keywords: ca,factominer,factor analysis,famd,hcpc,mca,mfa,multivariate,pca
+Classifier: Development Status :: 3 - Alpha
+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: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Requires-Dist: matplotlib>=3.9
+Requires-Dist: numpy>=2.0
+Requires-Dist: pandas>=2.2
+Requires-Dist: scipy>=1.13
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: jupyter; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: myst-nb; extra == 'dev'
+Requires-Dist: myst-parser; extra == 'dev'
+Requires-Dist: nbclient; extra == 'dev'
+Requires-Dist: nbformat; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: sphinx>=7; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: plotly
+Requires-Dist: plotly>=5.20; extra == 'plotly'
+Provides-Extra: rpy2
+Requires-Dist: rpy2>=3.5; extra == 'rpy2'
+Description-Content-Type: text/markdown
+
+# FactoMinePy
+
+[![CI](https://github.com/aigorahub/FactoMinePy/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/aigorahub/FactoMinePy/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+[![Status](https://img.shields.io/badge/status-alpha-orange)](#status)
+
+> ⚠️ **Experimental — use with caution.** This is an independent Python port of the R package [FactoMineR](https://cran.r-project.org/package=FactoMineR). It is **not** affiliated with or endorsed by the authors of FactoMineR. The port is in early development; APIs may change, edge cases may differ from R, and several FactoMineR methods are not yet implemented (see status table below). For production work or published research, treat results as preliminary and cross-check against the original R package.
+
+A from-primitives reimplementation in pure NumPy/SciPy/Pandas of the R package [FactoMineR](https://cran.r-project.org/package=FactoMineR) for multivariate exploratory data analysis (PCA, CA, MCA, HCPC, dimdesc/catdes/condes).
+
+This package is **not** a wrapper around R; every method is reimplemented from the published FactoMineR documentation and R source, then validated numerically against R FactoMineR (currently 2.14 on CRAN) via a checked-in fixture harness. R FactoMineR remains the canonical reference implementation; this port aims for byte-identical fixture output and column-by-column schema parity, but is not a drop-in replacement.
+
+## Status
+
+**Early-alpha.** The supported-methods table is the source of truth for what works.
+
+| FactoMineR method | Python equivalent | Live | R-parity verified | Notes |
+| --- | --- | --- | --- | --- |
+| `PCA` | `factominer.PCA` | ✅ | ✅ | active + supplementary individuals, quanti.sup, quali.sup |
+| `CA` | `factominer.CA` | ✅ | ✅ | symmetric biplot, supplementary rows/columns |
+| `MCA` | `factominer.MCA` | ✅ | ✅ | indicator matrix; Burt option |
+| `HCPC` | `factominer.HCPC` | ✅ | ✅ | hierarchical clustering on PCA/CA/MCA, k-means consolidation |
+| `dimdesc` | `factominer.dimdesc` | ✅ | ✅ | quantitative + categorical description per axis |
+| `catdes` | `factominer.catdes` | ✅ | ✅ | `Cla/Mod`, `Mod/Cla`, `Global`, hypergeometric v-test; `quanti_var` Eta²; per-level `quanti` with `sd in category` / `Overall sd` / `n` |
+| `condes` | `factominer.condes` | ✅ | ✅ | correlation tests for a continuous target |
+| `plot.PCA / .CA / .MCA / .HCPC` | `factominer.plot.plot()` | ✅ | structural | matplotlib backend; factor maps, biplot, scree, contributions, dendrogram, ellipses, habillage |
+| `FAMD` | `factominer.FAMD` | 🚧 stub | — | Round 2 |
+| `MFA` | `factominer.MFA` | 🚧 stub | — | Round 2 |
+| `HMFA` | `factominer.HMFA` | 🚧 stub | — | Round 2 |
+| `DMFA` | `factominer.DMFA` | 🚧 stub | — | Round 2 |
+| `GPA` | `factominer.GPA` | 🚧 stub | — | Round 2 |
+| Plotly backend | `factominer.plot.plotly_*` | 🚧 stub | — | Round 2 |
+
+Methods marked 🚧 are importable but raise `NotImplementedError("deferred — see docs/plans/factominer-python-port.md §2")` when called. This is by design so downstream code can `from factominer import HMFA` without an `ImportError`.
+
+## Install
+
+```bash
+pip install factominer
+# matplotlib backend ships by default; for the optional plotly backend:
+pip install 'factominer[plotly]'
+```
+
+## Quickstart
+
+```python
+from factominer import PCA, HCPC, dimdesc
+from factominer.datasets import load_decathlon
+
+decathlon = load_decathlon()
+res = PCA(decathlon, scale_unit=True, ncp=5,
+          quanti_sup=["Rank", "Points"],
+          quali_sup=["Competition"])
+
+print(res.summary())
+print(res.eig)             # eigenvalue table (DataFrame)
+print(res.ind.coord)       # individual coordinates
+print(res.var.contrib)     # variable contributions
+
+# Describe each axis
+desc = dimdesc(res, axes=[0, 1])
+print(desc[0]["quanti"])
+
+# Cluster on the principal components
+clust = HCPC(res, nb_clust=3)
+print(clust.data_clust.head())
+
+# Plot
+import matplotlib.pyplot as plt
+from factominer.plot import plot
+fig, ax = plt.subplots(1, 2, figsize=(12, 5))
+plot(res, choix="ind", habillage="Competition", ax=ax[0])
+plot(res, choix="var", ax=ax[1])
+plt.show()
+```
+
+## Migrating from R
+
+See [docs/migrating-from-r.md](docs/migrating-from-r.md) for a side-by-side cheat sheet (R call → Python call → result attribute mapping → semantic differences).
+
+The most important semantic differences:
+
+1. **Argument names use snake_case.** `scale.unit=TRUE` → `scale_unit=True`, `quanti.sup=11:12` → `quanti_sup=[10, 11]` (and column names like `"Rank"` work too).
+2. **Indices are 0-based.** `ind.sup=1:3` (R) → `ind_sup=[0, 1, 2]` (Python).
+3. **Sign convention.** SVD is sign-ambiguous; we apply a deterministic rule (first absolute-max coordinate of each axis is positive). Coordinates may differ from R by a sign; the *interpretation* (clusters, distances, contributions) is identical. See `factominer._sign`.
+4. **Result objects.** `res$eig` (R) → `res.eig` (Python). `res$var$coord` → `res.var.coord`. All result tables are `pandas.DataFrame`.
+5. **Plotting is explicit.** `graph=TRUE` does not exist; you call `factominer.plot.plot(res, ...)` yourself. No magic on `print(res)`.
+
+## Numerical fidelity
+
+For every live method, the package ships parity tests that assert column-by-column equivalence against R FactoMineR 2.14 (current CRAN) within tight tolerances:
+
+- Eigenvalues to **1e-10** absolute
+- Coordinates / cos² / correlations / eta² to **1e-9** after sign alignment
+- Contributions to **1e-8**
+- v-tests to **1e-6**
+- p-values to **1e-5** relative
+- HCPC partitions to ARI ≥ 0.999 (k-means consolidation can swap a couple of individuals)
+
+Fixtures are JSON dumps of R FactoMineR results, generated by `tools/refresh_r_fixtures.R` and committed under `tests/fixtures/r_outputs/`. The Python tests load them without needing R at test time. Every fixture in the repo is byte-identical to what live R FactoMineR 2.14 emits on a Linux GitHub runner with R 4.6.0 (verified by the `rpy2-parity` CI job, which is triggerable on-demand via `workflow_dispatch` and runs on a weekly cron).
+
+To regenerate fixtures locally (requires R + FactoMineR + jsonlite):
+
+```bash
+Rscript tools/refresh_r_fixtures.R
+pytest -q
+```
+
+## Known limitations / use with caution
+
+This port targets the most common FactoMineR API surface and is rigorously validated on the bundled datasets, but the following caveats apply:
+
+- **Several methods are stubs.** `FAMD`, `MFA`, `HMFA`, `DMFA`, `GPA` are importable but raise `NotImplementedError` when called.
+- **Parity is empirical, not exhaustive.** The 83 parity tests cover the active + supplementary blocks for PCA / CA / MCA / HCPC and the full output schemas of dimdesc / catdes / condes on standard fixtures (`decathlon`, `children`, `tea`). Behavior with row weights, missing values, very small samples, or `method="burt"` MCA has not been independently verified.
+- **Sign of axes is arbitrary.** SVD is sign-ambiguous; we apply a deterministic rule that may give the opposite sign from R on a given axis. Distances, clusters, contributions, and cos² are sign-invariant; coordinates may need a flip to align visually with R output.
+- **HCPC partitions can differ by one or two individuals.** K-means consolidation is sensitive to initialization; the adjusted Rand index against R is ≥ 0.999 on the decathlon test fixture but not exactly 1.0.
+- **No plotly backend yet.** Only matplotlib is implemented; the plotly module's functions raise `NotImplementedError`.
+
+For production analyses, journal submissions, or any use where reproducibility against R FactoMineR is load-bearing, cross-check results against the original R package.
+
+## Datasets
+
+Bundled datasets under `factominer.datasets`:
+
+| Loader | Source | Use case |
+| --- | --- | --- |
+| `load_decathlon()` | IAAF 2004 Athens Olympic + Décastar 2004, re-derived from public results | PCA, dimdesc, HCPC |
+| `load_children()` | FactoMineR's `children` (children's worries by socio-educational category) | CA |
+| `load_tea()` | FactoMineR's `tea` (300-person tea-consumption survey) | MCA, catdes |
+| `load_poison()` | FactoMineR's `poison` (food-poisoning outbreak survey) | mixed quantitative + categorical |
+
+See [factominer/datasets/data/PROVENANCE.md](factominer/datasets/data/PROVENANCE.md) for each dataset's origin and licensing notes.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, parity-bar expectations, and the PR / issue workflow. Bug reports and feature requests are welcome — please use the issue templates so we have the reproducer / R-side context up front. For security issues, see [SECURITY.md](SECURITY.md) and email `hello@aigora.com` rather than filing a public issue.
+
+## Citing
+
+If you use FactoMinePy in published work, please cite both this package and the original R FactoMineR (Lê, Josse, Husson, *J. Stat. Softw.* 2008, [doi:10.18637/jss.v025.i01](https://doi.org/10.18637/jss.v025.i01)). A [CITATION.cff](CITATION.cff) is included for tools that consume it automatically.
+
+## License
+
+MIT for code. Bundled datasets carry their original licensing — see [factominer/datasets/data/PROVENANCE.md](factominer/datasets/data/PROVENANCE.md). The package does **not** redistribute R FactoMineR source (GPL); everything is reimplemented from the published documentation and validated against R outputs.
+
+## Acknowledgments
+
+- The R FactoMineR package by Sébastien Lê, Julie Josse, François Husson (and many contributors) defines the API surface this package targets.
+- `factoextra` for the visualization patterns that the matplotlib backend reproduces.
+- `scientisttools` and `prince` for prior Python ports that informed the API shape.