simtrial 0.0.1__tar.gz

simtrial-0.0.1/.github/workflows/ci-tests.yml

@@ -0,0 +1,56 @@
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+name: CI Tests
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+      fail-fast: false
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          # we are using the -e flag, so that code cov finds the source.
+          # this is not ideal, since installing an editable can technically
+          # differ from a normal install in surprising ways.
+          pip install -e '.[all]'
+      - name: Test with pytest
+        run: |
+          pip install pytest pytest-cov
+          pytest --cov=simtrial --cov-report=xml
+
+      # - name: Upload coverage reports to Codecov
+      #   uses: codecov/codecov-action@v4
+      #   with:
+      #     name: "py${{ matrix.python-version }}"
+      #     token: ${{ secrets.CODECOV_TOKEN }}
+
+  test-windows:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install dependencies
+        run: |
+          pip install -e '.[all]'
+      - name: Test with pytest
+        run: |
+          pip install pytest pytest-cov
+          pytest --cov=simtrial --cov-report=xml

simtrial-0.0.1/.github/workflows/mypy.yml

@@ -0,0 +1,34 @@
+name: Mypy check
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - '**'
+
+jobs:
+  mypy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.13.7
+
+      - name: Install uv
+        run: |
+          pip install uv
+
+      - name: Install dependencies
+        run: |
+          uv sync --dev
+
+      - name: Run Type Checks
+        run: |
+          uv run mypy .

simtrial-0.0.1/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Jupyter notebooks
+.ipynb_checkpoints/

simtrial-0.0.1/.python-version

@@ -0,0 +1 @@
+3.13.7

