pyplasmode 1.0.0__py3-none-any.whl

pyplasmode/truth.py

@@ -0,0 +1,510 @@
+"""Truth specifications and deterministic signal materialisation."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Literal
+
+import numpy as np
+from numpy.typing import NDArray
+
+from pyplasmode._validation import identities, integer
+from pyplasmode.data import Population
+from pyplasmode.structures import FeatureSets
+
+type TruthKind = Literal["null", "sparse", "correlated", "module", "interaction", "custom"]
+
+
+@dataclass(frozen=True, slots=True)
+class RecoveryGroup:
+    """A direct feature and the explicitly admissible substitutes for its group."""
+
+    name: str
+    direct_feature: str | None
+    features: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        identities((self.name,), "group name")
+        identities(self.features, "group features")
+        if self.direct_feature is not None and self.direct_feature not in self.features:
+            raise ValueError("group direct feature must belong to its members")
+
+
+@dataclass(frozen=True, slots=True)
+class FeatureWeight:
+    """One feature's unstandardized contribution to a distributed signal."""
+
+    feature: str
+    weight: float
+
+    def __post_init__(self) -> None:
+        identities((self.feature,), "weight feature")
+        if not np.isfinite(self.weight) or self.weight == 0.0:
+            raise ValueError("truth weights must be finite and non-zero")
+
+
+@dataclass(frozen=True, slots=True)
+class MaterializedTruth:
+    """The realised signal and mechanism-specific recovery targets."""
+
+    kind: TruthKind
+    signal: NDArray[np.float64]
+    feature_universe: tuple[str, ...]
+    direct_features: tuple[str, ...] = ()
+    admissible_groups: tuple[RecoveryGroup, ...] = ()
+    weights: tuple[FeatureWeight, ...] = ()
+    graph_region: tuple[str, ...] = ()
+    center: float = 0.0
+    scale: float = 1.0
+    description: str = ""
+
+    def __post_init__(self) -> None:
+        if self.kind not in {"null", "sparse", "correlated", "module", "interaction", "custom"}:
+            raise ValueError("unsupported truth kind")
+        identities(self.feature_universe, "feature universe")
+        identities(self.direct_features, "direct features", allow_empty=True)
+        identities(
+            tuple(item.feature for item in self.weights), "weighted features", allow_empty=True
+        )
+        identities(
+            tuple(group.name for group in self.admissible_groups), "group names", allow_empty=True
+        )
+        identities(self.graph_region, "graph region", allow_empty=True)
+        declared = (
+            self.direct_features
+            + tuple(item.feature for item in self.weights)
+            + tuple(feature for group in self.admissible_groups for feature in group.features)
+            + self.graph_region
+        )
+        if not set(declared) <= set(self.feature_universe):
+            raise ValueError("truth targets must belong to the feature universe")
+        if not np.isfinite(self.center) or not np.isfinite(self.scale) or self.scale < 0.0:
+            raise ValueError("truth center and scale must be finite with non-negative scale")
+        signal = np.asarray(self.signal, dtype=np.float64)
+        if signal.ndim != 1 or not signal.size or not np.isfinite(signal).all():
+            raise ValueError("materialized truth signal must be finite and one-dimensional")
+        if self.kind == "null" and (np.any(signal != 0.0) or declared):
+            raise ValueError("null truth cannot contain signal or recovery targets")
+        copied = np.array(signal, copy=True)
+        copied.setflags(write=False)
+        object.__setattr__(self, "signal", copied)
+
+
+@dataclass(frozen=True, slots=True)
+class NullTruth:
+    """A truth with no biomarker contribution."""
+
+
+@dataclass(frozen=True, slots=True)
+class SparseTruth:
+    """An exact sparse truth selected explicitly or by seeded weak-correlation search."""
+
+    count: int | None = None
+    features: tuple[str, ...] = ()
+    weights: tuple[float, ...] = ()
+    max_absolute_correlation: float = 0.7
+
+    def __post_init__(self) -> None:
+        if (self.count is None) == (not self.features):
+            raise ValueError("SparseTruth requires exactly one of count or features")
+        if self.count is not None:
+            integer(self.count, "sparse count", minimum=1)
+        identities(self.features, "sparse features", allow_empty=True)
+        if self.weights and len(self.weights) != len(self.features):
+            raise ValueError("sparse weights require one value per explicit feature")
+        _validate_weights(self.weights)
+        if not 0.0 <= self.max_absolute_correlation < 1.0:
+            raise ValueError("max_absolute_correlation must be in [0, 1)")
+
+
+@dataclass(frozen=True, slots=True)
+class CorrelatedTruth:
+    """One direct sentinel and admissible substitutes from each declared group."""
+
+    group_names: tuple[str, ...]
+    sentinels: tuple[str, ...] = ()
+    weights: tuple[float, ...] = ()
+    signal_form: Literal["sentinels", "group_means"] = "sentinels"
+
+    def __post_init__(self) -> None:
+        identities(self.group_names, "correlated group_names")
+        identities(self.sentinels, "sentinels", allow_empty=True)
+        if self.signal_form not in {"sentinels", "group_means"}:
+            raise ValueError("signal_form must be sentinels or group_means")
+        if self.signal_form == "group_means" and self.sentinels:
+            raise ValueError("group_means has no direct sentinels")
+        if self.sentinels and len(self.sentinels) != len(self.group_names):
+            raise ValueError("sentinels must contain one feature per group")
+        if self.weights and len(self.weights) != len(self.group_names):
+            raise ValueError("correlated weights require one value per group")
+        _validate_weights(self.weights)
+
+
+@dataclass(frozen=True, slots=True)
+class ModuleTruth:
+    """A weighted state distributed across one declared feature set."""
+
+    set_name: str
+    weights: tuple[float, ...] = ()
+
+    def __post_init__(self) -> None:
+        identities((self.set_name,), "module set_name")
+        _validate_weights(self.weights)
+
+
+@dataclass(frozen=True, slots=True)
+class InteractionTruth:
+    """A bounded pairwise product or threshold interaction sensitivity."""
+
+    features: tuple[str, str]
+    operation: Literal["product", "threshold"] = "product"
+    threshold: float = 0.0
+
+    def __post_init__(self) -> None:
+        identities(self.features, "interaction features")
+        if len(self.features) != 2:
+            raise ValueError("interaction truth requires two distinct features")
+        if self.operation not in {"product", "threshold"}:
+            raise ValueError("operation must be product or threshold")
+        if not np.isfinite(self.threshold):
+            raise ValueError("interaction threshold must be finite")
+
+
+@dataclass(frozen=True, slots=True)
+class CustomSignal:
+    """A custom signal and its explicit recovery semantics."""
+
+    signal: NDArray[np.float64]
+    direct_features: tuple[str, ...] = ()
+    groups: tuple[RecoveryGroup, ...] = ()
+    weights: tuple[FeatureWeight, ...] = ()
+    graph_region: tuple[str, ...] = ()
+    description: str = ""
+
+
+type CustomTruthFunction = Callable[
+    [NDArray[np.float64], tuple[str, ...], np.random.Generator], CustomSignal
+]
+
+
+@dataclass(frozen=True, slots=True)
+class CustomTruth:
+    """A conforming callable used to materialise an extension truth."""
+
+    function: CustomTruthFunction
+
+    def __post_init__(self) -> None:
+        if not callable(self.function):
+            raise ValueError("custom truth function must be callable")
+
+
+type TruthSpec = (
+    NullTruth | SparseTruth | CorrelatedTruth | ModuleTruth | InteractionTruth | CustomTruth
+)
+
+
+def _validate_weights(weights: tuple[float, ...]) -> None:
+    if any(not np.isfinite(weight) or weight == 0.0 for weight in weights):
+        raise ValueError("truth weights must be finite and non-zero")
+
+
+def _completed_standardized(
+    population: Population, *, required_features: tuple[str, ...] = ()
+) -> NDArray[np.float64]:
+    """Median-complete observed columns and retain missing columns as constants."""
+    required = _indices(population, required_features)
+    matrix = np.array(population.X[:, required] if required_features else population.X, copy=True)
+    all_missing = np.isnan(matrix).all(axis=0)
+    unavailable = tuple(
+        feature for feature, missing in zip(required_features, all_missing, strict=False) if missing
+    )
+    if unavailable:
+        raise ValueError(f"truth features are entirely missing: {unavailable}")
+    medians = np.zeros(matrix.shape[1], dtype=np.float64)
+    observed = ~all_missing
+    medians[observed] = np.nanmedian(matrix[:, observed], axis=0)
+    missing_rows, missing_columns = np.where(np.isnan(matrix))
+    matrix[missing_rows, missing_columns] = medians[missing_columns]
+    scales = np.std(matrix, axis=0)
+    constants = tuple(
+        feature for feature, scale in zip(required_features, scales, strict=False) if scale == 0.0
+    )
+    if constants:
+        raise ValueError(f"truth features are constant: {constants}")
+    scales[scales == 0.0] = 1.0
+    return (matrix - np.mean(matrix, axis=0)) / scales
+
+
+def _indices(population: Population, features: tuple[str, ...]) -> NDArray[np.int64]:
+    positions = {feature: index for index, feature in enumerate(population.feature_ids)}
+    unknown = tuple(feature for feature in features if feature not in positions)
+    if unknown:
+        raise ValueError(f"truth contains unknown feature identities: {unknown}")
+    return np.asarray([positions[feature] for feature in features], dtype=np.int64)
+
+
+def _standardize_signal(signal: NDArray[np.float64]) -> tuple[NDArray[np.float64], float, float]:
+    if signal.ndim != 1 or not np.isfinite(signal).all():
+        raise ValueError("truth signal must be finite and one-dimensional")
+    center = float(np.mean(signal))
+    scale = float(np.std(signal))
+    if not np.isfinite(scale) or scale <= 0.0:
+        raise ValueError("a non-null truth signal must be nonconstant")
+    return (signal - center) / scale, center, scale
+
+
+def _weighted_signal(
+    standardized: NDArray[np.float64], indices: NDArray[np.int64], weights: NDArray[np.float64]
+) -> NDArray[np.float64]:
+    if not np.isfinite(weights).all() or np.all(weights == 0.0):
+        raise ValueError("truth weights must be finite and not all zero")
+    return np.asarray(standardized[:, indices] @ weights, dtype=np.float64)
+
+
+def _select_sparse(
+    standardized: NDArray[np.float64], count: int, maximum: float, rng: np.random.Generator
+) -> NDArray[np.int64]:
+    variable = np.flatnonzero(np.std(standardized, axis=0) > 0.0)
+    selected: list[int] = []
+    for candidate in rng.permutation(variable):
+        if all(
+            abs(float(np.corrcoef(standardized[:, candidate], standardized[:, prior])[0, 1]))
+            <= maximum
+            for prior in selected
+        ):
+            selected.append(int(candidate))
+        if len(selected) == count:
+            return np.asarray(selected, dtype=np.int64)
+    raise ValueError(f"could not select {count} features under max_absolute_correlation={maximum}")
+
+
+def _materialize_custom(truth: CustomTruth, population: Population, seed: int) -> MaterializedTruth:
+    readonly = np.array(population.X, copy=True)
+    readonly.setflags(write=False)
+    first = truth.function(readonly, population.feature_ids, np.random.default_rng(seed))
+    second = truth.function(readonly, population.feature_ids, np.random.default_rng(seed))
+    first_signal = np.asarray(first.signal, dtype=np.float64)
+    second_signal = np.asarray(second.signal, dtype=np.float64)
+    if first_signal.shape != (population.sample_count,):
+        raise ValueError("custom truth signal shape must equal the population row count")
+    same_metadata = (
+        first.direct_features == second.direct_features
+        and first.groups == second.groups
+        and first.weights == second.weights
+        and first.graph_region == second.graph_region
+        and first.description == second.description
+    )
+    if not np.array_equal(first_signal, second_signal, equal_nan=True) or not same_metadata:
+        raise ValueError("custom truth must be deterministic for identical inputs and seed")
+    declared = (
+        first.direct_features
+        + tuple(feature for group in first.groups for feature in group.features)
+        + tuple(item.feature for item in first.weights)
+        + first.graph_region
+    )
+    _indices(population, declared)
+    signal, center, scale = _standardize_signal(first_signal)
+    return MaterializedTruth(
+        kind="custom",
+        signal=signal,
+        feature_universe=population.feature_ids,
+        direct_features=first.direct_features,
+        admissible_groups=first.groups,
+        weights=first.weights,
+        graph_region=first.graph_region,
+        center=center,
+        scale=scale,
+        description=first.description,
+    )
+
+
+def materialize_truth(
+    truth: TruthSpec,
+    population: Population,
+    *,
+    seed: int,
+    feature_sets: FeatureSets | None = None,
+) -> MaterializedTruth:
+    """Materialise a declared mechanism on an empirical matrix.
+
+    Args:
+        truth: Built-in mechanism or deterministic custom signal function.
+        population: Numeric feature matrix and ordered identifiers.
+        seed: Non-negative integer controlling data-derived truth selection.
+        feature_sets: Named memberships required by correlated and module truths.
+
+    Returns:
+        Standardised latent signal and explicit recovery targets. The original
+        matrix is not modified. Null truth has a zero signal and no targets.
+
+    Raises:
+        ValueError: Invalid identities, weights or settings, unavailable or
+            constant required features, or an infeasible sparse selection.
+        TypeError: Unsupported specification type.
+    """
+    integer(seed, "seed")
+    if isinstance(truth, NullTruth):
+        return MaterializedTruth(
+            kind="null",
+            signal=np.zeros(population.sample_count),
+            feature_universe=population.feature_ids,
+            center=0.0,
+            scale=0.0,
+            description="No biomarker signal",
+        )
+
+    rng = np.random.default_rng(seed)
+    if isinstance(truth, SparseTruth):
+        if truth.features:
+            features = truth.features
+            standardized = _completed_standardized(population, required_features=features)
+            selected = np.arange(len(features), dtype=np.int64)
+        else:
+            if truth.count is None:  # Narrowing guard for static type checkers.
+                raise RuntimeError("sparse truth count is missing")
+            standardized = _completed_standardized(population)
+            selected = _select_sparse(
+                standardized, truth.count, truth.max_absolute_correlation, rng
+            )
+            features = tuple(population.feature_ids[index] for index in selected)
+        raw_weights = truth.weights or tuple(1.0 for _ in features)
+        weights = np.asarray(raw_weights, dtype=np.float64)
+        raw = _weighted_signal(standardized, selected, weights)
+        signal, center, scale = _standardize_signal(raw)
+        return MaterializedTruth(
+            kind="sparse",
+            signal=signal,
+            feature_universe=population.feature_ids,
+            direct_features=features,
+            weights=tuple(
+                FeatureWeight(feature, float(weight))
+                for feature, weight in zip(features, weights, strict=True)
+            ),
+            center=center,
+            scale=scale,
+            description=f"Sparse exact truth over {len(features)} features",
+        )
+
+    if isinstance(truth, CorrelatedTruth):
+        if feature_sets is None:
+            raise ValueError("CorrelatedTruth requires FeatureSets")
+        groups = tuple(feature_sets.get(name) for name in truth.group_names)
+        all_members = tuple(feature for group in groups for feature in group.members)
+        if len(set(all_members)) != len(all_members):
+            raise ValueError("correlated truth requires disjoint groups")
+        for group in groups:
+            _indices(population, group.members)
+        sentinels = (
+            (
+                truth.sentinels
+                or tuple(
+                    group.members[int(rng.integers(0, len(group.members)))] for group in groups
+                )
+            )
+            if truth.signal_form == "sentinels"
+            else ()
+        )
+        if any(
+            sentinel not in group.members
+            for sentinel, group in zip(sentinels, groups, strict=False)
+        ):
+            raise ValueError("every correlated sentinel must belong to its declared group")
+        required = (
+            sentinels
+            if truth.signal_form == "sentinels"
+            else tuple(dict.fromkeys(feature for group in groups for feature in group.members))
+        )
+        standardized = _completed_standardized(population, required_features=required)
+        positions = {feature: index for index, feature in enumerate(required)}
+        weights = np.asarray(truth.weights or tuple(1.0 for _ in groups), dtype=np.float64)
+        if truth.signal_form == "sentinels":
+            selected = np.arange(len(sentinels), dtype=np.int64)
+            raw = _weighted_signal(standardized, selected, weights)
+            feature_weights = tuple(
+                FeatureWeight(feature, float(weight))
+                for feature, weight in zip(sentinels, weights, strict=True)
+            )
+        else:
+            group_states = np.column_stack(
+                [
+                    np.mean(
+                        standardized[:, [positions[feature] for feature in group.members]], axis=1
+                    )
+                    for group in groups
+                ]
+            )
+            raw = np.asarray(group_states @ weights, dtype=np.float64)
+            contributions: dict[str, float] = dict.fromkeys(required, 0.0)
+            for group, weight in zip(groups, weights, strict=True):
+                for feature in group.members:
+                    contributions[feature] += float(weight) / len(group.members)
+            feature_weights = tuple(
+                FeatureWeight(feature, weight)
+                for feature, weight in contributions.items()
+                if weight != 0.0
+            )
+        signal, center, scale = _standardize_signal(raw)
+        recovery_groups = tuple(
+            RecoveryGroup(group.name, sentinels[index] if sentinels else None, group.members)
+            for index, group in enumerate(groups)
+        )
+        return MaterializedTruth(
+            kind="correlated",
+            signal=signal,
+            feature_universe=population.feature_ids,
+            direct_features=sentinels,
+            admissible_groups=recovery_groups,
+            weights=feature_weights,
+            center=center,
+            scale=scale,
+            description=f"Correlated {truth.signal_form} truth over {len(groups)} groups",
+        )
+
+    if isinstance(truth, ModuleTruth):
+        if feature_sets is None:
+            raise ValueError("ModuleTruth requires FeatureSets")
+        feature_set = feature_sets.get(truth.set_name)
+        standardized = _completed_standardized(population, required_features=feature_set.members)
+        selected = np.arange(len(feature_set.members), dtype=np.int64)
+        raw_weights = truth.weights or tuple(1.0 for _ in feature_set.members)
+        if len(raw_weights) != len(feature_set.members):
+            raise ValueError("module weights require one value per set member")
+        weights = np.asarray(raw_weights, dtype=np.float64)
+        raw = _weighted_signal(standardized, selected, weights)
+        signal, center, scale = _standardize_signal(raw)
+        return MaterializedTruth(
+            kind="module",
+            signal=signal,
+            feature_universe=population.feature_ids,
+            weights=tuple(
+                FeatureWeight(feature, float(weight))
+                for feature, weight in zip(feature_set.members, weights, strict=True)
+            ),
+            center=center,
+            scale=scale,
+            description=f"Weighted module truth: {feature_set.name}",
+        )
+
+    if isinstance(truth, InteractionTruth):
+        standardized = _completed_standardized(population, required_features=truth.features)
+        left = standardized[:, 0]
+        right = standardized[:, 1]
+        if truth.operation == "product":
+            raw = left * right
+        else:
+            raw = ((left > truth.threshold) & (right > truth.threshold)).astype(float)
+        signal, center, scale = _standardize_signal(raw)
+        return MaterializedTruth(
+            kind="interaction",
+            signal=signal,
+            feature_universe=population.feature_ids,
+            direct_features=truth.features,
+            center=center,
+            scale=scale,
+            description=f"Pairwise {truth.operation} interaction",
+        )
+
+    if isinstance(truth, CustomTruth):
+        return _materialize_custom(truth, population, seed)
+    raise TypeError(f"unsupported truth specification: {type(truth).__name__}")

