robustsignalmaker 0.2.0__py3-none-any.whl

robustsignalmaker/__init__.py

@@ -0,0 +1,188 @@
+"""RobustSignalMaker: NaN-aware, leakage-free stability selection for signals.
+
+Third sibling of RobustModelMaker (tabular columns) and RobustPixelMaker
+(image patches): RSM identifies the important parts of scientific signals and
+spectra (time-, space-, mass-series) to retain and removes the rest, with
+missing data treated as absent evidence rather than something to fabricate.
+See RSM_PLAN.md for the design and build order.
+"""
+from __future__ import annotations
+
+from .config import RSMConfig, fit_count
+from .metrics import (
+    BaselineComparison,
+    adjusted_jaccard,
+    expected_jaccard,
+    jaccard,
+    mean_pairwise_jaccard,
+    paired_comparison,
+    rmse_from_score,
+    score_predictions,
+)
+from .masking import (
+    SoftMaskSelector,
+    loss_and_dz,
+    mask_data_gradient,
+    renormalised_gated_forward,
+)
+from .nested_cv import (
+    BootstrapMaskFoldEstimator,
+    EnsembleMaskFoldEstimator,
+    FoldEstimator,
+    FullSignalFoldEstimator,
+    NestedCV,
+    SoftMaskFoldEstimator,
+    infer_task,
+    make_inner_splitter,
+    make_outer_splitter,
+)
+from .representations import (
+    GaussianScale1D,
+    RandomConv1D,
+    SavGolDerivative,
+    SegmentMean,
+    SegmentStats,
+    default_ensemble,
+)
+from .reproducibility import (
+    BOOTSTRAP_OFFSET,
+    INNER_OFFSET,
+    REPEAT_STRIDE,
+    REPRESENTATION_OFFSET,
+    Seeds,
+    set_global_seed,
+)
+from .models import (
+    ALGORITHMS,
+    ExternalRefit,
+    PLSDA,
+    make_refit_model,
+    refit_features,
+)
+from .results import RSMResult
+from .segments import SegmentGrid
+from .selection import (
+    BootstrapMaskSelector,
+    RepresentationEnsembleSelector,
+    complementary_pair,
+    observation_groups,
+    resample_indices,
+)
+from .tuning import lam_for_coverage, lam_frontier
+from .synthetic import (
+    SignalControl,
+    drop_labels,
+    make_signal_control,
+    mask_band_by_group,
+    mask_dropout_stretches,
+    mask_saturation_censor,
+    mask_scattered,
+)
+from .validity import (
+    InsufficientEvidenceError,
+    MissingnessInformativeWarning,
+    StandardisationStats,
+    as_validity,
+    fabricated_edge,
+    fill_mean,
+    fill_zero,
+    is_contrast_filter,
+    masked_mean,
+    masked_standardise,
+    masked_standardise_fit,
+    masked_std,
+    missingness_association,
+    observation_support,
+    renormalised_convolve1d,
+    renormalised_dot,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "__version__",
+    # config
+    "RSMConfig",
+    "fit_count",
+    # reproducibility
+    "Seeds",
+    "set_global_seed",
+    "BOOTSTRAP_OFFSET",
+    "REPRESENTATION_OFFSET",
+    "INNER_OFFSET",
+    "REPEAT_STRIDE",
+    # validity
+    "InsufficientEvidenceError",
+    "MissingnessInformativeWarning",
+    "StandardisationStats",
+    "as_validity",
+    "masked_mean",
+    "masked_std",
+    "masked_standardise_fit",
+    "masked_standardise",
+    "renormalised_convolve1d",
+    "renormalised_dot",
+    "is_contrast_filter",
+    "observation_support",
+    "missingness_association",
+    "fill_zero",
+    "fill_mean",
+    "fabricated_edge",
+    # segments
+    "SegmentGrid",
+    # masking
+    "SoftMaskSelector",
+    "renormalised_gated_forward",
+    "mask_data_gradient",
+    "loss_and_dz",
+    # representations
+    "SegmentMean",
+    "SegmentStats",
+    "SavGolDerivative",
+    "GaussianScale1D",
+    "RandomConv1D",
+    "default_ensemble",
+    # nested CV and results
+    "NestedCV",
+    "FoldEstimator",
+    "SoftMaskFoldEstimator",
+    "BootstrapMaskFoldEstimator",
+    "FullSignalFoldEstimator",
+    "infer_task",
+    "make_outer_splitter",
+    "make_inner_splitter",
+    "RSMResult",
+    # refit model zoo
+    "ALGORITHMS",
+    "make_refit_model",
+    "PLSDA",
+    "ExternalRefit",
+    "refit_features",
+    # selection
+    "BootstrapMaskSelector",
+    "RepresentationEnsembleSelector",
+    "EnsembleMaskFoldEstimator",
+    "resample_indices",
+    "complementary_pair",
+    "observation_groups",
+    # tuning
+    "lam_frontier",
+    "lam_for_coverage",
+    # synthetic
+    "SignalControl",
+    "make_signal_control",
+    "mask_scattered",
+    "mask_dropout_stretches",
+    "mask_band_by_group",
+    "mask_saturation_censor",
+    "drop_labels",
+    # metrics
+    "score_predictions",
+    "rmse_from_score",
+    "jaccard",
+    "expected_jaccard",
+    "adjusted_jaccard",
+    "mean_pairwise_jaccard",
+    "BaselineComparison",
+    "paired_comparison",
+]

