catgen 0.1.0__py3-none-any.whl

catgen/__init__.py

@@ -0,0 +1,64 @@
+"""catgen – Categorical data generator for machine learning benchmarks.
+
+Includes SNP genetics simulation, k-multiplexer boolean datasets, DNF
+concepts, MONK benchmarks, epistasis, geometric boundaries, and more.
+"""
+
+__version__ = "0.1.0"
+
+from catgen.simulation.snp import (
+    SimSNPGlm,
+    SimSNPCovariateGlm,
+    simulate_snp_glm,
+    simulate_snp_glm_with_covariates,
+)
+from catgen.datasets import (
+    generate_multiplexer_dataset,
+    generate_xor_parity_dataset,
+    generate_dnf_concept_dataset,
+    generate_monk1_dataset,
+    generate_monk3_dataset,
+    generate_overlapping_rules_dataset,
+    generate_modular_sum_dataset,
+    generate_epistasis_dataset,
+    generate_highdim_lowsample_dataset,
+    generate_imbalanced_dataset,
+    generate_checkerboard_dataset,
+    generate_circle_boundary_dataset,
+    generate_diagonal_boundary_dataset,
+    generate_spiral_dataset,
+    generate_concentric_rings_dataset,
+    generate_deep_tree_dataset,
+    generate_sequential_threshold_dataset,
+    generate_hierarchical_interaction_dataset,
+    generate_snp_glm_dataset,
+    generate_snp_glm_with_covariates_dataset,
+)
+
+__all__ = [
+    "__version__",
+    "SimSNPGlm",
+    "SimSNPCovariateGlm",
+    "simulate_snp_glm",
+    "simulate_snp_glm_with_covariates",
+    "generate_multiplexer_dataset",
+    "generate_xor_parity_dataset",
+    "generate_dnf_concept_dataset",
+    "generate_monk1_dataset",
+    "generate_monk3_dataset",
+    "generate_overlapping_rules_dataset",
+    "generate_modular_sum_dataset",
+    "generate_epistasis_dataset",
+    "generate_highdim_lowsample_dataset",
+    "generate_imbalanced_dataset",
+    "generate_checkerboard_dataset",
+    "generate_circle_boundary_dataset",
+    "generate_diagonal_boundary_dataset",
+    "generate_spiral_dataset",
+    "generate_concentric_rings_dataset",
+    "generate_deep_tree_dataset",
+    "generate_sequential_threshold_dataset",
+    "generate_hierarchical_interaction_dataset",
+    "generate_snp_glm_dataset",
+    "generate_snp_glm_with_covariates_dataset",
+]

catgen/datasets/__init__.py

@@ -0,0 +1,80 @@
+"""catgen.datasets – synthetic benchmark dataset generators.
+
+All generators return ``(X, y)`` tuples of NumPy arrays and accept a
+``random_state`` keyword argument for reproducibility.
+
+Submodules
+----------
+multiplexer
+    k-multiplexer boolean classification tasks.
+boolean_concepts
+    XOR/parity, DNF concepts, MONK benchmarks, overlapping rules.
+biomedical
+    SNP epistasis (GAMETES-style), high-dimensional low-sample, imbalanced.
+geometric
+    Checkerboard, circle/spiral/ring boundaries.
+structured
+    Modular sum, deep tree, sequential thresholds, hierarchical interactions.
+snp_generators
+    SNP dataset generators with unified (X, y) interface.
+"""
+
+from catgen.datasets.multiplexer import generate_multiplexer_dataset
+from catgen.datasets.boolean_concepts import (
+    generate_xor_parity_dataset,
+    generate_dnf_concept_dataset,
+    generate_monk1_dataset,
+    generate_monk3_dataset,
+    generate_overlapping_rules_dataset,
+    generate_modular_sum_dataset,
+)
+from catgen.datasets.biomedical import (
+    generate_epistasis_dataset,
+    generate_highdim_lowsample_dataset,
+    generate_imbalanced_dataset,
+)
+from catgen.datasets.geometric import (
+    generate_checkerboard_dataset,
+    generate_circle_boundary_dataset,
+    generate_diagonal_boundary_dataset,
+    generate_spiral_dataset,
+    generate_concentric_rings_dataset,
+)
+from catgen.datasets.structured import (
+    generate_deep_tree_dataset,
+    generate_sequential_threshold_dataset,
+    generate_hierarchical_interaction_dataset,
+)
+from catgen.datasets.snp_generators import (
+    generate_snp_glm_dataset,
+    generate_snp_glm_with_covariates_dataset,
+)
+
+__all__ = [
+    # multiplexer
+    "generate_multiplexer_dataset",
+    # boolean concepts
+    "generate_xor_parity_dataset",
+    "generate_dnf_concept_dataset",
+    "generate_monk1_dataset",
+    "generate_monk3_dataset",
+    "generate_overlapping_rules_dataset",
+    "generate_modular_sum_dataset",
+    # biomedical
+    "generate_epistasis_dataset",
+    "generate_highdim_lowsample_dataset",
+    "generate_imbalanced_dataset",
+    # geometric
+    "generate_checkerboard_dataset",
+    "generate_circle_boundary_dataset",
+    "generate_diagonal_boundary_dataset",
+    "generate_spiral_dataset",
+    "generate_concentric_rings_dataset",
+    # structured
+    "generate_deep_tree_dataset",
+    "generate_sequential_threshold_dataset",
+    "generate_hierarchical_interaction_dataset",
+    # snp_generators
+    "generate_snp_glm_dataset",
+    "generate_snp_glm_with_covariates_dataset",
+]

