refactor: unify error handling (#60)

Author: DiogoRibeiro7

benchmarks/README.md

@@ -0,0 +1,13 @@
+# Benchmarks
+
+This directory contains performance benchmarks run with `pytest-benchmark`.
+Run them with:
+
+```bash
+pytest benchmarks -q --benchmark-only
+```
+
+## Available benchmarks
+
+- validation helpers
+- TDCM generation

benchmarks/test_tdcm_benchmark.py

@@ -0,0 +1,19 @@
+import pytest
+
+pytest.importorskip("pytest_benchmark")
+
+from gen_surv.tdcm import gen_tdcm
+
+
+def test_tdcm_generation_benchmark(benchmark):
+    benchmark(
+        gen_tdcm,
+        n=1000,
+        dist="weibull",
+        corr=0.5,
+        dist_par=[1, 2, 1, 2],
+        model_cens="uniform",
+        cens_par=1.0,
+        beta=[0.1, 0.2, 0.3],
+        lam=1.0,
+    )

benchmarks/test_validation_benchmark.py

@@ -0,0 +1,11 @@
+import numpy as np
+import pytest
+
+pytest.importorskip("pytest_benchmark")
+
+from gen_surv._validation import ensure_positive_sequence
+
+
+def test_positive_sequence_benchmark(benchmark):
+    seq = np.random.rand(10000) + 1.0
+    benchmark(ensure_positive_sequence, seq, "seq")

binder/requirements.txt

@@ -0,0 +1,2 @@
+-e .
+jupyterlab

docs/requirements.txt

@@ -5,3 +5,4 @@ sphinx-autodoc-typehints
 sphinx-copybutton
 sphinx-design
 linkify-it-py>=2.0
+matplotlib

docs/source/conf.py

@@ -21,6 +21,7 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.autosummary",
     "sphinx.ext.githubpages",
+    "sphinx.ext.plot_directive",
     "myst_parser",
     "sphinx_copybutton",
     "sphinx_design",

docs/source/examples/cmm.md

@@ -0,0 +1,28 @@
+# Continuous-Time Multi-State Markov Model (CMM)
+
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/DiogoRibeiro7/genSurvPy/HEAD?urlpath=lab/tree/examples/notebooks/cmm.ipynb)
+
+Visualize transition times from the CMM generator:
+
+```{plot}
+import numpy as np
+import matplotlib.pyplot as plt
+from gen_surv import generate
+
+np.random.seed(0)
+
+df = generate(
+    model="cmm",
+    n=200,
+    model_cens="exponential",
+    cens_par=2.0,
+    beta=[0.1, 0.2, 0.3],
+    covariate_range=1.0,
+    rate=[0.1, 1.0, 0.2, 1.0, 0.1, 1.0],
+)
+
+plt.hist(df["stop"], bins=20, color="#4C72B0")
+plt.xlabel("Time")
+plt.ylabel("Frequency")
+plt.title("CMM Transition Times")
+```

docs/source/examples/index.md

@@ -12,7 +12,14 @@ Some examples may require optional packages such as
 `pip install scikit-survival` before running these examples.
 ```
 
+Each example page includes a [Binder](https://mybinder.org/) badge so you can
+launch the corresponding notebook and experiment interactively in your
+browser.
+
 ```{toctree}
 :maxdepth: 2
 
+tdcm
+cmm
+thmm
 ```

docs/source/examples/tdcm.md

@@ -0,0 +1,30 @@
+# Time-Dependent Covariate Model (TDCM)
+
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/DiogoRibeiro7/genSurvPy/HEAD?urlpath=lab/tree/examples/notebooks/tdcm.ipynb)
+
+A basic visualization of event times produced by the TDCM generator:
+
+```{plot}
+import numpy as np
+import matplotlib.pyplot as plt
+from gen_surv import generate
+
+np.random.seed(0)
+
+df = generate(
+    model="tdcm",
+    n=200,
+    dist="weibull",
+    corr=0.5,
+    dist_par=[1, 2, 1, 2],
+    model_cens="uniform",
+    cens_par=1.0,
+    beta=[0.1, 0.2, 0.3],
+    lam=1.0,
+)
+
+plt.hist(df["stop"], bins=20, color="#4C72B0")
+plt.xlabel("Time")
+plt.ylabel("Frequency")
+plt.title("TDCM Event Times")
+```

docs/source/examples/thmm.md

@@ -0,0 +1,28 @@
+# Time-Homogeneous Hidden Markov Model (THMM)
+
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/DiogoRibeiro7/genSurvPy/HEAD?urlpath=lab/tree/examples/notebooks/thmm.ipynb)
+
+An example of event times generated by the THMM:
+
+```{plot}
+import numpy as np
+import matplotlib.pyplot as plt
+from gen_surv import generate
+
+np.random.seed(0)
+
+df = generate(
+    model="thmm",
+    n=200,
+    model_cens="exponential",
+    cens_par=3.0,
+    beta=[0.1, 0.2, 0.3],
+    covariate_range=1.0,
+    rate=[0.2, 0.1, 0.3],
+)
+
+plt.hist(df["time"], bins=20, color="#4C72B0")
+plt.xlabel("Time")
+plt.ylabel("Frequency")
+plt.title("THMM Event Times")
+```