simtrial-0.0.1/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## simtrial-python 0.0.1
+
+### New features
+
+- Added a piecewise exponential sampler that mirrors the R implementation using
+  inverse-CDF sampling with reproducibility hooks and type hints (#1).
+
+### Testing
+
+- Added pytest tests with 100% code coverage for the sampler, including
+  validation, broadcasting, and RNG behaviors (#1).
+- Added deterministic R-generated fixtures (`tests/fixtures/`) to
+  cross-check Python draws (#1).

simtrial-0.0.1/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.

simtrial-0.0.1/PKG-INFO

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

@@ -0,0 +1,26 @@
+# 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/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "simtrial"
+version = "0.0.1"
+description = "Clinical trial simulation"
+authors = [
+    { name = "Nan Xiao", email = "me@nanx.me" }
+]
+dependencies = [
+    "numpy>=2.0.0",
+]
+readme = "README.md"
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+
+    "Intended Audience :: Science/Research",
+
+    "License :: OSI Approved :: MIT License",
+
+    "Operating System :: OS Independent",
+
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+
+    "Topic :: Scientific/Engineering :: Mathematics",
+
+    "Typing :: Typed",
+]
+
+requires-python = ">=3.10"
+
+[project.urls]
+Repository = "https://github.com/nanxstats/simtrial-python"
+Issues = "https://github.com/nanxstats/simtrial-python/issues"
+Changelog = "https://github.com/nanxstats/simtrial-python/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "isort>=6.1.0",
+    "mypy>=1.18.2",
+    "pytest>=8.4.2",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.13.3",
+]

simtrial-0.0.1/src/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-0.0.1/src/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/tests/fixtures/README.md

@@ -0,0 +1,18 @@
+# Reference data fixtures
+
+The `.txt` files in this directory contain reference outputs from the original
+simtrial R implementation. They are used to validate the Python port of the
+piecewise exponential generator.
+
+## Regenerating fixtures
+
+The fixture generator script reproduces the draws using the R implementation
+for specific seeds and parameter sets, and writes both the uniform random
+numbers and the resulting event times to plain-text files without headers.
+
+```sh
+Rscript tests/fixtures/generate_piecewise_exponential.R
+```
+
+The pytest suite consumes these numbers with `numpy.loadtxt` to cross-check the
+Python implementation against the reference algorithm.

simtrial-0.0.1/tests/fixtures/generate_piecewise_exponential.R

@@ -0,0 +1,50 @@
+options(digits = 16, scipen = 999)
+
+suppressPackageStartupMessages(library(simtrial))
+
+output_dir <- "tests/fixtures"
+dir.create(output_dir, showWarnings = FALSE, recursive = TRUE)
+
+write_matrix <- function(mat, filename) {
+  path <- file.path(output_dir, filename)
+  write.table(
+    mat,
+    file = path,
+    row.names = FALSE,
+    col.names = FALSE,
+    quote = FALSE
+  )
+}
+
+write_fixture <- function(filename, seed, n, durations, rates) {
+  fail_rate <- data.frame(duration = durations, rate = rates)
+
+  set.seed(seed)
+  uniforms <- runif(n)
+
+  set.seed(seed)
+  r_times <- simtrial::rpwexp(n = n, fail_rate = fail_rate)
+
+  if (!all.equal(length(r_times), n)) {
+    stop("Generated R sample length does not match request.")
+  }
+
+  data <- cbind(uniforms, r_times)
+  write_matrix(data, filename)
+}
+
+write_fixture(
+  filename = "pwexp_single_seed_123_n20.txt",
+  seed = 123,
+  n = 20,
+  durations = c(1.0),
+  rates = c(2.0)
+)
+
+write_fixture(
+  filename = "pwexp_multi_seed_456_n30.txt",
+  seed = 456,
+  n = 30,
+  durations = c(0.5, 0.5, 1.0),
+  rates = c(1.0, 3.0, 10.0)
+)

simtrial-0.0.1/tests/fixtures/pwexp_multi_seed_456_n30.txt

@@ -0,0 +1,30 @@
+0.0895516003947705 1.04129402791134
+0.21051231934689 0.852737034452974
+0.73295526811853 0.3106706047168
+0.852133540669456 0.16001202655997
+0.788397894473746 0.237752374339119
+0.331959968432784 0.700913631448442
+0.0824327350128442 1.0495772651384
+0.285526945022866 0.751139625325209
+0.23750327154994 0.812524626885066
+0.38523616688326 0.651299570761263
+0.372945911018178 0.662107293509504
+0.217908559599891 0.84122658518801
+0.755105035379529 0.280898419701376
+0.82168106874451 0.196402953443282
+0.598918164148927 0.504210103662197
+0.651033560046926 0.429194086570926
+0.843117238022387 0.170649258262776
+0.4532381426543 0.597112530135988
+0.716757099609822 0.333018268987182
+0.291222166502848 0.744556281441457
+0.179883137578145 0.905149291537882
+0.721743599977344 0.326085327846133
+0.905087579507381 0.0997235670280772
+0.445766670163721 0.602653208308821
+0.838601463707164 0.17601969882944
+0.70349283167161 0.351697592001127
+0.950928996317089 0.0503158813512434
+0.643152175005525 0.441373918661801
+0.0748198556248099 1.05926719796977
+0.253490373725072 0.790809810047676

simtrial-0.0.1/tests/fixtures/pwexp_single_seed_123_n20.txt

@@ -0,0 +1,20 @@
+0.287577520124614 0.623131409936862
+0.788305135443807 0.118935018178498
+0.4089769218117 0.4470482752098
+0.883017404004931 0.0622051842437791
+0.940467284293845 0.0306892081429518
+0.0455564993899316 1.54440098925953
+0.528105488047004 0.319229613631512
+0.892419044394046 0.0569097380018624
+0.551435014465824 0.297615640691194
+0.456614735303447 0.391957636804057
+0.956833345349878 0.0220630227419475
+0.453334156190977 0.395562886897321
+0.677570635452867 0.194620736345925
+0.572633401956409 0.278754777090065
+0.102924682665616 1.13687889724614
+0.899824970401824 0.0527775059511509
+0.24608773435466 0.701033581456949
+0.0420595335308462 1.58433459966692
+0.327920719282702 0.557491704659201
+0.954503649147227 0.0232819063627237