pyplasmode 1.0.0__tar.gz

pyplasmode-1.0.0/.gitignore

@@ -0,0 +1,14 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage*
+htmlcov/
+dist/
+build/
+site/
+uv.lock
+.env*
+validation-output/

pyplasmode-1.0.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 1.0.0
+
+First public release. PyPlasmode provides outcome generation, feature-recovery evaluation,
+worked examples and reference validation for biomarker benchmarking.
+
+### Included in this release
+
+- Empirical complete-row resampling and source-partitioned generation.
+- Null, sparse, correlated-group, module, interaction and custom signals.
+- Five outcome families calibrated in observable units.
+- Recovery, prediction, panel, reconstruction and rank-stability evaluation.
+- API documentation, worked examples, validation figures and cross-platform CI.
+- A visual gallery of signal shapes, correlated-feature recovery and outcome families,
+  with editable vector figures and an executable source-data example.
+- Python 3.12-3.14 and scikit-learn 1.6 through the current 1.x series.
+- BSD 3-Clause licensing.

pyplasmode-1.0.0/CITATION.cff

@@ -0,0 +1,20 @@
+cff-version: 1.2.0
+message: "If you use PyPlasmode in your research, please cite this software using the metadata below."
+title: "PyPlasmode"
+type: software
+version: 1.0.0
+repository-code: "https://github.com/BradSegal/PyPlasmode"
+license: BSD-3-Clause
+authors:
+  - family-names: Segal
+    given-names: Bradley
+  - family-names: Fieggen
+    given-names: Joshua
+  - family-names: Simond
+    given-names: Greg
+  - family-names: Belgrave
+    given-names: Danielle
+  - family-names: Clifton
+    given-names: David
+  - family-names: Clifton
+    given-names: Lei

pyplasmode-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing
+
+Contributions to generators, evaluation functions, documentation and examples are welcome.
+For a new signal or outcome family, describe the intended use and mathematical definition
+in an issue before implementing it.
+
+From a checkout, install a supported Python version (3.12-3.14) and uv, then run:
+
+```bash
+uv sync --extra validation --group docs
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src/pyplasmode
+uv run mkdocs build --strict
+uv run python -m build
+uv run twine check --strict dist/*
+uv run check-wheel-contents dist/*.whl
+```
+
+Run `python examples/validation_vignette.py --output validation-output` to regenerate the
+synthetic validation figures and tables. The `validation` extra is included in the setup above.
+
+The local uv lock records your development environment. Supported dependency ranges are
+listed in `pyproject.toml`.
+
+## Changes and support
+
+Use the repository's issue tracker for bug reports, questions and feature proposals. For a bug,
+include dependency versions, the expected result and a small synthetic reproducer. Keep
+participant data and credentials out of reports. Send security-sensitive reports privately
+to the repository maintainer.
+
+Add a focused regression test for bug fixes. Generator changes also need checks of their
+distributional properties, including null signals and a reference calculation or estimator.
+Integration tests exercise complete user workflows; the examples show how to combine the
+library with model fitting, tuning and explanation tools.
+
+## Releases and compatibility
+
+Record public changes in the changelog. Incompatible API or statistical-definition changes
+increment the major version; compatible additions increment the minor version, and fixes
+increment the patch version. Explain corrections that affect numerical results in the release notes.
+Record random seeds and dependency versions when sharing reproducible analyses.
+
+The CI matrix covers minimum numerical dependencies on Python 3.12 and current dependencies
+on supported Python versions, with Linux, Windows and macOS jobs. Test dependency changes
+against this matrix. Build release artifacts from the tagged version after CI passes.

pyplasmode-1.0.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, PyPlasmode contributors
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pyplasmode-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,116 @@
+# 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/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,9 @@
+# Third-party notices
+
+PyPlasmode depends on NumPy, SciPy and scikit-learn. These dependencies are not vendored in
+the PyPlasmode source distribution or wheel and remain subject to their own licences. Their
+installed versions can be recorded with `python -m pip freeze`. The source distribution
+declares supported ranges rather than shipping an experiment-specific lock file.
+
+The BSD 3-Clause License for PyPlasmode does not relicense empirical input data, generated
+row-level plasmodes or third-party software.

pyplasmode-1.0.0/docs/api.md

@@ -0,0 +1,48 @@
+# API reference
+
+The common entry points are exported from `pyplasmode`. Matrices have shape
+`(participants, features)`; `feature_ids` supplies one unique string per column.
+Generated arrays are read-only. Convert result dataclasses to plain records with
+`dataclasses.asdict` for your reporting workflow.
+
+Use `generate` for one sample or `partition_population` followed by
+`generate_partitioned` for source-disjoint development and evaluation. Access
+`outcome.values` for binary, continuous and count outcomes, `outcome.codes` for
+ordinal outcomes, and `outcome.time` plus `outcome.event` for survival outcomes.
+Survival times are in days; latent event and censoring times beyond administrative
+follow-up are represented by infinity.
+
+The rendered reference includes signatures, types and result fields. See the
+methods and evaluation guides for the scientific definitions.
+
+## Populations and sampling
+
+::: pyplasmode.data
+
+## Generation
+
+::: pyplasmode.generate
+
+## Truth specifications
+
+::: pyplasmode.truth
+
+## Outcome specifications and results
+
+::: pyplasmode.outcomes
+
+## Feature sets and graphs
+
+::: pyplasmode.structures
+
+## Ranking and prediction evaluation
+
+::: pyplasmode.evaluate
+
+## Fractional nominations and matched references
+
+::: pyplasmode.nominations
+
+## Evaluation results
+
+::: pyplasmode.results

pyplasmode-1.0.0/docs/assets/concepts/README.md

@@ -0,0 +1,10 @@
+# Concept diagrams
+
+Bradley Segal supplied these diagrams for the PyPlasmode documentation and manuscript.
+The original vector PDFs are preserved; PNG copies provide browser previews.
+
+- `plasmode-workflow.pdf`: supplied as `Biomarkers (2).pdf`.
+- `signal-recovery.pdf`: supplied as `Biomarkers (3).pdf`.
+
+The captions in the documentation explain the simulated disease score and distinguish
+true contributors from proteins selected by a fitted model.

pyplasmode-1.0.0/docs/assets/patterns/correlated-recovery.csv

@@ -0,0 +1,25 @@
+panel,order,depth,recovery
+b,Generator first,1,1.0
+c,Generator first,1,1.0
+b,Generator first,2,1.0
+c,Generator first,2,1.0
+b,Generator first,3,1.0
+c,Generator first,3,1.0
+b,Generator first,4,1.0
+c,Generator first,4,1.0
+b,Generator first,5,1.0
+c,Generator first,5,1.0
+b,Generator first,6,1.0
+c,Generator first,6,1.0
+b,Substitute first,1,0.0
+c,Substitute first,1,1.0
+b,Substitute first,2,0.0
+c,Substitute first,2,1.0
+b,Substitute first,3,0.0
+c,Substitute first,3,1.0
+b,Substitute first,4,0.0
+c,Substitute first,4,1.0
+b,Substitute first,5,0.0
+c,Substitute first,5,1.0
+b,Substitute first,6,1.0
+c,Substitute first,6,1.0