synthbench 0.1.0__py3-none-any.whl

synthbench/__init__.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from synthbench._version import __version__
+from synthbench.corruptors import (
+    BaseCorruptor,
+    BaseLabelCorruptor,
+    CategoricalCorruptor,
+    CollinearityCorruptor,
+    LabelNoiseCorruptor,
+    MeasurementNoiseCorruptor,
+    MissingDataCorruptor,
+    OutlierCorruptor,
+)
+from synthbench.dgps import (
+    AdditiveDGP,
+    BaseDGP,
+    FriedmanDGP,
+    GeometricDGP,
+    LinearDGP,
+    PolynomialDGP,
+    SparseDGP,
+    TreeDGP,
+)
+from synthbench.pipeline import BenchPipeline, BenchResult
+from synthbench.suite import BenchSuite
+from synthbench.sweeps import difficulty_sweep, experiment_grid, severity_sweep
+
+__all__ = [
+    "__version__",
+    "AdditiveDGP",
+    "BaseDGP",
+    "BaseCorruptor",
+    "BaseLabelCorruptor",
+    "BenchPipeline",
+    "BenchResult",
+    "BenchSuite",
+    "CategoricalCorruptor",
+    "CollinearityCorruptor",
+    "difficulty_sweep",
+    "experiment_grid",
+    "FriedmanDGP",
+    "GeometricDGP",
+    "LabelNoiseCorruptor",
+    "LinearDGP",
+    "MeasurementNoiseCorruptor",
+    "MissingDataCorruptor",
+    "OutlierCorruptor",
+    "PolynomialDGP",
+    "severity_sweep",
+    "SparseDGP",
+    "TreeDGP",
+    # RandomNeuralDGP is available only with synthbench[neural] (torch required).
+    # It is exposed lazily via __getattr__ below so that importing synthbench
+    # does NOT unconditionally load torch into sys.modules.
+    "RandomNeuralDGP",
+]
+
+# Names that are only available with the neural extra (torch).
+_NEURAL_NAMES = {"RandomNeuralDGP"}
+
+
+def __getattr__(name: str):
+    """Lazy loader for optional neural symbols (requires synthbench[neural])."""
+    if name in _NEURAL_NAMES:
+        try:
+            from synthbench.dgps.neural import RandomNeuralDGP
+        except ImportError as exc:
+            raise ImportError(
+                f"{name} requires PyTorch. "
+                "Install it with: pip install synthbench[neural]"
+            ) from exc
+        # Cache in module namespace so subsequent lookups are O(1).
+        import synthbench as _self
+
+        setattr(_self, name, RandomNeuralDGP)
+        return RandomNeuralDGP
+    raise AttributeError(f"module 'synthbench' has no attribute {name!r}")

synthbench/_seed.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import numpy as np
+from numpy.random import SeedSequence
+
+
+def derive_seeds(master_state: int | SeedSequence, n: int) -> list[int]:
+    """Derive *n* independent integer seeds from a master state.
+
+    Uses ``numpy.random.SeedSequence.spawn`` so that child seeds are
+    statistically independent and fully reproducible from the master state.
+    The global numpy RNG state is never touched.
+
+    Parameters
+    ----------
+    master_state:
+        Either a plain integer that seeds the root ``SeedSequence``, or an
+        already-constructed ``SeedSequence`` (e.g. from a parent context).
+    n:
+        Number of independent child seeds to derive.
+
+    Returns
+    -------
+    list[int]
+        Plain Python ints (JSON-serializable, not numpy dtypes).
+    """
+    if isinstance(master_state, SeedSequence):
+        seq = master_state
+    else:
+        seq = SeedSequence(int(master_state))
+
+    children = seq.spawn(n)
+    # generate_state(1)[0] gives a single uint64 from the child sequence
+    return [int(child.generate_state(1)[0]) for child in children]
+
+
+def make_rng(seed: int) -> np.random.RandomState:
+    """Return a local ``numpy.random.RandomState`` seeded with *seed*.
+
+    Use ``sklearn.utils.check_random_state`` for public APIs that accept
+    ``int | None | RandomState``.
+    """
+    return np.random.RandomState(seed)

synthbench/_version.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+try:
+    from importlib.metadata import PackageNotFoundError, version
+
+    __version__ = version("synthbench")
+except PackageNotFoundError:
+    __version__ = "0.0.0+dev"

