factominer 0.1.0.dev0__py3-none-any.whl

factominer/__init__.py

@@ -0,0 +1,36 @@
+"""factominer — a Python port of R's FactoMineR.
+
+This module re-exports the public API. The supported-methods table in
+``README.md`` is the source of truth for which symbols are live and which are
+stubs that raise ``NotImplementedError``.
+"""
+
+from __future__ import annotations
+
+# Deferred methods (Round 2). Imported so ``from factominer import HMFA`` works,
+# but the implementations raise NotImplementedError when called.
+from ._deferred import DMFA, FAMD, GPA, HMFA, MFA
+from ._result import Result
+from .ca import CA
+from .desc import catdes, condes, dimdesc
+from .hcpc import HCPC
+from .mca import MCA
+from .pca import PCA
+
+__all__ = [
+    "PCA",
+    "CA",
+    "MCA",
+    "FAMD",
+    "MFA",
+    "HMFA",
+    "DMFA",
+    "GPA",
+    "HCPC",
+    "dimdesc",
+    "catdes",
+    "condes",
+    "Result",
+]
+
+__version__ = "0.1.0.dev0"

factominer/_deferred.py

@@ -0,0 +1,46 @@
+"""Deferred-method stubs.
+
+Importable so ``from factominer import HMFA`` works, but raising
+``NotImplementedError`` when called. Each stub points at the plan that records
+the round-2 work and the reason.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def _deferred(name: str, hint: str) -> Any:
+    def stub(*_args: Any, **_kwargs: Any) -> Any:
+        raise NotImplementedError(
+            f"{name} is a Round 2 deferral. {hint} "
+            f"See docs/plans/factominer-python-port.md §2 and the README "
+            f"supported-methods table for the current status."
+        )
+
+    stub.__name__ = name
+    stub.__qualname__ = name
+    stub.__doc__ = f"Stub for {name}; deferred to Round 2."
+    return stub
+
+
+FAMD = _deferred(
+    "FAMD",
+    "Factor Analysis for Mixed Data is planned for the next iteration.",
+)
+MFA = _deferred(
+    "MFA",
+    "Multiple Factor Analysis is planned for the next iteration.",
+)
+HMFA = _deferred(
+    "HMFA",
+    "Hierarchical Multiple Factor Analysis is planned for the next iteration.",
+)
+DMFA = _deferred(
+    "DMFA",
+    "Dual Multiple Factor Analysis is planned for the next iteration.",
+)
+GPA = _deferred(
+    "GPA",
+    "Generalized Procrustes Analysis is planned for the next iteration.",
+)

factominer/_result.py

@@ -0,0 +1,111 @@
+"""Result containers mirroring FactoMineR's ``res`` lists.
+
+R returns lists with ``$``-accessed fields. We use a small set of
+``SimpleNamespace``-based holders so ``res.var.coord`` reads naturally in Python
+and the same shape can carry any subset of fields a method actually produces.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+
+@dataclass(frozen=True)
+class Block:
+    """A coordinates / cos² / contributions block (variables or individuals).
+
+    ``cor`` is FactoMineR's ``var$cor`` (variables only). ``dist`` is squared
+    distance to origin (FactoMineR's ``ind$dist``). ``v_test`` and ``eta2``
+    show up on qualitative blocks (MCA / quali.sup).
+    """
+
+    coord: pd.DataFrame
+    cos2: pd.DataFrame | None = None
+    contrib: pd.DataFrame | None = None
+    cor: pd.DataFrame | None = None
+    dist: pd.Series | None = None
+    inertia: pd.Series | None = None
+    v_test: pd.DataFrame | None = None
+    eta2: pd.DataFrame | None = None
+
+
+@dataclass(frozen=True)
+class SVD:
+    vs: np.ndarray  # singular values
+    U: np.ndarray   # left singular vectors (rows × ncp)
+    V: np.ndarray   # right singular vectors (cols × ncp)
+
+
+@dataclass(frozen=True)
+class Result:
+    """FactoMineR-shaped result object.
+
+    Only ``eig``, ``svd``, ``call`` are always present. Method-specific blocks
+    are attached as additional attributes — ``ind`` and ``var`` for PCA; ``row``
+    and ``col`` for CA; etc.
+    """
+
+    eig: pd.DataFrame
+    svd: SVD
+    call: dict[str, Any] = field(default_factory=dict)
+    ind: Block | None = None
+    var: Block | None = None
+    row: Block | None = None
+    col: Block | None = None
+    ind_sup: Block | None = None
+    quanti_sup: Block | None = None
+    quali_sup: Block | None = None
+    row_sup: Block | None = None
+    col_sup: Block | None = None
+    quanti_var_sup: Block | None = None
+    # Method tag for ``summary()``: "PCA", "CA", "MCA", ...
+    method: str = ""
+
+    def summary(self, ncp: int | None = None) -> str:
+        ncp = ncp if ncp is not None else min(5, self.eig.shape[0])
+        lines: list[str] = []
+        lines.append(f"\nResults for the {self.method or 'analysis'}")
+        lines.append("=" * 50)
+        lines.append("\nEigenvalues")
+        lines.append("-" * 50)
+        eig = self.eig.head(ncp).copy()
+        eig.columns = ["eigenvalue", "percentage of variance", "cumulative percentage of variance"]
+        lines.append(eig.round(4).to_string())
+
+        for label, block in [
+            ("Individuals", self.ind),
+            ("Variables", self.var),
+            ("Rows", self.row),
+            ("Columns", self.col),
+        ]:
+            if block is None:
+                continue
+            lines.append(f"\n{label} (the first {min(ncp, block.coord.shape[0])} are reported)")
+            lines.append("-" * 50)
+            head = block.coord.iloc[: min(10, block.coord.shape[0]), :ncp].copy()
+            head.columns = [f"Dim.{i + 1}" for i in range(head.shape[1])]
+            lines.append(head.round(4).to_string())
+
+        for label, block in [
+            ("Supplementary individuals", self.ind_sup),
+            ("Supplementary continuous variables", self.quanti_sup),
+            ("Supplementary categories", self.quali_sup),
+            ("Supplementary rows", self.row_sup),
+            ("Supplementary columns", self.col_sup),
+        ]:
+            if block is None or block.coord.empty:
+                continue
+            lines.append(f"\n{label}")
+            lines.append("-" * 50)
+            head = block.coord.iloc[: min(10, block.coord.shape[0]), :ncp].copy()
+            head.columns = [f"Dim.{i + 1}" for i in range(head.shape[1])]
+            lines.append(head.round(4).to_string())
+
+        return "\n".join(lines)
+
+    def __repr__(self) -> str:
+        return f"<factominer.{self.method or 'Result'} ncp={self.eig.shape[0]}>"

