BayesianEstimationTool 1.0.1__tar.gz → 1.0.2__tar.gz

{bayesianestimationtool-1.0.1 → bayesianestimationtool-1.0.2}/BayesianEstimationTool.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: BayesianEstimationTool
-Version: 1.0.1
+Version: 1.0.2
 Summary: Hierarchical Bayesian estimation and prediction for mechanistic models
 License-Expression: Apache-2.0
 Project-URL: Repository, https://github.com/rafaelrbravo/BayesianEstimationTool
@@ -15,6 +15,8 @@ Dynamic: license-file
 
 # BayesianEstimationTool (BET)
 
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23431103.svg)](https://doi.org/10.5281/zenodo.23431103)
+
 BayesianEstimationTool fits population-level parameters and individual-specific latent variables with NumPyro inference methods.
 
 ## Documentation
@@ -37,25 +39,19 @@ The GitHub Actions test workflow regenerates the PDFs (and the Python-authored c
 
 ## Installation
 
-BET requires Python 3.10 or newer. Install the latest version from [PyPI](https://pypi.org/project/BayesianEstimationTool/):
+BET requires Python 3.10 or newer. Install from [PyPI](https://pypi.org/project/BayesianEstimationTool/):
 
 ```bash
 python -m pip install BayesianEstimationTool
 ```
 
-To install the specific first release:
-
-```bash
-python -m pip install BayesianEstimationTool==1.0.1
-```
-
-Alternatively, install directly from the tagged GitHub source:
+Alternatively, install the latest source directly from GitHub:
 
 ```bash
-python -m pip install "git+https://github.com/rafaelrbravo/BayesianEstimationTool.git@v1.0.1"
+python -m pip install "git+https://github.com/rafaelrbravo/BayesianEstimationTool.git"
 ```
 
-You can also download a wheel (`.whl`) or source archive (`.tar.gz`) from [GitHub Releases](https://github.com/rafaelrbravo/BayesianEstimationTool/releases) and install it with `python -m pip install PATH_TO_DOWNLOADED_FILE`. These release assets become available after publishing.
+You can also download a wheel (`.whl`) or source archive (`.tar.gz`) from [GitHub Releases](https://github.com/rafaelrbravo/BayesianEstimationTool/releases) and install it with `python -m pip install PATH_TO_DOWNLOADED_FILE`.
 
 Verify installation:
 
@@ -67,10 +63,26 @@ For editable development from a source checkout, run `python -m pip install -e .
 
 See the manual for the minimal model and training examples.
 
+## Bundled examples and PDF documentation
+
+After installing BET, copy its bundled runnable examples and PDF manual/cheatsheet to an editable folder in the current directory (no GitHub download needed):
+
+```bash
+python -m BayesianEstimationTool.ExampleInstaller
+```
+
+To select a different parent directory:
+
+```bash
+python -m BayesianEstimationTool.ExampleInstaller ~/Documents
+```
+
+This creates `BET-Examples/` with the six Python examples and a `Documentation/` subfolder containing `Manual.pdf` and `Cheatsheet.pdf`. Run a script with `python BET-Examples/1_SimpleExampleNuts.py`. The installer refuses to overwrite an existing `BET-Examples/` directory. The installer is available in package builds that include bundled examples and documentation.
+
 ## How to cite
 
 If you use BET in your research, please cite:
 
-Bravo, R., Tercan, B., Lima, E., Aguilar, B., & Yankeelov, T. (2026). *BayesianEstimationTool* (Version 1.0.1) [Computer software]. https://github.com/rafaelrbravo/BayesianEstimationTool
+Bravo, R., Tercan, B., Lima, E., Aguilar, B., & Yankeelov, T. (2026). *BayesianEstimationTool* (Version 1.0.2) [Computer software]. https://doi.org/10.5281/zenodo.23431103
 
-GitHub also provides a **Cite this repository** option using [CITATION.cff](CITATION.cff).
+This DOI identifies all versions of BET. GitHub also provides a **Cite this repository** option using [CITATION.cff](CITATION.cff).

{bayesianestimationtool-1.0.1 → bayesianestimationtool-1.0.2}/BayesianEstimationTool.egg-info/SOURCES.txt

@@ -1,5 +1,6 @@
 BayesianEstimationTool.py
 BayesianEstimationTool_CheatSheet.py
+ExampleInstaller.py
 LICENSE
 Method.py
 MethodValidation.py
@@ -10,16 +11,33 @@ __init__.py
 pyproject.toml
 ./BayesianEstimationTool.py
 ./BayesianEstimationTool_CheatSheet.py
+./ExampleInstaller.py
 ./Method.py
 ./MethodValidation.py
 ./NutsMethod.py
 ./SviMethod.py
 ./__init__.py
+./Examples/1_SimpleExampleNuts.py
+./Examples/2_SimpleExampleSvi.py
+./Examples/3_SaveExampleNuts.py
+./Examples/4_LoadExampleNuts.py
+./Examples/5_SaveExampleSvi.py
+./Examples/6_LoadExampleSvi.py
+./docs/Cheatsheet.pdf
+./docs/Manual.pdf
 BayesianEstimationTool.egg-info/PKG-INFO
 BayesianEstimationTool.egg-info/SOURCES.txt
 BayesianEstimationTool.egg-info/dependency_links.txt
 BayesianEstimationTool.egg-info/requires.txt
 BayesianEstimationTool.egg-info/top_level.txt
+Examples/1_SimpleExampleNuts.py
+Examples/2_SimpleExampleSvi.py
+Examples/3_SaveExampleNuts.py
+Examples/4_LoadExampleNuts.py
+Examples/5_SaveExampleSvi.py
+Examples/6_LoadExampleSvi.py
+docs/Cheatsheet.pdf
+docs/Manual.pdf
 tests/test_custom_method.py
 tests/test_estimator_integration.py
 tests/test_estimator_validation.py

bayesianestimationtool-1.0.2/ExampleInstaller.py

@@ -0,0 +1,41 @@
+"""Copy bundled BET examples and PDF documentation into an editable folder."""
+import argparse
+from pathlib import Path
+import shutil
+import sys
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Copy bundled BET examples and documentation.")
+    parser.add_argument("path", nargs="?", default=".", help="Parent directory for BET-Examples (default: current directory)")
+    args = parser.parse_args()
+    package = Path(__file__).resolve().parent
+    source = package / "Examples"
+    docs = package / "docs"
+    parent = Path(args.path).expanduser().resolve()
+    target = parent / "BET-Examples"
+    if not parent.is_dir():
+        print(f"Parent directory does not exist: {parent}", file=sys.stderr)
+        return 1
+    if not source.is_dir() or not list(source.glob("*.py")):
+        print("BET examples are missing from this installation.", file=sys.stderr)
+        return 1
+    pdfs = sorted(docs.glob("*.pdf")) if docs.is_dir() else []
+    if not pdfs:
+        print("BET documentation PDFs are missing from this installation.", file=sys.stderr)
+        return 1
+    if target.exists():
+        print(f"Destination already exists: {target}\\nNothing was overwritten.", file=sys.stderr)
+        return 1
+    shutil.copytree(source, target)
+    docs_target = target / "Documentation"
+    docs_target.mkdir()
+    for pdf in pdfs:
+        shutil.copy2(pdf, docs_target / pdf.name)
+    print(f"Copied BET examples and documentation PDFs to {target}")
+    print("Run an example with: python BET-Examples/1_SimpleExampleNuts.py")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bayesianestimationtool-1.0.2/Examples/1_SimpleExampleNuts.py

@@ -0,0 +1,149 @@
+import numpyro as npo
+npo.set_host_device_count(4)
+
+import jax.numpy as jnp
+import numpyro.distributions as dist
+from jax import random
+
+import BayesianEstimationTool as bet
+
+
+# ---------------------------------------------------------------------
+# Generate 10 synthetic patient trajectories
+# ---------------------------------------------------------------------
+
+keyG,keyNoise=random.split(random.PRNGKey(2),2)
+
+nPatients=10
+nTimes=8
+times=jnp.linspace(0,10,nTimes)
+
+# True population:
+# mean growth rate = 0.15
+# std growth rate  = 0.03
+
+trueG=0.15+0.03*random.normal(keyG,(nPatients,))
+
+# Give patients slightly different initial tumor sizes.
+
+v0=jnp.linspace(0.8,1.2,nPatients)
+trueTumorSize=v0[:,None]*jnp.exp(trueG[:,None]*times)
+tumorSize=trueTumorSize+0.05*random.normal(keyNoise,trueTumorSize.shape)
+
+data={
+    "times":jnp.tile(times,(nPatients,1)),
+    "v0":v0,
+    "tumorSize":tumorSize,
+}
+
+
+# ---------------------------------------------------------------------
+# Model components
+# ---------------------------------------------------------------------
+
+# Analytical solution of dV/dt = gV.
+
+# localZs["g"] is the standardized patient-specific deviation.
+# Convert it to the physical growth rate using the population mean/std.
+
+def ModelFn(globalParams,localZs,data):
+    g=globalParams["gMean"]+globalParams["gStd"]*localZs["g"]
+    return {"tumorSize":data["v0"]*jnp.exp(g*data["times"])}
+
+
+# Population parameters and observation noise.
+
+def GlobalPriorFn(dataShapes):
+    return {
+        "gMean":dist.Normal(0.15,0.1),
+        "gStd":dist.HalfNormal(0.1),
+        "sigma":dist.HalfNormal(0.1),
+    }
+
+
+# Training likelihood for one patient; BET vectorizes it across patients.
+
+def TrainLikelihoodFn(globalParams,localZs,data,modelOut):
+    return {"tumorSize":(data["tumorSize"],dist.Normal(modelOut["tumorSize"],globalParams["sigma"]))}
+
+
+# Test likelihood for one patient; only the first nFit observations are used.
+
+def TestLikelihoodFn(globalParams,localZs,data,modelOut):
+    nFit=3
+    tumorSize=modelOut["tumorSize"]
+    mask=jnp.arange(tumorSize.shape[-1])<nFit
+    return {"tumorSize":(data["tumorSize"],dist.Normal(tumorSize,globalParams["sigma"]).mask(mask))}
+
+
+# Score only the last five observations; the first three may be used for fitting.
+
+def ScoreFn(modelOut,data):
+    return jnp.mean(jnp.abs(modelOut["tumorSize"][3:]-data["tumorSize"][3:]))
+
+
+# ---------------------------------------------------------------------
+# Construct Estimator
+# ---------------------------------------------------------------------
+
+est=bet.Estimator(data=data,ModelFn=ModelFn,localZNames=["g"],GlobalPriorFn=GlobalPriorFn,rngSeed=0)
+
+# Patients 0-4 train the population model.
+# Patients 5-9 are completely held out.
+
+
+# ---------------------------------------------------------------------
+# 1. TRAINING
+#
+# Infer:
+# - population mean of g
+# - population std of g
+# - g for each training patient
+# - observation noise sigma
+#
+# using all observations from the five training patients.
+# ---------------------------------------------------------------------
+
+est.Train( trainDataIdxs=jnp.arange(5), TrainLikelihoodFn=TrainLikelihoodFn, Method=bet.Nuts(numWarmup=500,numSamples=500,numChains=4), printSummary=True)
+trainScores=est.ScoreTrainSamples(ScoreFn=ScoreFn)
+
+
+# ---------------------------------------------------------------------
+# 2. TESTING WITHOUT INFERENCE
+#
+# Do not use any test-patient observations for inference.
+#
+# Use the median global posterior state to keep this introductory run fast.
+# For each test patient, sample local Zs from the learned
+# population distribution and generate trajectories.
+#
+# numSamples controls the number of local Z samples generated.
+# ---------------------------------------------------------------------
+
+est.Test( testDataIdxs=jnp.arange(5,10), TestLikelihoodFn=None, nGlobalSamples=None, nLocalZSamples=2000)
+noInferenceScores=est.ScoreTestSamples(ScoreFn=ScoreFn)
+
+
+# ---------------------------------------------------------------------
+# 3. TESTING WITH NUTS
+#
+# Use the median global parameter values from the training posterior
+# and infer each test patient's local Z using early observations.
+#
+# TestLikelihoodFn exposes only the first nFit=3 tumor measurements,
+# so each test patient's g is updated using its early trajectory.
+#
+# ScoreFn evaluates only the final five measurements, held out from inference.
+# ---------------------------------------------------------------------
+
+est.Test( testDataIdxs=jnp.arange(5,10), TestLikelihoodFn=TestLikelihoodFn, Method=bet.Nuts, nGlobalSamples=None, printSummary=True)
+testNutsScores=est.ScoreTestSamples(ScoreFn=ScoreFn)
+
+
+# ---------------------------------------------------------------------
+# Results
+# ---------------------------------------------------------------------
+
+print("Training score:      ",jnp.mean(trainScores))
+print("Test score, no inference: ",jnp.mean(noInferenceScores))
+print("Test score, NUTS:    ",jnp.mean(testNutsScores))

bayesianestimationtool-1.0.2/Examples/2_SimpleExampleSvi.py

@@ -0,0 +1,149 @@
+import numpyro as npo
+npo.set_host_device_count(4)
+
+import jax.numpy as jnp
+import numpyro.distributions as dist
+from jax import random
+
+import BayesianEstimationTool as bet
+
+
+# ---------------------------------------------------------------------
+# Generate 10 synthetic patient trajectories
+# ---------------------------------------------------------------------
+
+keyG,keyNoise=random.split(random.PRNGKey(2),2)
+
+nPatients=10
+nTimes=8
+times=jnp.linspace(0,10,nTimes)
+
+# True population:
+# mean growth rate = 0.15
+# std growth rate  = 0.03
+
+trueG=0.15+0.03*random.normal(keyG,(nPatients,))
+
+# Give patients slightly different initial tumor sizes.
+
+v0=jnp.linspace(0.8,1.2,nPatients)
+trueTumorSize=v0[:,None]*jnp.exp(trueG[:,None]*times)
+tumorSize=trueTumorSize+0.05*random.normal(keyNoise,trueTumorSize.shape)
+
+data={
+    "times":jnp.tile(times,(nPatients,1)),
+    "v0":v0,
+    "tumorSize":tumorSize,
+}
+
+
+# ---------------------------------------------------------------------
+# Model components
+# ---------------------------------------------------------------------
+
+# Analytical solution of dV/dt = gV.
+
+# localZs["g"] is the standardized patient-specific deviation.
+# Convert it to the physical growth rate using the population mean/std.
+
+def ModelFn(globalParams,localZs,data):
+    g=globalParams["gMean"]+globalParams["gStd"]*localZs["g"]
+    return {"tumorSize":data["v0"]*jnp.exp(g*data["times"])}
+
+
+# Population parameters and observation noise.
+
+def GlobalPriorFn(dataShapes):
+    return {
+        "gMean":dist.Normal(0.15,0.1),
+        "gStd":dist.HalfNormal(0.1),
+        "sigma":dist.HalfNormal(0.1),
+    }
+
+
+# Training likelihood for one patient; BET vectorizes it across patients.
+
+def TrainLikelihoodFn(globalParams,localZs,data,modelOut):
+    return {"tumorSize":(data["tumorSize"],dist.Normal(modelOut["tumorSize"],globalParams["sigma"]))}
+
+
+# Test likelihood for one patient; only the first nFit observations are used.
+
+def TestLikelihoodFn(globalParams,localZs,data,modelOut):
+    nFit=3
+    tumorSize=modelOut["tumorSize"]
+    mask=jnp.arange(tumorSize.shape[-1])<nFit
+    return {"tumorSize":(data["tumorSize"],dist.Normal(tumorSize,globalParams["sigma"]).mask(mask))}
+
+
+# Score only the last five observations; the first three may be used for fitting.
+
+def ScoreFn(modelOut,data):
+    return jnp.mean(jnp.abs(modelOut["tumorSize"][3:]-data["tumorSize"][3:]))
+
+
+# ---------------------------------------------------------------------
+# Construct Estimator
+# ---------------------------------------------------------------------
+
+est=bet.Estimator(data=data,ModelFn=ModelFn,localZNames=["g"],GlobalPriorFn=GlobalPriorFn,rngSeed=0)
+
+# Patients 0-4 train the population model.
+# Patients 5-9 are completely held out.
+
+
+# ---------------------------------------------------------------------
+# 1. TRAINING
+#
+# Infer:
+# - population mean of g
+# - population std of g
+# - g for each training patient
+# - observation noise sigma
+#
+# using all observations from the five training patients.
+# ---------------------------------------------------------------------
+
+est.Train( trainDataIdxs=jnp.arange(5), TrainLikelihoodFn=TrainLikelihoodFn, Method=bet.Svi(numSteps=10000,numSamples=2000,stepSize=0.01), printSummary=True)
+trainScores=est.ScoreTrainSamples(ScoreFn=ScoreFn)
+
+
+# ---------------------------------------------------------------------
+# 2. TESTING WITHOUT INFERENCE
+#
+# Do not use any test-patient observations for inference.
+#
+# Use the median global posterior state to keep this introductory run fast.
+# For each test patient, sample local Zs from the learned
+# population distribution and generate trajectories.
+#
+# numSamples controls the number of local Z samples generated.
+# ---------------------------------------------------------------------
+
+est.Test( testDataIdxs=jnp.arange(5,10), TestLikelihoodFn=None, nGlobalSamples=None, nLocalZSamples=2000)
+noInferenceScores=est.ScoreTestSamples(ScoreFn=ScoreFn)
+
+
+# ---------------------------------------------------------------------
+# 3. TESTING WITH SVI
+#
+# Use the median global parameter values from the training posterior
+# and infer each test patient's local Z using early observations.
+#
+# TestLikelihoodFn exposes only the first nFit=3 tumor measurements,
+# so each test patient's g is updated using its early trajectory.
+#
+# ScoreFn evaluates only the final five measurements, held out from inference.
+# ---------------------------------------------------------------------
+
+est.Test( testDataIdxs=jnp.arange(5,10), TestLikelihoodFn=TestLikelihoodFn, Method=bet.Svi, nGlobalSamples=None, printSummary=True)
+testSviScores=est.ScoreTestSamples(ScoreFn=ScoreFn)
+
+
+# ---------------------------------------------------------------------
+# Results
+# ---------------------------------------------------------------------
+
+print("Training score:      ",jnp.mean(trainScores))
+print("Test score, no inference: ",jnp.mean(noInferenceScores))
+print("Test score, SVI:          ",jnp.mean(testSviScores))

bayesianestimationtool-1.0.2/Examples/3_SaveExampleNuts.py

@@ -0,0 +1,151 @@
+import numpyro as npo
+npo.set_host_device_count(4)
+
+import jax.numpy as jnp
+import numpyro.distributions as dist
+from jax import random
+
+import BayesianEstimationTool as bet
+
+
+# ---------------------------------------------------------------------
+# Generate 10 synthetic patient trajectories
+# ---------------------------------------------------------------------
+
+keyG,keyD,keySize,keyNoise=random.split(random.PRNGKey(2),4)
+
+nPatients=10
+nTimes=11
+times=jnp.linspace(0,10,nTimes)
+drugStart=4.0
+
+# Generate correlated patient-specific growth and drug-response effects.
+
+rho=0.8
+zG=random.normal(keyG,(nPatients,))
+zDIndependent=random.normal(keyD,(nPatients,))
+zD=rho*zG+jnp.sqrt(1.0-rho**2)*zDIndependent
+
+# True population:
+# mean growth rate       = 0.15
+# std growth rate        = 0.03
+# mean drug effect       = 0.25
+# std drug effect        = 0.05
+
+trueG=0.15+0.03*zG
+trueD=0.25+0.05*zD
+
+# Give patients different initial tumor sizes.
+
+v0=random.uniform(keySize,(nPatients,),minval=0.8,maxval=1.2)
+
+timeOnDrug=jnp.maximum(times-drugStart,0.0)
+trueTumorSize=v0[:,None]*jnp.exp(trueG[:,None]*times-trueD[:,None]*timeOnDrug)
+tumorSize=trueTumorSize+0.05*random.normal(keyNoise,trueTumorSize.shape)
+
+data={
+    "times":jnp.tile(times,(nPatients,1)),
+    "drugStart":jnp.full(nPatients,drugStart),
+    "v0":v0,
+    "tumorSize":tumorSize,
+}
+
+
+# ---------------------------------------------------------------------
+# Model components
+# ---------------------------------------------------------------------
+
+# Analytical solution: dV/dt = gV before treatment and (g-d)V after.
+
+# localZs["g"] and localZs["d"] are standardized
+# patient-specific deviations.
+#
+# Convert them to physical parameter values using the inferred
+# population means and standard deviations.
+
+def ModelFn(globalParams,localZs,data):
+    g=globalParams["gMean"]+globalParams["gStd"]*localZs["g"]
+    d=globalParams["dMean"]+globalParams["dStd"]*localZs["d"]
+    tumorSize=data["v0"]*jnp.exp(g*data["times"]-d*jnp.maximum(data["times"]-data["drugStart"],0.0))
+    return {"tumorSize":tumorSize}
+
+
+# Population parameters and observation noise.
+
+def GlobalPriorFn(dataShapes):
+    return {
+        "gMean":dist.Normal(0.15,0.1),
+        "gStd":dist.HalfNormal(0.1),
+        "dMean":dist.Normal(0.25,0.1),
+        "dStd":dist.HalfNormal(0.1),
+        "sigma":dist.HalfNormal(0.1),
+    }
+
+
+# Training likelihood for one patient; BET vectorizes it across patients.
+
+def TrainLikelihoodFn(globalParams,localZs,data,modelOut):
+    return {"tumorSize":(data["tumorSize"],dist.Normal(modelOut["tumorSize"],globalParams["sigma"]))}
+
+
+# Score one trajectory against all available observations.
+
+def ScoreFn(modelOut,data):
+    return jnp.mean(jnp.abs(modelOut["tumorSize"]-data["tumorSize"]))
+
+
+# ---------------------------------------------------------------------
+# Construct Estimator
+# ---------------------------------------------------------------------
+
+est=bet.Estimator(data=data,ModelFn=ModelFn,localZNames=["g","d"],GlobalPriorFn=GlobalPriorFn,rngSeed=0)
+
+
+# ---------------------------------------------------------------------
+# 1. TRAINING
+#
+# Patients 0-4 train the population model.
+#
+# Infer:
+# - population mean growth rate
+# - population std growth rate
+# - population mean drug effect
+# - population std drug effect
+# - correlation between patient-specific g and d
+# - patient-specific g and d values
+# - observation noise sigma
+#
+# using all observations from the five training patients.
+# ---------------------------------------------------------------------
+
+est.Train(trainDataIdxs=jnp.arange(5),TrainLikelihoodFn=TrainLikelihoodFn,Method=bet.Nuts(numWarmup=500,numSamples=500,numChains=4),printSummary=True)
+
+
+# ---------------------------------------------------------------------
+# 2. SCORE TRAINING POSTERIOR
+# ---------------------------------------------------------------------
+
+trainScores=est.ScoreTrainSamples(ScoreFn=ScoreFn)
+
+print("Training score before save:",jnp.mean(trainScores))
+
+
+# ---------------------------------------------------------------------
+# 3. SAVE
+#
+# The Estimator is saved as a NumPy .npz archive.
+#
+# By default, Save stores:
+# - Estimator metadata
+# - training/test run settings, including method name and constructor arguments
+# - training/test indices
+# - RNG state
+# - training global posterior samples
+# - training Cholesky samples
+# - training local posterior samples
+# - test local Zs/globals/cholesky, if testing has been run
+#
+# Model outputs and the full input dataset are not saved by default.
+# ---------------------------------------------------------------------
+
+est.Save("SimpleTumorGrowthNuts.npz")