synthbench/corruptors/__init__.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from synthbench.corruptors.base import BaseCorruptor
+from synthbench.corruptors.categorical import CategoricalCorruptor
+from synthbench.corruptors.collinearity import CollinearityCorruptor
+from synthbench.corruptors.label_base import (
+    BaseLabelCorruptor,
+)
+from synthbench.corruptors.label_noise import LabelNoiseCorruptor
+from synthbench.corruptors.measurement_noise import MeasurementNoiseCorruptor
+from synthbench.corruptors.missing_data import MissingDataCorruptor
+from synthbench.corruptors.outlier import OutlierCorruptor
+
+__all__ = [
+    "BaseCorruptor",
+    "BaseLabelCorruptor",
+    "CategoricalCorruptor",
+    "CollinearityCorruptor",
+    "LabelNoiseCorruptor",
+    "MeasurementNoiseCorruptor",
+    "MissingDataCorruptor",
+    "OutlierCorruptor",
+]

synthbench/corruptors/base.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+import numpy as np
+
+_CORRUPTOR_REGISTRY: dict[str, type] = {}
+
+
+class BaseCorruptor(ABC):
+    """Abstract base class for all corruptors.
+
+    Concrete subclasses must:
+    - Declare ``key="some_key"`` in their class signature to be auto-registered.
+    - Implement [corrupt][synthbench.corruptors.base.BaseCorruptor.corrupt].
+
+    Corruptors transform X only; y is never passed in or mutated.
+
+    Example::
+
+        class CollinearityCorruptor(BaseCorruptor, key="collinearity"):
+            def corrupt(self, X, metadata, random_state):
+                ...
+    """
+
+    def __init_subclass__(cls, key: str | None = None, **kwargs: object) -> None:
+        super().__init_subclass__(**kwargs)
+        if key is not None:
+            if key in _CORRUPTOR_REGISTRY:
+                raise ValueError(
+                    f"Duplicate corruptor key '{key}': already registered by "
+                    f"{_CORRUPTOR_REGISTRY[key].__qualname__}"
+                )
+            _CORRUPTOR_REGISTRY[key] = cls
+
+    @abstractmethod
+    def corrupt(
+        self,
+        X: np.ndarray,
+        metadata: dict,
+        random_state: int,
+    ) -> tuple[np.ndarray, dict]:
+        """Apply a structural transformation to X.
+
+        Parameters
+        ----------
+        X:
+            Feature matrix of shape (n_samples, n_features). Must not be
+            modified in-place; return a new array.
+        metadata:
+            The BenchResult metadata dict produced by the DGP. Corruptors
+            may add keys (e.g. effective_feature_importances) but must not
+            remove or overwrite existing keys set by the DGP.
+        random_state:
+            Integer seed. Each corruptor derives its own RNG from this value
+            so that results are fully reproducible.
+
+        Returns
+        -------
+        X_corrupted : np.ndarray
+            Transformed feature matrix, same shape as X.
+        updated_metadata : dict
+            Metadata dict with any corruptor-specific fields added.
+        """
+
+    def get_params(self) -> dict[str, object]:
+        """Return the corruptor's current configuration as a plain dict.
+
+        Concrete corruptors should override this to return their __init__
+        parameters. Used by BenchPipeline to record component provenance.
+        """
+        raise NotImplementedError(
+            f"{type(self).__qualname__}.get_params() is not implemented. "
+            "Concrete corruptor subclasses must override this method."
+        )
+
+
+__all__ = ["BaseCorruptor", "_CORRUPTOR_REGISTRY"]

synthbench/corruptors/categorical.py