pyplasmode-1.0.0.dist-info/METADATA

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: pyplasmode
+Version: 1.0.0
+Summary: Simulate biomarker signals and evaluate prediction and feature recovery.
+Project-URL: Repository, https://github.com/BradSegal/PyPlasmode
+Project-URL: Documentation, https://github.com/BradSegal/PyPlasmode/tree/main/docs
+Project-URL: Issues, https://github.com/BradSegal/PyPlasmode/issues
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: <3.15,>=3.12
+Requires-Dist: numpy<3,>=2.0
+Requires-Dist: scikit-learn<2,>=1.6
+Requires-Dist: scipy<2,>=1.14
+Provides-Extra: validation
+Requires-Dist: matplotlib<4,>=3.10; extra == 'validation'
+Requires-Dist: statsmodels<0.16,>=0.14; extra == 'validation'
+Description-Content-Type: text/markdown
+
+# PyPlasmode
+
+PyPlasmode benchmarks the reliability of biomarker discovery. A model can predict disease
+accurately while selecting proteins that only track the underlying signal. To evaluate its
+explanations, you need a comparison in which the relevant features are known. PyPlasmode
+creates that comparison by generating outcomes from specified effects within your measurements.
+
+Use it with your existing modelling workflow: generate a dataset, fit and tune your models,
+then evaluate their predictions, feature rankings or selected panels.
+
+[![From observed measurements to simulated outcomes, model predictions and feature recovery](docs/assets/concepts/plasmode-workflow.png)](docs/methods.md)
+
+The same generated dataset supports two comparisons: predictions against outcomes, and
+selected features against the signal that generated them.
+
+Explore the [visual gallery](docs/gallery.md) for signal patterns, correlated-feature recovery
+and the five outcome families.
+
+The [biomarker tutorial](docs/tutorial.md) follows a complete example from correlated
+measurements through model fitting, attribution and recovery above chance.
+
+## Installation
+
+Requires Python 3.12-3.14. Install from GitHub:
+
+```bash
+python -m pip install "git+https://github.com/BradSegal/PyPlasmode.git@v1.0.0"
+```
+
+The runtime dependencies are NumPy, SciPy and scikit-learn. To include the reference
+validation and survival examples, install the validation extra:
+
+```bash
+python -m pip install "PyPlasmode[validation] @ git+https://github.com/BradSegal/PyPlasmode.git@v1.0.0"
+```
+
+## Ten-minute example
+
+```python
+import numpy as np
+from sklearn.linear_model import LogisticRegression
+import pyplasmode as ppm
+
+rng = np.random.default_rng(1)
+population = ppm.Population(
+    rng.normal(size=(2_000, 100)),
+    tuple(f"protein_{index}" for index in range(100)),
+)
+
+partition = ppm.partition_population(
+    population,
+    training_fraction=0.6,
+    validation_fraction=0.2,
+    seed=7,
+)
+samples = ppm.generate_partitioned(
+    partition,
+    truth=ppm.SparseTruth(features=("protein_3", "protein_17", "protein_42")),
+    outcome=ppm.BinaryOutcome(probability=0.15, odds_ratio=2.0),
+    sample_sizes=ppm.PartitionSampleSizes(1_200, 400, 400),
+    sampling_method="without_replacement",
+    seed=42,
+)
+
+train, test = samples.training, samples.evaluation
+model = LogisticRegression(max_iter=1_000).fit(train.X, train.outcome.values)
+ranking = tuple(train.feature_ids[index] for index in np.argsort(-np.abs(model.coef_[0])))
+
+recovery = ppm.evaluate_ranking(ranking, train.truth, depths=(10, 20, 50))
+prediction = ppm.evaluate_prediction(
+    test.outcome.values,
+    model.predict_proba(test.X)[:, 1],
+    metric="roc_auc",
+)
+print(recovery.at_depth[0].recall)
+print(prediction.value)
+```
+
+Recall measures how many of the three generating features appear in the model's top ten;
+AUC measures prediction on held-out participants. Repeat the comparison with different seeds
+to estimate average performance and its Monte Carlo uncertainty.
+
+Source participants are split before resampling, keeping training, validation and test
+rows separate. This example uses a fixed model; the validation sample is available for
+hyperparameter tuning. See [Methods](docs/methods.md) for the generation process.
+
+## What can be varied
+
+- **Signal:** null, sparse features, correlated groups, distributed modules, pairwise
+  interactions or a custom function.
+- **Outcome:** binary probability, continuous mean and spread, count rate, ordinal category
+  probabilities or cumulative event risks at native-time horizons.
+- **Evaluation:** feature and group recovery, weighted-module and graph-region coverage,
+  signal reconstruction, prediction accuracy, panel performance and ranking stability.
+  Additional functions handle tied scores, incomplete selections and matched chance references.
+
+Start with [Methods](docs/methods.md), then choose a [signal](docs/truths.md) and
+[outcome](docs/outcomes.md). The [evaluation guide](docs/evaluation.md) defines each result.
+The [validation example](docs/validation.md) checks the generators and recovery metrics against
+known values and reference estimators.
+
+The executable [quickstart](https://github.com/BradSegal/PyPlasmode/blob/main/examples/quickstart.py),
+[survival example](https://github.com/BradSegal/PyPlasmode/blob/main/examples/survival.py)
+and [custom signal](https://github.com/BradSegal/PyPlasmode/blob/main/examples/custom_signal.py)
+use synthetic inputs. The [documentation](https://github.com/BradSegal/PyPlasmode/tree/main/docs)
+includes the generation methods, evaluation definitions and API reference.
+
+## Working with empirical data
+
+Resampling preserves the source data's feature relationships and missingness patterns.
+It can reproduce individual records, so generated datasets require the same privacy protections
+as their source. See [Data handling](docs/privacy-and-limitations.md).
+
+## Licence
+
+PyPlasmode uses the [BSD 3-Clause License](LICENSE).

pyplasmode-1.0.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+pyplasmode/__init__.py,sha256=rja5bwpPzlCbiy4LFqxW20Ae80GbhscZeDqVm9BQFSM,4050
+pyplasmode/_validation.py,sha256=Cpz2cPvIbNE4huu8SWbDPyhnniAlxV_D5NCqqK8KTRI,1239
+pyplasmode/data.py,sha256=t8lGLhjKTp_R52eTDE8KG_NTfyiXUBZXpmSXN4Bnw44,9053
+pyplasmode/evaluate.py,sha256=r1V-3EOg6SGLQSFTfa0n5qveFoXobUAYAIVnOPCH49Q,15504
+pyplasmode/generate.py,sha256=S7qMj_uq06b1ah9Ctu3ad-YA6XjmGPR4m2XgNIwt9gw,12166
+pyplasmode/nominations.py,sha256=P0kZ3ihp80Ja6fvDHqqki-tilbYgbsCE83dKDkfmZQA,23338
+pyplasmode/outcomes.py,sha256=6Rv594rEnzLFgsFQwYysd4C_lQ1Sk53yWMdm6tN-i68,27890
+pyplasmode/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyplasmode/results.py,sha256=yBh41GeFKKcb5Fa6Gxo-0Pi8X4OpvZg4KhcHDpK70yM,4288
+pyplasmode/structures.py,sha256=skBF1lOx-wl9fkMiAYleEFHyOZGliYY_Fp3rx7rQ66s,4545
+pyplasmode/truth.py,sha256=GVCbYjxdGjJouv6VRjhjCCTsQXB_mBN04DkmDEhAuJs,21237
+pyplasmode-1.0.0.dist-info/METADATA,sha256=IU5rU9SFmqo4N0j960Jnf6cRbsxdFMtxrRZ_kiFAsX4,6119
+pyplasmode-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+pyplasmode-1.0.0.dist-info/licenses/LICENSE,sha256=e2PYeltfQUlLtcYi9YJ91fEgDiEhCEp0BKvf-swZzq8,1531
+pyplasmode-1.0.0.dist-info/RECORD,,

pyplasmode-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any