factominer/_scaling.py

@@ -0,0 +1,99 @@
+"""Scaling utilities for the factor-method engines."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+
+def coerce_numeric(X: pd.DataFrame) -> np.ndarray:
+    """Return X.values as float64, raising on any non-numeric column."""
+    non_numeric = [c for c in X.columns if not np.issubdtype(X[c].dtype, np.number)]
+    if non_numeric:
+        raise ValueError(f"non-numeric columns in X: {non_numeric}")
+    return np.asarray(X.to_numpy(), dtype=np.float64)
+
+
+def center_scale(
+    X: np.ndarray,
+    scale_unit: bool,
+    row_w: np.ndarray | None = None,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Weighted center (and optionally scale) X.
+
+    Returns ``(X_scaled, mean, scale)``. ``scale`` is the per-column divisor
+    used (1.0 when ``scale_unit=False``). Weights default to uniform.
+    """
+    n = X.shape[0]
+    if row_w is None:
+        row_w = np.full(n, 1.0 / n)
+    else:
+        row_w = np.asarray(row_w, dtype=np.float64)
+        if row_w.shape != (n,):
+            raise ValueError("row_w must have length n")
+        # Normalize to a probability vector for the moments.
+        row_w = row_w / row_w.sum()
+    mean = (X * row_w[:, None]).sum(axis=0)
+    Xc = X - mean
+    if scale_unit:
+        # FactoMineR uses 1/n weighted variance (not 1/(n-1)).
+        var = (Xc**2 * row_w[:, None]).sum(axis=0)
+        scale = np.sqrt(var)
+        scale_safe = np.where(scale < 1e-12, 1.0, scale)
+        Xs = Xc / scale_safe
+    else:
+        scale_safe = np.ones_like(mean)
+        Xs = Xc
+    return Xs, mean, scale_safe
+
+
+def column_indices(
+    cols: list[str] | pd.Index,
+    spec: list[int] | list[str] | None,
+) -> list[int]:
+    """Normalize a column spec (None / names / positional indices) to indices."""
+    if spec is None:
+        return []
+    out: list[int] = []
+    cols_list = list(cols)
+    for item in spec:
+        if isinstance(item, str):
+            if item not in cols_list:
+                raise KeyError(f"column not found: {item}")
+            out.append(cols_list.index(item))
+        elif isinstance(item, (int, np.integer)):
+            idx = int(item)
+            if not (0 <= idx < len(cols_list)):
+                raise IndexError(f"column index out of range: {idx}")
+            out.append(idx)
+        else:
+            raise TypeError(f"column spec items must be str or int, got {type(item).__name__}")
+    if len(out) != len(set(out)):
+        raise ValueError(f"duplicate column spec: {spec}")
+    return out
+
+
+def row_indices(
+    index: pd.Index,
+    spec: list[int] | list[str] | None,
+) -> list[int]:
+    """Normalize a row spec (None / names / positional indices) to indices."""
+    if spec is None:
+        return []
+    out: list[int] = []
+    idx_list = list(index)
+    for item in spec:
+        if isinstance(item, str):
+            if item not in idx_list:
+                raise KeyError(f"row not found: {item}")
+            out.append(idx_list.index(item))
+        elif isinstance(item, (int, np.integer)):
+            i = int(item)
+            if not (0 <= i < len(idx_list)):
+                raise IndexError(f"row index out of range: {i}")
+            out.append(i)
+        else:
+            raise TypeError(f"row spec items must be str or int, got {type(item).__name__}")
+    if len(out) != len(set(out)):
+        raise ValueError(f"duplicate row spec: {spec}")
+    return out