@@ -0,0 +1,154 @@
+"""CategoricalCorruptor -- bins continuous features into integer categories."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from synthbench.corruptors.base import BaseCorruptor
+
+_SEVERITY_N_BINS: dict[str, int] = {
+    "low": 10,
+    "medium": 5,
+    "high": 2,
+}
+
+
+class CategoricalCorruptor(BaseCorruptor, key="categorical"):
+    """Converts continuous features to integer-encoded bins.
+
+    For each targeted column, quantile-based bin edges are computed and
+    ``np.digitize`` is used to assign each sample to a bin index
+    ``0, 1, ..., n_bins-1``.  The column values are replaced with these
+    integer indices cast to ``float``.
+
+    Feature importances are discounted by the factor ``(1 - 1/n_bins)``
+    for each targeted column, then re-normalized to sum to 1.
+
+    Parameters
+    ----------
+    severity:
+        Controls default ``n_bins`` when ``n_bins`` is not provided:
+        ``"low"`` -> 10, ``"medium"`` -> 5, ``"high"`` -> 2.
+    n_bins:
+        If provided, overrides the severity-derived number of bins.
+    columns:
+        Indices of columns to target.  ``None`` targets all columns.
+    """
+
+    def __init__(
+        self,
+        severity: str = "medium",
+        n_bins: int | None = None,
+        columns: list[int] | None = None,
+    ) -> None:
+        if severity not in _SEVERITY_N_BINS:
+            raise ValueError(
+                f"Invalid severity '{severity}'. "
+                f"Must be one of {list(_SEVERITY_N_BINS)}."
+            )
+        self.severity = severity
+        self.n_bins = n_bins
+        self.columns = columns
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _effective_n_bins(self) -> int:
+        """Return n_bins, falling back to severity default."""
+        if self.n_bins is not None:
+            return int(self.n_bins)
+        return _SEVERITY_N_BINS[self.severity]
+
+    @staticmethod
+    def _bin_column(col_values: np.ndarray, n_bins: int) -> np.ndarray:
+        """Quantile-bin a 1-D array into integer indices 0 .. n_bins-1."""
+        edges = np.quantile(col_values, np.linspace(0.0, 1.0, n_bins + 1))
+        # Handle constant columns: all edges are identical -> all go to bin 0
+        if np.all(edges == edges[0]):
+            return np.zeros(len(col_values), dtype=float)
+        # np.digitize with edges[1:-1] gives indices 0 to n_bins-1
+        bins = np.digitize(col_values, edges[1:-1])
+        return bins.astype(float)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def corrupt(
+        self,
+        X: np.ndarray,
+        metadata: dict,
+        random_state: int,
+    ) -> tuple[np.ndarray, dict]:
+        """Bin targeted columns and update importances.
+
+        Parameters
+        ----------
+        X:
+            Feature matrix of shape ``(n_samples, n_features)``.
+        metadata:
+            Metadata dict from the DGP.  Must contain either
+            ``effective_feature_importances`` or
+            ``signal_feature_importances``.
+        random_state:
+            Integer seed.  Binning is fully deterministic given X, so
+            ``random_state`` does not affect output; it is accepted for
+            interface consistency.
+
+        Returns
+        -------
+        X_corrupted:
+            Same shape as X; targeted columns contain integer-valued floats.
+        updated_metadata:
+            Metadata with updated ``effective_feature_importances``.
+        """
+        # random_state accepted for contract consistency; binning is deterministic
+        _ = random_state
+
+        n_features = X.shape[1]
+        n_bins = self._effective_n_bins()
+
+        # Determine targeted columns
+        targeted = (
+            list(range(n_features)) if self.columns is None else list(self.columns)
+        )
+
+        # Copy X -- do not modify in-place
+        X_out = X.copy()
+        for col in targeted:
+            X_out[:, col] = self._bin_column(X[:, col], n_bins)
+
+        # Retrieve effective importances (fall back to signal importances)
+        eff = metadata.get("effective_feature_importances")
+        if eff is None:
+            eff = metadata.get("signal_feature_importances", {})
+        importances: dict[str, float] = dict(eff)
+
+        # Discount targeted column importances
+        discount = 1.0 - 1.0 / n_bins
+        for col in targeted:
+            key = f"feature_{col}"
+            importances[key] = importances.get(key, 0.0) * discount
+
+        # Re-normalize to sum to 1.0
+        total = sum(importances.values())
+        if total > 0:
+            importances = {k: v / total for k, v in importances.items()}
+
+        # Build output metadata (no in-place mutation)
+        meta_out = dict(metadata)
+        meta_out["effective_feature_importances"] = importances
+
+        return X_out, meta_out
+
+    def get_params(self) -> dict[str, object]:
+        """Return constructor parameters as a plain dict."""
+        return {
+            "severity": self.severity,
+            "n_bins": self.n_bins,
+            "columns": self.columns,
+        }
+
+
+__all__ = ["CategoricalCorruptor"]

synthbench/corruptors/collinearity.py

@@ -0,0 +1,174 @@
+"""CollinearityCorruptor -- appends correlated proxy columns to X."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from synthbench._seed import make_rng
+from synthbench.corruptors.base import BaseCorruptor
+
+_SEVERITY_NOISE_STD: dict[str, float] = {
+    "low": 0.05,
+    "medium": 0.3,
+    "high": 0.8,
+}
+
+
+class CollinearityCorruptor(BaseCorruptor, key="collinearity"):
+    """Appends proxy columns that are noisy copies of targeted features.
+
+    For each targeted column ``c``, a proxy column is generated as::
+
+        proxy = X[:, c] * scale + N(0, noise_std, n_samples)
+
+    The proxy is appended at the end of X, expanding the feature matrix
+    from ``(n_samples, n_features)`` to
+    ``(n_samples, n_features + n_targeted)``.
+
+    Feature importances are split between the original and proxy columns
+    using the coefficient of determination (r^2) of the proxy relative to
+    the original signal.
+
+    Parameters
+    ----------
+    severity:
+        Controls default ``noise_std`` when ``noise_std`` is not provided:
+        ``"low"`` -> 0.05, ``"medium"`` -> 0.3, ``"high"`` -> 0.8.
+    noise_std:
+        If provided, overrides the severity-derived noise standard deviation.
+    scale:
+        Multiplicative factor applied to the source column when generating
+        the proxy.  Defaults to 1.0.
+    columns:
+        Indices of columns to target.  ``None`` targets all columns.
+    """
+
+    def __init__(
+        self,
+        severity: str = "medium",
+        noise_std: float | None = None,
+        scale: float = 1.0,
+        columns: list[int] | None = None,
+    ) -> None:
+        if severity not in _SEVERITY_NOISE_STD:
+            raise ValueError(
+                f"Invalid severity '{severity}'. "
+                f"Must be one of {list(_SEVERITY_NOISE_STD)}."
+            )
+        self.severity = severity
+        self.noise_std = noise_std
+        self.scale = scale
+        self.columns = columns
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _effective_noise_std(self) -> float:
+        """Return noise_std, falling back to severity default."""
+        if self.noise_std is not None:
+            return float(self.noise_std)
+        return _SEVERITY_NOISE_STD[self.severity]
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def corrupt(
+        self,
+        X: np.ndarray,
+        metadata: dict,
+        random_state: int,
+    ) -> tuple[np.ndarray, dict]:
+        """Append proxy columns and update importances.
+
+        Parameters
+        ----------
+        X:
+            Feature matrix of shape ``(n_samples, n_features)``.
+        metadata:
+            Metadata dict from the DGP.  Must contain either
+            ``effective_feature_importances`` or
+            ``signal_feature_importances``.
+        random_state:
+            Integer seed for reproducibility.
+
+        Returns
+        -------
+        X_corrupted:
+            Shape ``(n_samples, n_features + n_targeted)``.
+        updated_metadata:
+            Metadata with updated ``effective_feature_importances`` and
+            ``proxy_source_map``.
+        """
+        rng = make_rng(random_state)
+        n_samples, n_features = X.shape
+        noise_std = self._effective_noise_std()
+
+        # Determine targeted columns
+        targeted = (
+            list(range(n_features)) if self.columns is None else list(self.columns)
+        )
+
+        # Build proxy columns
+        proxy_cols: list[np.ndarray] = []
+        for col in targeted:
+            signal = X[:, col] * self.scale
+            noise = rng.normal(0.0, noise_std, size=n_samples)
+            proxy_cols.append(signal + noise)
+
+        # Append proxies
+        if proxy_cols:
+            X_out = np.hstack([X, np.column_stack(proxy_cols)])
+        else:
+            X_out = X.copy()
+
+        # Build proxy_source_map
+        proxy_source_map: dict[str, str] = {}
+        for proxy_idx, source_col in enumerate(targeted):
+            proxy_key = f"feature_{n_features + proxy_idx}"
+            source_key = f"feature_{source_col}"
+            proxy_source_map[proxy_key] = source_key
+
+        # Retrieve effective importances (fall back to signal importances)
+        eff = metadata.get("effective_feature_importances")
+        if eff is None:
+            eff = metadata.get("signal_feature_importances", {})
+        importances: dict[str, float] = dict(eff)
+
+        # Split importances: original keeps (1 - r2), proxy gets r2
+        for proxy_idx, source_col in enumerate(targeted):
+            source_key = f"feature_{source_col}"
+            proxy_key = f"feature_{n_features + proxy_idx}"
+
+            col_var = float(np.var(X[:, source_col]))
+            signal_var = col_var * (self.scale**2)
+            r2 = signal_var / (signal_var + noise_std**2 + 1e-12)
+
+            original_imp = importances.get(source_key, 0.0)
+            importances[source_key] = original_imp * (1.0 - r2)
+            importances[proxy_key] = original_imp * r2
+
+        # Re-normalize to sum to 1.0
+        total = sum(importances.values())
+        if total > 0:
+            importances = {k: v / total for k, v in importances.items()}
+
+        # Build output metadata (no in-place mutation)
+        meta_out = dict(metadata)
+        meta_out["effective_feature_importances"] = importances
+        meta_out["proxy_source_map"] = proxy_source_map
+
+        return X_out, meta_out
+
+    def get_params(self) -> dict[str, object]:
+        """Return constructor parameters as a plain dict."""
+        return {
+            "severity": self.severity,
+            "noise_std": self.noise_std,
+            "scale": self.scale,
+            "columns": self.columns,
+        }
+
+
+__all__ = ["CollinearityCorruptor"]