robustsignalmaker/config.py

@@ -0,0 +1,91 @@
+"""Configuration: user-facing knobs with robust defaults, and the fit-cost model.
+
+Design constraints (RSM_PLAN.md sec.6):
+  * numpy-only: no torch, no device management. RPM's device detection is
+    deliberately not ported; every fit is a hand-derived-gradient numpy loop.
+  * User-defined where possible with robust defaults: every knob here has a
+    sane default. The evidence thresholds are scientific choices adopted with
+    the user (RSM_PLAN.md sec.11) and are scheduled for a sensitivity sweep in
+    Milestone 8 before being considered final.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, asdict
+
+
+@dataclass
+class RSMConfig:
+    """All user-facing knobs with robust defaults.
+
+    Fields beyond the Milestone-1 scaffold are declared here so the config
+    surface is stable as later milestones land (RPM convention).
+    """
+
+    # --- selection unit (sec.2) ---
+    segment: int = 16  # points per segment; 1 gives exact point-wise mode
+    channel_mode: str = "joint"  # joint | per_channel (per_channel is a later extension)
+
+    # --- cross-validation ---
+    k_outer: int = 5
+    l_inner: int = 5
+    repeated_outer_cv: int = 1
+    n_iter: int = 20  # randomized hyperparameter configurations per inner CV
+
+    # --- stability selection ---
+    n_bootstrap: int = 20
+    n_representations: int = 4
+    tau: float = 0.7  # stability threshold (RMM default)
+    lam: float = 0.03  # mask sparsity strength
+    subsample: str = "bootstrap"  # bootstrap | half | complementary
+
+    # --- masking / gates ---
+    gate: str = "hardconcrete"  # hardconcrete | sigmoid
+    tv: float = 0.0  # 1D total-variation prior strength (contiguous bands)
+
+    # --- evidence thresholds (adopted defaults; M8 sensitivity sweep) ---
+    min_valid_frac: float = 0.5  # segment observation fraction below which a
+    #                              (sample, segment) feature is ineligible
+    rho_min: float = 0.1  # per-sample observed-evidence floor; below it a
+    #                       prediction is nan, never an amplified guess
+    o_min: float = 0.1  # per-resample segment support floor for assessability
+    a_min: float = 0.5  # fraction of resamples that must assess a segment
+    #                     before pi is reported as a number rather than nan.
+    #                     Measured (FINDINGS sec.10): this binds only when
+    #                     the observation patterns are too varied to group.
+    #                     With groups detected, resampling draws a fixed
+    #                     count per stratum, support is deterministic, and
+    #                     a_min cannot act.
+    o_floor: float = 0.2  # floor for observation-scaled sparsity penalty
+    n_min_hard: int = 8  # effective sample size below which a segment-channel
+    #                      is unassessable (excluded, reported)
+    n_min_warn: int = 30  # effective sample size below which it is flagged
+
+    # --- missing y ---
+    use_unlabelled_stats: bool = False  # opt-in: unlabelled TRAINING rows may
+    #                                     contribute to X-only statistics
+
+    # --- execution ---
+    n_jobs: int = 1
+    random_state: int = 0
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def fit_count(
+    k_outer: int,
+    repeated_outer_cv: int,
+    n_representations: int,
+    n_bootstrap: int,
+    n_iter: int,
+    l_inner: int,
+) -> int:
+    """Total model-fit count (RPM's extension of RMM Eq.3, unchanged for 1D).
+
+    F = K * R_out * (R_rep * B + n_iter * L + 1)  +  (R_rep * B + n_iter * L + 1)
+
+    The trailing term is the final selection + final inner search + final
+    refit on all training data. Use this to size runs before launching.
+    """
+    per = n_representations * n_bootstrap + n_iter * l_inner + 1
+    return k_outer * repeated_outer_cv * per + per