factominer/_sign.py

@@ -0,0 +1,50 @@
+"""Deterministic sign convention for SVD-based factor methods.
+
+SVD signs are not unique — flipping the sign of column k of U and of column k of
+V leaves the decomposition unchanged. Different libraries pick different
+conventions; we pick one and apply it uniformly so our output is reproducible.
+
+Convention: for each axis k, find the row index r with the largest absolute
+value in U[:, k]. If U[r, k] is negative, flip the signs of column k of U and V.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def align_signs(U: np.ndarray, V: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """Apply the project's sign convention to (U, V).
+
+    Both ``U`` and ``V`` are assumed to share the same column dimension (the
+    rank kept). Returns sign-aligned copies — inputs are not modified.
+    """
+    U = np.asarray(U, dtype=np.float64).copy()
+    V = np.asarray(V, dtype=np.float64).copy()
+    if U.ndim != 2 or V.ndim != 2 or U.shape[1] != V.shape[1]:
+        raise ValueError("U and V must be 2D and share the second dimension")
+    for k in range(U.shape[1]):
+        r = int(np.argmax(np.abs(U[:, k])))
+        if U[r, k] < 0:
+            U[:, k] *= -1
+            V[:, k] *= -1
+    return U, V
+
+
+def align_to_reference(values: np.ndarray, reference: np.ndarray) -> np.ndarray:
+    """Sign-align ``values`` axis-wise to ``reference``.
+
+    For each column, multiply by -1 if the dot product with the reference column
+    is negative. Used to compare our output to R FactoMineR fixtures whose own
+    sign convention differs.
+    """
+    values = np.asarray(values, dtype=np.float64).copy()
+    reference = np.asarray(reference, dtype=np.float64)
+    if values.shape != reference.shape:
+        raise ValueError(
+            f"shape mismatch: values={values.shape}, reference={reference.shape}"
+        )
+    for k in range(values.shape[1]):
+        if float(values[:, k] @ reference[:, k]) < 0:
+            values[:, k] *= -1
+    return values

factominer/_svd.py

@@ -0,0 +1,60 @@
+"""Shared SVD primitives for the factor-method engines.
+
+The generalized SVD (with row and column weights) underlies CA, MCA, FAMD, MFA.
+PCA is a special case with uniform weights.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ._sign import align_signs
+
+
+def standard_svd(X: np.ndarray, ncp: int) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """SVD of X, truncated to ``ncp`` components, sign-aligned.
+
+    Returns ``(U, vs, V)`` such that ``X ≈ U @ diag(vs) @ V.T``. Column counts
+    of U and V are min(ncp, rank).
+    """
+    X = np.asarray(X, dtype=np.float64)
+    if X.ndim != 2:
+        raise ValueError("X must be 2D")
+    U_full, vs_full, Vt_full = np.linalg.svd(X, full_matrices=False)
+    rank_cap = min(ncp, vs_full.size)
+    U = U_full[:, :rank_cap]
+    vs = vs_full[:rank_cap]
+    V = Vt_full[:rank_cap].T
+    U, V = align_signs(U, V)
+    return U, vs, V
+
+
+def generalized_svd(
+    X: np.ndarray,
+    row_w: np.ndarray,
+    col_w: np.ndarray,
+    ncp: int,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Generalized SVD with positive row and column weights.
+
+    Solves ``argmax`` of the bilinear form ``u' diag(row_w) X diag(col_w) v``
+    subject to ``u' diag(row_w) u = 1`` and ``v' diag(col_w) v = 1``.
+
+    Implemented as: form ``Y = diag(sqrt(row_w)) X diag(sqrt(col_w))``, do a
+    standard SVD on Y, then unwhiten the singular vectors. Returns ``(U, vs, V)``
+    on the *unwhitened* (original) scales. ``vs`` are the singular values of Y.
+    """
+    X = np.asarray(X, dtype=np.float64)
+    row_w = np.asarray(row_w, dtype=np.float64).reshape(-1)
+    col_w = np.asarray(col_w, dtype=np.float64).reshape(-1)
+    if row_w.size != X.shape[0] or col_w.size != X.shape[1]:
+        raise ValueError("weight vectors must match X's shape")
+    if (row_w <= 0).any() or (col_w <= 0).any():
+        raise ValueError("weights must be strictly positive")
+    sqrt_row = np.sqrt(row_w)
+    sqrt_col = np.sqrt(col_w)
+    Y = (X * sqrt_row[:, None]) * sqrt_col[None, :]
+    U_tilde, vs, V_tilde = standard_svd(Y, ncp)
+    U = U_tilde / sqrt_row[:, None]
+    V = V_tilde / sqrt_col[:, None]
+    return U, vs, V

factominer/ca.py

@@ -0,0 +1,164 @@
+"""Correspondence Analysis — FactoMineR-compatible API."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from ._result import SVD, Block, Result
+from ._scaling import row_indices
+from ._svd import standard_svd
+
+
+def CA(  # noqa: N802 — mirrors R
+    X: pd.DataFrame,
+    ncp: int = 5,
+    row_sup: list[int] | list[str] | None = None,
+    col_sup: list[int] | list[str] | None = None,
+    graph: bool = False,  # noqa: ARG001
+) -> Result:
+    """Run Correspondence Analysis on a contingency table.
+
+    Mirrors ``FactoMineR::CA``.
+    """
+    if not isinstance(X, pd.DataFrame):
+        raise TypeError("X must be a pandas DataFrame")
+    Xv = X.to_numpy(dtype=np.float64)
+    if (Xv < 0).any():
+        raise ValueError("CA requires non-negative counts")
+
+    row_sup_idx = row_indices(X.index, row_sup)
+    col_sup_idx = row_indices(X.columns, col_sup)
+
+    all_row_pos = np.arange(X.shape[0])
+    all_col_pos = np.arange(X.shape[1])
+    active_rows = np.array([i for i in all_row_pos if i not in set(row_sup_idx)])
+    active_cols = np.array([j for j in all_col_pos if j not in set(col_sup_idx)])
+
+    A = Xv[np.ix_(active_rows, active_cols)]
+    N = float(A.sum())
+    if N <= 0:
+        raise ValueError("active sub-table has zero total")
+    P = A / N
+    r = P.sum(axis=1)
+    c = P.sum(axis=0)
+    if (r <= 0).any() or (c <= 0).any():
+        raise ValueError("CA requires strictly positive row and column margins on the active table")
+    # Standardized residuals matrix S; SVD of S gives axes.
+    expected = np.outer(r, c)
+    S = (P - expected) / np.sqrt(expected)
+    n_pc = min(ncp, min(A.shape) - 1)
+    U_tilde, vs, V_tilde = standard_svd(S, n_pc)
+    eigenvalues = vs**2
+    # R returns all eigenvalues in res$eig (full rank, not truncated to ncp).
+    vs_full = np.linalg.svd(S, compute_uv=False)
+    eigenvalues_full = vs_full**2
+    # CA's rank is min(I,J)-1 (centering removes one axis); drop the trailing
+    # near-zero residual so the count matches FactoMineR's res$eig row count.
+    rank_ca = min(A.shape) - 1
+    if eigenvalues_full.size > rank_ca:
+        eigenvalues_full = eigenvalues_full[:rank_ca]
+        vs_full = vs_full[:rank_ca]
+    total_inertia = float((S**2).sum())
+
+    # Row / column coordinates (chi-square distance, "symmetric" rendering).
+    row_coord = (U_tilde * vs[None, :]) / np.sqrt(r)[:, None]
+    col_coord = (V_tilde * vs[None, :]) / np.sqrt(c)[:, None]
+
+    # Squared distance to centroid in chi-square space
+    row_dist2 = ((P / r[:, None] - c[None, :]) ** 2 / c[None, :]).sum(axis=1)
+    col_dist2 = ((P / c[None, :] - r[:, None]) ** 2 / r[:, None]).sum(axis=0)
+
+    with np.errstate(divide="ignore", invalid="ignore"):
+        row_cos2 = np.where(row_dist2[:, None] > 0, row_coord**2 / row_dist2[:, None], 0.0)
+        col_cos2 = np.where(col_dist2[:, None] > 0, col_coord**2 / col_dist2[:, None], 0.0)
+
+    row_contrib = (r[:, None] * row_coord**2) / np.where(
+        eigenvalues[None, :] > 0, eigenvalues[None, :], 1.0
+    ) * 100.0
+    col_contrib = (c[:, None] * col_coord**2) / np.where(
+        eigenvalues[None, :] > 0, eigenvalues[None, :], 1.0
+    ) * 100.0
+
+    row_inertia = r * row_dist2
+    col_inertia = c * col_dist2
+
+    dim_names = [f"Dim.{i + 1}" for i in range(n_pc)]
+    active_row_labels = list(X.index[active_rows])
+    active_col_labels = list(X.columns[active_cols])
+
+    eig_df = pd.DataFrame(
+        {
+            "eigenvalue": eigenvalues_full,
+            "percentage of variance": eigenvalues_full / total_inertia * 100.0,
+            "cumulative percentage of variance": np.cumsum(eigenvalues_full) / total_inertia * 100.0,
+        },
+        index=[f"dim {i + 1}" for i in range(eigenvalues_full.size)],
+    )
+
+    row_block = Block(
+        coord=pd.DataFrame(row_coord, index=active_row_labels, columns=dim_names),
+        cos2=pd.DataFrame(row_cos2, index=active_row_labels, columns=dim_names),
+        contrib=pd.DataFrame(row_contrib, index=active_row_labels, columns=dim_names),
+        inertia=pd.Series(row_inertia, index=active_row_labels, name="inertia"),
+        dist=pd.Series(np.sqrt(row_dist2), index=active_row_labels, name="dist"),
+    )
+    col_block = Block(
+        coord=pd.DataFrame(col_coord, index=active_col_labels, columns=dim_names),
+        cos2=pd.DataFrame(col_cos2, index=active_col_labels, columns=dim_names),
+        contrib=pd.DataFrame(col_contrib, index=active_col_labels, columns=dim_names),
+        inertia=pd.Series(col_inertia, index=active_col_labels, name="inertia"),
+        dist=pd.Series(np.sqrt(col_dist2), index=active_col_labels, name="dist"),
+    )
+
+    # Supplementary rows (project onto column-axis basis)
+    row_sup_block = None
+    if row_sup_idx:
+        A_sup = Xv[np.ix_(np.asarray(row_sup_idx), active_cols)]
+        r_sup = A_sup.sum(axis=1)
+        r_sup_safe = np.where(r_sup <= 0, 1.0, r_sup)
+        prof_sup = A_sup / r_sup_safe[:, None]
+        # Row sup coords = (profile - c) projected on V_tilde / sqrt(c) (transition formula)
+        coord_sup = ((prof_sup - c[None, :]) / np.sqrt(c)[None, :]) @ V_tilde
+        dist2_sup = ((prof_sup - c[None, :]) ** 2 / c[None, :]).sum(axis=1)
+        with np.errstate(divide="ignore", invalid="ignore"):
+            cos2_sup = np.where(dist2_sup[:, None] > 0, coord_sup**2 / dist2_sup[:, None], 0.0)
+        row_sup_block = Block(
+            coord=pd.DataFrame(coord_sup, index=[X.index[i] for i in row_sup_idx], columns=dim_names),
+            cos2=pd.DataFrame(cos2_sup, index=[X.index[i] for i in row_sup_idx], columns=dim_names),
+            dist=pd.Series(np.sqrt(dist2_sup), index=[X.index[i] for i in row_sup_idx], name="dist"),
+        )
+
+    col_sup_block = None
+    if col_sup_idx:
+        A_sup = Xv[np.ix_(active_rows, np.asarray(col_sup_idx))]
+        c_sup = A_sup.sum(axis=0)
+        c_sup_safe = np.where(c_sup <= 0, 1.0, c_sup)
+        prof_sup = A_sup / c_sup_safe[None, :]
+        coord_sup = ((prof_sup.T - r[None, :]) / np.sqrt(r)[None, :]) @ U_tilde
+        dist2_sup = ((prof_sup.T - r[None, :]) ** 2 / r[None, :]).sum(axis=1)
+        with np.errstate(divide="ignore", invalid="ignore"):
+            cos2_sup = np.where(dist2_sup[:, None] > 0, coord_sup**2 / dist2_sup[:, None], 0.0)
+        col_sup_block = Block(
+            coord=pd.DataFrame(coord_sup, index=[X.columns[j] for j in col_sup_idx], columns=dim_names),
+            cos2=pd.DataFrame(cos2_sup, index=[X.columns[j] for j in col_sup_idx], columns=dim_names),
+            dist=pd.Series(np.sqrt(dist2_sup), index=[X.columns[j] for j in col_sup_idx], name="dist"),
+        )
+
+    return Result(
+        eig=eig_df,
+        svd=SVD(vs=vs_full.copy(), U=U_tilde.copy(), V=V_tilde.copy()),
+        call={
+            "ncp": ncp,
+            "row_sup": row_sup_idx,
+            "col_sup": col_sup_idx,
+            "N": N,
+            "marge_row": r.copy(),
+            "marge_col": c.copy(),
+        },
+        row=row_block,
+        col=col_block,
+        row_sup=row_sup_block,
+        col_sup=col_sup_block,
+        method="CA",
+    )

factominer/datasets/__init__.py

@@ -0,0 +1,54 @@
+"""Bundled datasets re-used from FactoMineR's distribution for parity testing.
+
+See ``factominer/datasets/data/PROVENANCE.md`` for the origin and licensing of
+each file.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+
+_DATA_DIR = Path(__file__).parent / "data"
+
+
+def _load_csv(name: str) -> pd.DataFrame:
+    path = _DATA_DIR / name
+    if not path.exists():
+        raise FileNotFoundError(f"dataset not bundled: {path.name}")
+    return pd.read_csv(path, index_col=0)
+
+
+def load_decathlon() -> pd.DataFrame:
+    """41 athletes × 13 columns from the 2004 Athens Olympic + Décastar decathlons.
+
+    Columns: ten athletic events (seconds or meters), plus ``Rank``, ``Points``,
+    and ``Competition`` (a two-level factor). FactoMineR's canonical PCA example.
+    """
+    return _load_csv("decathlon.csv")
+
+
+def load_children() -> pd.DataFrame:
+    """18 × 8 contingency table on the perceptions of children's worries.
+
+    Rows: kinds of worries. Columns: socio-educational categories. Used in
+    FactoMineR's CA examples.
+    """
+    return _load_csv("children.csv")
+
+
+def load_tea() -> pd.DataFrame:
+    """300 × 36 survey on tea consumption habits.
+
+    Mostly categorical (factors); one integer column. Canonical MCA example.
+    """
+    return _load_csv("tea.csv")
+
+
+def load_poison() -> pd.DataFrame:
+    """55 × 15 food-poisoning outbreak survey.
+
+    Mixed categorical + quantitative. Used in MCA / FAMD examples.
+    """
+    return _load_csv("poison.csv")