synthbench/corruptors/label_base.py

@@ -0,0 +1,102 @@
+"""Base class for label-space corruptors.
+
+Corruptors that transform y (targets). X is read-only reference, never mutated.
+
+Concrete subclasses must:
+- Declare ``key="some_key"`` in their class signature to be auto-registered.
+- Implement
+  [corrupt_labels][synthbench.corruptors.label_base.BaseLabelCorruptor.corrupt_labels].
+- Override [get_params][synthbench.corruptors.label_base.BaseLabelCorruptor.get_params].
+
+Example::
+
+    class LabelNoiseCorruptor(BaseLabelCorruptor, key="label_noise"):
+        def corrupt_labels(self, X, y, metadata, random_state):
+            ...
+        def get_params(self):
+            return {"noise_rate": self.noise_rate}
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+import numpy as np
+
+_LABEL_CORRUPTOR_REGISTRY: dict[str, type] = {}
+
+
+class BaseLabelCorruptor(ABC):
+    """Abstract base class for all label-space corruptors.
+
+    Concrete subclasses must:
+    - Declare ``key="some_key"`` in their class signature to be auto-registered.
+    - Implement
+      [corrupt_labels][synthbench.corruptors.label_base.BaseLabelCorruptor.corrupt_labels].
+
+    Label corruptors transform y only; X is passed as a read-only reference
+    and must never be mutated.
+
+    Example::
+
+        class LabelNoiseCorruptor(BaseLabelCorruptor, key="label_noise"):
+            def corrupt_labels(self, X, y, metadata, random_state):
+                ...
+    """
+
+    def __init_subclass__(cls, key: str | None = None, **kwargs: object) -> None:
+        super().__init_subclass__(**kwargs)
+        if key is not None:
+            if key in _LABEL_CORRUPTOR_REGISTRY:
+                raise ValueError(
+                    f"Duplicate label corruptor key '{key}': already registered by "
+                    f"{_LABEL_CORRUPTOR_REGISTRY[key].__qualname__}"
+                )
+            _LABEL_CORRUPTOR_REGISTRY[key] = cls
+
+    @abstractmethod
+    def corrupt_labels(
+        self,
+        X: np.ndarray,
+        y: np.ndarray,
+        metadata: dict,
+        random_state: int,
+    ) -> tuple[np.ndarray, dict]:
+        """Apply a label-space transformation to y.
+
+        Parameters
+        ----------
+        X:
+            Feature matrix of shape (n_samples, n_features). Read-only
+            reference; must not be modified in-place.
+        y:
+            Target array of shape (n_samples,). Must not be modified in-place;
+            return a new array.
+        metadata:
+            The BenchResult metadata dict. Label corruptors may add keys but
+            must not remove or overwrite existing keys.
+        random_state:
+            Integer seed. Each corruptor derives its own RNG from this value
+            so that results are fully reproducible.
+
+        Returns
+        -------
+        y_corrupted : np.ndarray
+            Transformed target array, same shape as y.
+        updated_metadata : dict
+            Metadata dict with any label-corruptor-specific fields added.
+        """
+
+    def get_params(self) -> dict[str, object]:
+        """Return the corruptor's current configuration as a plain dict.
+
+        Concrete corruptors should override this to return their __init__
+        parameters. Used by BenchPipeline to record component provenance.
+        """
+        raise NotImplementedError(
+            f"{type(self).__qualname__}.get_params() is not implemented. "
+            "Concrete label corruptor subclasses must override this method."
+        )
+
+
+__all__ = ["BaseLabelCorruptor", "_LABEL_CORRUPTOR_REGISTRY"]