catgen/datasets/biomedical.py

@@ -0,0 +1,161 @@
+"""Biomedical synthetic datasets (epistasis, high-dimensional, imbalanced).
+
+These datasets simulate scenarios common in computational biology and
+rare-disease research.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def generate_epistasis_dataset(
+    n_samples: int = 1600,
+    n_snps: int = 20,
+    n_interacting: int = 2,
+    heritability: float = 0.4,
+    minor_allele_freq: float = 0.3,
+    *,
+    random_state: int | None = None,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Generate a synthetic epistasis dataset (SNP-SNP interaction).
+
+    The class is determined exclusively by an interaction among
+    ``n_interacting`` SNPs; all other SNPs are noise features.
+    The model emulates GAMETES behavior: causal SNPs jointly create an
+    XOR-like pattern (no main effect, only interaction).
+
+    Parameters
+    ----------
+    n_samples : int
+        Number of instances.
+    n_snps : int
+        Total number of SNP features (including causal SNPs).
+    n_interacting : int
+        Number of interacting causal SNPs (2 or 3 recommended).
+    heritability : float
+        Strength of genetic signal (0 = no signal, 1 = perfectly separable).
+        Controls the penetrance table.
+    minor_allele_freq : float
+        Minor allele frequency for Hardy-Weinberg equilibrium (0 < maf < 0.5).
+    random_state : int or None
+        Seed for reproducibility.
+
+    Returns
+    -------
+    X : np.ndarray, shape (n_samples, n_snps), dtype int  (values: 0, 1, 2)
+    y : np.ndarray, shape (n_samples,), dtype int  (0 or 1)
+    """
+    rng = np.random.default_rng(random_state)
+    if n_interacting > n_snps:
+        raise ValueError("n_interacting must not exceed n_snps")
+    if not (0 < minor_allele_freq < 0.5):
+        raise ValueError("minor_allele_freq must be in (0, 0.5)")
+
+    p = minor_allele_freq
+    hw_probs = [(1 - p) ** 2, 2 * p * (1 - p), p ** 2]
+    X = rng.choice(3, size=(n_samples, n_snps), p=hw_probs)
+
+    causal = X[:, :n_interacting]
+    interaction_signal = np.sum(causal, axis=1) % 2
+
+    pen_high = min(1.0, 0.5 + heritability / 2)
+    pen_low = max(0.0, 0.5 - heritability / 2)
+    probs = np.where(interaction_signal == 1, pen_high, pen_low)
+    y = (rng.random(n_samples) < probs).astype(int)
+
+    perm = rng.permutation(n_snps)
+    X = X[:, perm]
+    return X, y
+
+
+def generate_highdim_lowsample_dataset(
+    n_samples: int = 120,
+    n_features: int = 500,
+    n_informative: int = 5,
+    n_classes: int = 2,
+    *,
+    random_state: int | None = None,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Generate a high-dimensional dataset with few samples (p >> n).
+
+    Typical for genomics scenarios (e.g. microarray, SNP panels): many features,
+    few patients, and only a few informative features.
+
+    Parameters
+    ----------
+    n_samples : int
+        Number of instances (typically small, e.g. 80–200).
+    n_features : int
+        Total number of features (typically large, e.g. 200–2000).
+    n_informative : int
+        Number of truly informative features.
+    n_classes : int
+        Number of classes.
+    random_state : int or None
+        Seed.
+
+    Returns
+    -------
+    X : np.ndarray, shape (n_samples, n_features)
+    y : np.ndarray, shape (n_samples,), dtype int
+    """
+    from sklearn.datasets import make_classification
+
+    X, y = make_classification(
+        n_samples=n_samples,
+        n_features=n_features,
+        n_informative=n_informative,
+        n_redundant=2,
+        n_clusters_per_class=1,
+        n_classes=n_classes,
+        flip_y=0.03,
+        class_sep=1.0,
+        random_state=random_state,
+    )
+    return X, y
+
+
+def generate_imbalanced_dataset(
+    n_samples: int = 1000,
+    n_features: int = 10,
+    n_informative: int = 5,
+    imbalance_ratio: float = 0.1,
+    *,
+    random_state: int | None = None,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Generate a dataset with strong class imbalance.
+
+    Simulates rare diseases or rare events.
+
+    Parameters
+    ----------
+    n_samples : int
+        Total number of instances.
+    n_features : int
+        Number of features.
+    n_informative : int
+        Number of informative features.
+    imbalance_ratio : float
+        Minority class ratio (e.g. 0.1 = 10%).
+    random_state : int or None
+        Seed.
+
+    Returns
+    -------
+    X : np.ndarray, shape (n_samples, n_features)
+    y : np.ndarray, shape (n_samples,), dtype int (0 or 1)
+    """
+    from sklearn.datasets import make_classification
+
+    X, y = make_classification(
+        n_samples=n_samples,
+        n_features=n_features,
+        n_informative=n_informative,
+        n_redundant=2,
+        n_clusters_per_class=1,
+        weights=[1 - imbalance_ratio, imbalance_ratio],
+        flip_y=0.01,
+        random_state=random_state,
+    )
+    return X, y

catgen/datasets/boolean_concepts.py

@@ -0,0 +1,309 @@
+"""Boolean concept datasets (XOR/parity, DNF, MONK, overlapping rules, modular sum).
+
+These datasets expose weaknesses of CART and are well-suited for evaluating
+rule-set learners.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def generate_xor_parity_dataset(
+    n_bits: int = 6,
+    n_noise_features: int = 14,
+    n_samples: int = 2000,
+    *,
+    random_state: int | None = None,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Generate an XOR/parity dataset with noise features.
+
+    The class is the parity (XOR) of the first ``n_bits`` binary features.
+    Additionally, ``n_noise_features`` random binary features are appended.
+    This dataset is non-linearly separable and requires conjunctive rules.
+
+    Parameters
+    ----------
+    n_bits : int
+        Number of relevant parity bits.
+    n_noise_features : int
+        Number of irrelevant noise features.
+    n_samples : int
+        Number of instances.
+    random_state : int or None
+        Seed.
+
+    Returns
+    -------
+    X : np.ndarray, shape (n_samples, n_bits + n_noise_features), dtype int
+    y : np.ndarray, shape (n_samples,), dtype int (0 or 1)
+    """
+    rng = np.random.default_rng(random_state)
+    total_features = n_bits + n_noise_features
+    X = rng.integers(0, 2, size=(n_samples, total_features))
+    y = np.bitwise_xor.reduce(X[:, :n_bits], axis=1)
+
+    perm = rng.permutation(total_features)
+    X = X[:, perm]
+    return X, y
+
+
+def generate_dnf_concept_dataset(
+    n_disjuncts: int = 3,
+    n_conjuncts: int = 2,
+    n_noise_features: int = 10,
+    n_samples: int = 2000,
+    noise_rate: float = 0.0,
+    *,
+    random_state: int | None = None,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Generate a dataset with a DNF decision rule.
+
+    The true concept is a disjunction of ``n_disjuncts`` conjunctions,
+    where each conjunction requires ``n_conjuncts`` different binary features.
+    CART must duplicate subtrees for this; rule sets can represent each
+    disjunct directly as a separate rule.
+
+    Parameters
+    ----------
+    n_disjuncts : int
+        Number of disjuncts (OR terms).
+    n_conjuncts : int
+        Number of conjuncts per disjunct (AND terms).
+    n_noise_features : int
+        Additional irrelevant binary features.
+    n_samples : int
+        Number of instances.
+    noise_rate : float
+        Fraction of randomly flipped labels (0 = no noise).
+    random_state : int or None
+        Seed.
+
+    Returns
+    -------
+    X : np.ndarray, shape (n_samples, n_disjuncts * n_conjuncts + n_noise_features), dtype int
+    y : np.ndarray, shape (n_samples,), dtype int (0 or 1)
+    """
+    rng = np.random.default_rng(random_state)
+    n_relevant = n_disjuncts * n_conjuncts
+    n_features = n_relevant + n_noise_features
+    X = rng.integers(0, 2, size=(n_samples, n_features))
+
+    y = np.zeros(n_samples, dtype=int)
+    for d in range(n_disjuncts):
+        clause = np.ones(n_samples, dtype=bool)
+        for c in range(n_conjuncts):
+            clause &= X[:, d * n_conjuncts + c] == 1
+        y |= clause.astype(int)
+
+    if noise_rate > 0:
+        flip = rng.random(n_samples) < noise_rate
+        y[flip] = 1 - y[flip]
+
+    perm = rng.permutation(n_features)
+    X = X[:, perm]
+    return X, y
+
+
+def generate_monk1_dataset(
+    n_samples: int = 2000,
+    *,
+    random_state: int | None = None,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Generate the MONK-1 dataset (disjunction: (a1==a2) OR (a5==1)).
+
+    MONK-1 is a classic benchmark for rule learners. The decision rule is a
+    disjunction that CART can represent only via subtree duplication.
+
+    Attributes: a1 in {1,2,3}, a2 in {1,2,3}, a3 in {1,2},
+                a4 in {1,2,3}, a5 in {1,2,3,4}, a6 in {1,2}
+
+    Parameters
+    ----------
+    n_samples : int
+        Number of instances (sampling with replacement if > 432).
+    random_state : int or None
+        Seed.
+
+    Returns
+    -------
+    X : np.ndarray, shape (n_samples, 6), dtype float
+    y : np.ndarray, shape (n_samples,), dtype int (0 or 1)
+    """
+    rng = np.random.default_rng(random_state)
+    domains = [3, 3, 2, 3, 4, 2]
+    n_total = 1
+    for d in domains:
+        n_total *= d  # 432
+
+    rows = np.zeros((n_total, 6), dtype=int)
+    idx = 0
+    for a1 in range(domains[0]):
+        for a2 in range(domains[1]):
+            for a3 in range(domains[2]):
+                for a4 in range(domains[3]):
+                    for a5 in range(domains[4]):
+                        for a6 in range(domains[5]):
+                            rows[idx] = [a1, a2, a3, a4, a5, a6]
+                            idx += 1
+
+    y_full = ((rows[:, 0] == rows[:, 1]) | (rows[:, 4] == 1)).astype(int)
+
+    if n_samples >= n_total:
+        X, y = rows, y_full
+    else:
+        chosen = rng.choice(n_total, size=n_samples, replace=True)
+        X, y = rows[chosen], y_full[chosen]
+
+    return X.astype(float), y
+
+
+def generate_monk3_dataset(
+    n_samples: int = 2000,
+    noise_rate: float = 0.05,
+    *,
+    random_state: int | None = None,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Generate the MONK-3 dataset (conjunction + exception + noise).
+
+    MONK-3 rule: (a5 != 3 AND a4 != 1) OR (a5 == 3 AND a2 != 3),
+    plus ``noise_rate`` randomly flipped labels.
+
+    Parameters
+    ----------
+    n_samples : int
+        Number of instances.
+    noise_rate : float
+        Fraction of randomly flipped labels (default: 5%).
+    random_state : int or None
+        Seed.
+
+    Returns
+    -------
+    X : np.ndarray, shape (n_samples, 6), dtype float
+    y : np.ndarray, shape (n_samples,), dtype int (0 or 1)
+    """
+    rng = np.random.default_rng(random_state)
+    domains = [3, 3, 2, 3, 4, 2]
+    n_total = 1
+    for d in domains:
+        n_total *= d
+
+    rows = np.zeros((n_total, 6), dtype=int)
+    idx = 0
+    for a1 in range(domains[0]):
+        for a2 in range(domains[1]):
+            for a3 in range(domains[2]):
+                for a4 in range(domains[3]):
+                    for a5 in range(domains[4]):
+                        for a6 in range(domains[5]):
+                            rows[idx] = [a1, a2, a3, a4, a5, a6]
+                            idx += 1
+
+    y_full = (
+        ((rows[:, 4] != 3) & (rows[:, 3] != 1))
+        | ((rows[:, 4] == 3) & (rows[:, 1] != 2))
+    ).astype(int)
+
+    if n_samples >= n_total:
+        X, y = rows, y_full
+    else:
+        chosen = rng.choice(n_total, size=n_samples, replace=True)
+        X, y = rows[chosen], y_full[chosen]
+
+    if noise_rate > 0:
+        flip = rng.random(len(y)) < noise_rate
+        y[flip] = 1 - y[flip]
+
+    return X.astype(float), y
+
+
+def generate_overlapping_rules_dataset(
+    n_rules: int = 4,
+    n_features_per_rule: int = 2,
+    n_noise_features: int = 10,
+    n_samples: int = 2000,
+    *,
+    random_state: int | None = None,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Generate a dataset with multiple independent, overlapping rules.
+
+    Each rule defines a positive region using a threshold over
+    ``n_features_per_rule`` continuous features. The class is 1 if at least
+    one rule fires. CART struggles because the rules are not hierarchical.
+
+    Parameters
+    ----------
+    n_rules : int
+        Number of independent rules.
+    n_features_per_rule : int
+        Number of features per rule.
+    n_noise_features : int
+        Additional noise features.
+    n_samples : int
+        Number of instances.
+    random_state : int or None
+        Seed.
+
+    Returns
+    -------
+    X : np.ndarray, shape (n_samples, n_rules * n_features_per_rule + n_noise_features)
+    y : np.ndarray, shape (n_samples,), dtype int (0 or 1)
+    """
+    rng = np.random.default_rng(random_state)
+    n_relevant = n_rules * n_features_per_rule
+    n_total_features = n_relevant + n_noise_features
+    X = rng.uniform(0, 1, size=(n_samples, n_total_features))
+
+    y = np.zeros(n_samples, dtype=int)
+    for r in range(n_rules):
+        start = r * n_features_per_rule
+        end = start + n_features_per_rule
+        fired = np.all(X[:, start:end] > 0.6, axis=1)
+        y[fired] = 1
+
+    perm = rng.permutation(n_total_features)
+    X = X[:, perm]
+    return X, y
+
+
+def generate_modular_sum_dataset(
+    n_relevant: int = 4,
+    n_noise_features: int = 8,
+    n_samples: int = 2000,
+    modulus: int = 3,
+    *,
+    random_state: int | None = None,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Generate a dataset where class depends on a modular sum.
+
+    y = (sum(X[:, :n_relevant]) mod modulus == 0). This pattern creates
+    non-axis-parallel decision boundaries that CART can only approximate
+    inefficiently.
+
+    Parameters
+    ----------
+    n_relevant : int
+        Number of relevant features.
+    n_noise_features : int
+        Additional noise features.
+    n_samples : int
+        Number of instances.
+    modulus : int
+        Modulus for the sum function.
+    random_state : int or None
+        Seed.
+
+    Returns
+    -------
+    X : np.ndarray, shape (n_samples, n_relevant + n_noise_features), dtype float
+    y : np.ndarray, shape (n_samples,), dtype int (0 or 1)
+    """
+    rng = np.random.default_rng(random_state)
+    n_total = n_relevant + n_noise_features
+    X = rng.integers(0, modulus + 1, size=(n_samples, n_total))
+    y = (np.sum(X[:, :n_relevant], axis=1) % modulus == 0).astype(int)
+
+    perm = rng.permutation(n_total)
+    X = X[:, perm]
+    return X.astype(float), y