simtrial 0.0.1__py3-none-any.whl

simtrial/__init__.py

@@ -0,0 +1,7 @@
+"""
+Public API for the simtrial package.
+"""
+
+from .piecewise_exponential import PiecewiseExponential, set_random_seed
+
+__all__ = ["PiecewiseExponential", "set_random_seed"]

simtrial/piecewise_exponential.py

@@ -0,0 +1,154 @@
+"""
+Tools for working with the piecewise exponential distribution.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Sequence, cast
+
+import numpy as np
+from numpy.typing import NDArray
+
+_RANDOM_STATE: np.random.Generator | None = None
+
+
+def _default_rng() -> np.random.Generator:
+    """
+    Return a module-level random number generator.
+
+    Returns:
+        The reusable random number generator for piecewise exponential sampling.
+    """
+
+    global _RANDOM_STATE
+    if _RANDOM_STATE is None:
+        _reset_rng()
+    return cast(np.random.Generator, _RANDOM_STATE)
+
+
+def _reset_rng(seed: int | None = None) -> None:
+    """
+    Initialize the module-level random number generator.
+
+    Args:
+        seed: Seed used to reset the generator.
+
+    Returns:
+        Nothing.
+    """
+
+    global _RANDOM_STATE
+    _RANDOM_STATE = np.random.default_rng(seed)
+
+
+def set_random_seed(seed: int) -> None:
+    """
+    Set the seed for the module-level random number generator.
+
+    Args:
+        seed: Seed value that controls reproducibility.
+
+    Returns:
+        Nothing.
+    """
+
+    _reset_rng(seed=seed)
+
+
+@dataclass
+class PiecewiseExponential:
+    """
+    Piecewise exponential sampler based on the inverse cumulative distribution.
+
+    Args:
+        durations: Interval durations for each hazard rate segment; all but the
+            final duration must be finite and strictly positive, while the last
+            entry may be set to ``math.inf`` to represent an open-ended tail.
+        rates: Hazard rates aligned with the provided durations.
+        rng: Optional random number generator.
+
+    Raises:
+        ValueError: Raised when inputs are invalid.
+    """
+
+    durations: Sequence[float]
+    rates: Sequence[float]
+    rng: np.random.Generator | None = None
+
+    def __post_init__(self) -> None:
+        """
+        Validate inputs and precompute cumulative quantities.
+
+        Returns:
+            Nothing.
+        """
+
+        self._durations = np.asarray(self.durations, dtype=float)
+        self._rates = np.asarray(self.rates, dtype=float)
+
+        if self._durations.ndim != 1:
+            raise ValueError("durations must be one-dimensional")
+        if self._rates.ndim != 1:
+            raise ValueError("rates must be one-dimensional")
+        if self._durations.size == 0:
+            raise ValueError("durations must contain at least one interval")
+        if self._durations.size != self._rates.size:
+            raise ValueError("durations and rates must have the same length")
+        if not np.all(np.isfinite(self._durations[:-1])):
+            raise ValueError(
+                "durations must be finite except possibly the last interval, "
+                "which may extend to infinity"
+            )
+        if np.any(self._durations[:-1] <= 0):
+            raise ValueError("durations before the final interval must be positive")
+        last_duration = float(self._durations[-1])
+        if math.isnan(last_duration):
+            raise ValueError("final duration must be finite or math.inf")
+        if last_duration <= 0:
+            raise ValueError("final duration must be positive")
+        if np.any(~np.isfinite(self._rates)):
+            raise ValueError("rates must be finite")
+        if np.any(self._rates <= 0):
+            raise ValueError("rates must be strictly positive")
+
+        self._cum_time = np.concatenate(
+            (np.array([0.0]), np.cumsum(self._durations[:-1]))
+        )
+        self._cum_hazard = np.concatenate(
+            (np.array([0.0]), np.cumsum(self._durations[:-1] * self._rates[:-1]))
+        )
+
+    def sample(
+        self,
+        size: int | tuple[int, ...] | None = None,
+        rng: np.random.Generator | None = None,
+    ) -> float | NDArray[np.float64]:
+        """
+        Draw samples using the inverse cumulative distribution function.
+
+        Args:
+            size: Requested sample size or shape.
+            rng: Optional random number generator overriding the stored generator.
+
+        Returns:
+            A scalar when `size` is `None`, otherwise an array of samples.
+        """
+
+        generator = rng or self.rng or _default_rng()
+
+        if size is None:
+            uniform = float(generator.uniform())
+            hazard = -math.log(uniform)
+            index = int(np.searchsorted(self._cum_hazard, hazard, side="right") - 1)
+            base_time = float(self._cum_time[index])
+            return base_time + (hazard - float(self._cum_hazard[index])) / float(
+                self._rates[index]
+            )
+
+        uniforms = generator.uniform(size=size)
+        hazards = -np.log(uniforms)
+        indices = np.searchsorted(self._cum_hazard, hazards, side="right") - 1
+        base_times = self._cum_time[indices]
+        return base_times + (hazards - self._cum_hazard[indices]) / self._rates[indices]

simtrial-0.0.1.dist-info/METADATA

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: simtrial
+Version: 0.0.1
+Summary: Clinical trial simulation
+Project-URL: Repository, https://github.com/nanxstats/simtrial-python
+Project-URL: Issues, https://github.com/nanxstats/simtrial-python/issues
+Project-URL: Changelog, https://github.com/nanxstats/simtrial-python/blob/main/CHANGELOG.md
+Author-email: Nan Xiao <me@nanx.me>
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: numpy>=2.0.0
+Description-Content-Type: text/markdown
+
+# simtrial-python
+
+[![PyPI version](https://img.shields.io/pypi/v/simtrial)](https://pypi.org/project/simtrial/)
+![Python versions](https://img.shields.io/pypi/pyversions/simtrial)
+[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
+[![CI Tests](https://github.com/nanxstats/simtrial-python/actions/workflows/ci-tests.yml/badge.svg)](https://github.com/nanxstats/simtrial-python/actions/workflows/ci-tests.yml)
+![License](https://img.shields.io/pypi/l/simtrial)
+
+simtrial-python is an experimental Python package for clinical trial
+simulation with time-to-event endpoints.
+
+## Installation
+
+You can install simtrial-python from PyPI:
+
+```bash
+pip install simtrial
+```
+
+Or install the development version from GitHub:
+
+```bash
+git clone https://github.com/nanxstats/simtrial-python.git
+cd simtrial-python
+python3 -m pip install -e .
+```

simtrial-0.0.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+simtrial/__init__.py,sha256=9Jimypg2M2w_Lkc-VAbhsI44-DZ0Romcc5w-_KxKL8E,174
+simtrial/piecewise_exponential.py,sha256=vVxILWC7iwXQghnS4e2gsu3Ed0jVIwpoJRqfqmnF_Ts,4871
+simtrial-0.0.1.dist-info/METADATA,sha256=SetPmMShHLtJZr87vpgcYMgxU65A7MbUF9lmUgnW00I,1884
+simtrial-0.0.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+simtrial-0.0.1.dist-info/licenses/LICENSE,sha256=fbue7RMrTYyNN6h6aYvgHX0k4Gpkd6h9bhk1XSVgAuI,1068
+simtrial-0.0.1.dist-info/RECORD,,

simtrial-0.0.1.dist-info/WHEEL

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

simtrial-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2025, simtrial-python authors
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.