gsdesign 0.0.1__tar.gz

gsdesign-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=gsdesign --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=gsdesign --cov-report=xml

gsdesign-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 .

gsdesign-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/

gsdesign-0.0.1/.python-version

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

gsdesign-0.0.1/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## gsdesign-python 0.0.1
+
+### New features
+
+- Ported the canonical `gridpts`, `h1`, and `hupdate` numerical integration
+  routines from gsDesign, complete with typed public exports (#1).
+
+### Testing
+
+- Added unit tests with high-precision reference fixtures and regeneration
+  tooling to keep the Python implementation aligned with the R package
+  gsDesign2 (#1).

gsdesign-0.0.1/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2025, gsdesign-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.

gsdesign-0.0.1/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: gsdesign
+Version: 0.0.1
+Summary: Group sequential design
+Project-URL: Repository, https://github.com/nanxstats/gsdesign-python
+Project-URL: Issues, https://github.com/nanxstats/gsdesign-python/issues
+Project-URL: Changelog, https://github.com/nanxstats/gsdesign-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
+
+# gsdesign-python
+
+[![PyPI version](https://img.shields.io/pypi/v/gsdesign)](https://pypi.org/project/gsdesign/)
+![Python versions](https://img.shields.io/pypi/pyversions/gsdesign)
+[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
+[![CI Tests](https://github.com/nanxstats/gsdesign-python/actions/workflows/ci-tests.yml/badge.svg)](https://github.com/nanxstats/gsdesign-python/actions/workflows/ci-tests.yml)
+![License](https://img.shields.io/pypi/l/gsdesign)
+
+gsdesign-python is an experimental Python package for group sequential design.
+
+## Installation
+
+You can install gsdesign-python from PyPI:
+
+```bash
+pip install gsdesign
+```
+
+Or install the development version from GitHub:
+
+```bash
+git clone https://github.com/nanxstats/gsdesign-python.git
+cd gsdesign-python
+python3 -m pip install -e .
+```

gsdesign-0.0.1/README.md

@@ -0,0 +1,25 @@
+# gsdesign-python
+
+[![PyPI version](https://img.shields.io/pypi/v/gsdesign)](https://pypi.org/project/gsdesign/)
+![Python versions](https://img.shields.io/pypi/pyversions/gsdesign)
+[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
+[![CI Tests](https://github.com/nanxstats/gsdesign-python/actions/workflows/ci-tests.yml/badge.svg)](https://github.com/nanxstats/gsdesign-python/actions/workflows/ci-tests.yml)
+![License](https://img.shields.io/pypi/l/gsdesign)
+
+gsdesign-python is an experimental Python package for group sequential design.
+
+## Installation
+
+You can install gsdesign-python from PyPI:
+
+```bash
+pip install gsdesign
+```
+
+Or install the development version from GitHub:
+
+```bash
+git clone https://github.com/nanxstats/gsdesign-python.git
+cd gsdesign-python
+python3 -m pip install -e .
+```

gsdesign-0.0.1/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "gsdesign"
+version = "0.0.1"
+description = "Group sequential design"
+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/gsdesign-python"
+Issues = "https://github.com/nanxstats/gsdesign-python/issues"
+Changelog = "https://github.com/nanxstats/gsdesign-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",
+]

gsdesign-0.0.1/src/gsdesign/__init__.py

@@ -0,0 +1,5 @@
+"""Core numerical integration routines for gsdesign."""
+
+from .integration import gridpts, h1, hupdate
+
+__all__ = ["gridpts", "h1", "hupdate"]

gsdesign-0.0.1/src/gsdesign/integration.py

@@ -0,0 +1,184 @@
+"""Numerical integration utilities for group sequential design.
+
+These routines port the canonical grid generation and update algorithms
+from the original C and C++ implementations in gsDesign.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+import numpy as np
+from numpy.typing import NDArray
+
+SQRT_2PI: float = float(np.sqrt(2.0 * np.pi))
+FloatArray = NDArray[np.float64]
+
+
+def _normal_pdf(x: FloatArray) -> FloatArray:
+    """Evaluate the standard normal density at the supplied points."""
+    squared = np.square(x, dtype=np.float64)
+    return np.exp(-0.5 * squared) / SQRT_2PI
+
+
+def _as_float64(array: Iterable[float]) -> FloatArray:
+    """Convert an iterable of floats to a contiguous float64 NumPy array."""
+    return np.asarray(array, dtype=np.float64)
+
+
+def gridpts(
+    r: int = 18,
+    mu: float = 0.0,
+    a: float = -np.inf,
+    b: float = np.inf,
+) -> tuple[FloatArray, FloatArray]:
+    """
+    Construct Simpson's rule grid points for canonical normal integration.
+
+    Args:
+        r: Number of odd grid points defining the Simpson stencil (at least 2).
+        mu: Mean shift applied to the canonical grid before truncation.
+        a: Lower integration limit; use ``-numpy.inf`` for no truncation.
+        b: Upper integration limit; use ``numpy.inf`` for no truncation.
+
+    Returns:
+        A tuple containing grid locations ``z`` and Simpson weights ``w``.
+    """
+
+    if r < 2:
+        raise ValueError("r must be at least 2 for Simpson integration.")
+    if not a < b:
+        raise ValueError("Lower limit 'a' must be strictly less than upper limit 'b'.")
+
+    base_count = 6 * r - 1
+    x = np.empty(base_count, dtype=np.float64)
+    odd_indices = np.arange(r - 1, dtype=np.int64)
+    right_indices = 6 * r - 2 - odd_indices
+    tmp = 3.0 + 4.0 * np.log(r / (odd_indices.astype(np.float64) + 1.0))
+    x[odd_indices] = mu - tmp
+    x[right_indices] = mu + tmp
+
+    mid_indices = np.arange(r - 1, 5 * r, dtype=np.int64)
+    x[mid_indices] = mu - 3.0 + 3.0 * (mid_indices - (r - 1)) / (2.0 * r)
+
+    if np.nanmin(x) < a:
+        x = x[x > a]
+        x = np.insert(x, 0, a)
+    if np.nanmax(x) > b:
+        x = x[x < b]
+        x = np.append(x, b)
+
+    m = x.size
+    if m == 1:
+        return x.astype(np.float64), np.ones(1, dtype=np.float64)
+
+    z = np.empty(2 * m - 1, dtype=np.float64)
+    w = np.empty(2 * m - 1, dtype=np.float64)
+
+    odd_positions = np.arange(0, 2 * m - 1, 2)
+    even_positions = np.arange(1, 2 * m - 1, 2)
+
+    z[odd_positions] = x
+    z[even_positions] = 0.5 * (x[:-1] + x[1:])
+
+    w[odd_positions[0]] = x[1] - x[0]
+    if m > 2:
+        w[odd_positions[1:-1]] = x[2:] - x[:-2]
+    w[odd_positions[-1]] = x[-1] - x[-2]
+    w[even_positions] = 4.0 * (x[1:] - x[:-1])
+    w /= 6.0
+
+    return z, w
+
+
+def h1(
+    r: int = 18,
+    theta: float = 0.0,
+    info: float = 1.0,
+    a: float = -np.inf,
+    b: float = np.inf,
+) -> tuple[FloatArray, FloatArray, FloatArray]:
+    """
+    Initialize the density grid for the first group sequential analysis.
+
+    Args:
+        r: Number of odd grid points defining the Simpson stencil (at least 2).
+        theta: Canonical drift parameter for the analysis.
+        info: Fisher information at the analysis; must be positive.
+        a: Lower integration limit; use ``-numpy.inf`` for no truncation.
+        b: Upper integration limit; use ``numpy.inf`` for no truncation.
+
+    Returns:
+        A tuple of arrays ``(z, w, h)`` ready for recursive integration.
+    """
+
+    if info <= 0:
+        raise ValueError("Information 'info' must be positive.")
+
+    mu = float(theta) * np.sqrt(info)
+    z, w = gridpts(r=r, mu=mu, a=a, b=b)
+    deviation = z - mu
+    h = w * _normal_pdf(deviation)
+    return z, w, h
+
+
+def hupdate(
+    r: int,
+    theta: float,
+    info: float,
+    a: float,
+    b: float,
+    theta_prev: float,
+    info_prev: float,
+    gm1: tuple[Iterable[float], Iterable[float], Iterable[float]],
+) -> tuple[FloatArray, FloatArray, FloatArray]:
+    """
+    Update the density grid for a subsequent group sequential analysis.
+
+    Args:
+        r: Number of odd grid points defining the Simpson stencil (at least 2).
+        theta: Canonical drift parameter for the current analysis.
+        info: Fisher information at the current analysis; must exceed ``info_prev``.
+        a: Lower integration limit; use ``-numpy.inf`` for no truncation.
+        b: Upper integration limit; use ``numpy.inf`` for no truncation.
+        theta_prev: Canonical drift parameter at the previous analysis.
+        info_prev: Fisher information at the previous analysis; must be positive.
+        gm1: tuple ``(z_prev, w_prev, h_prev)`` from ``h1`` or ``hupdate``.
+
+    Returns:
+        A tuple of arrays ``(z, w, h)`` updated for the current analysis.
+    """
+
+    if info <= info_prev:
+        raise ValueError("Current information must exceed previous information.")
+    if info_prev <= 0:
+        raise ValueError("Previous information must be positive.")
+
+    try:
+        z_prev_raw, _, h_prev_raw = gm1
+    except (TypeError, ValueError) as exc:
+        raise ValueError("gm1 must unpack into (z_prev, w_prev, h_prev).") from exc
+
+    z_prev = _as_float64(z_prev_raw)
+    h_prev = _as_float64(h_prev_raw)
+    if z_prev.shape != h_prev.shape:
+        raise ValueError("Previous grid points and weights must share the same shape.")
+
+    rt_info = np.sqrt(info)
+    rt_info_prev = np.sqrt(info_prev)
+    delta = info - info_prev
+    rt_delta = np.sqrt(delta)
+
+    z, w = gridpts(r=r, mu=float(theta) * rt_info, a=a, b=b)
+
+    mu = theta * info - theta_prev * info_prev
+    scale = rt_info / rt_delta
+    t = (z_prev * rt_info_prev + mu) / rt_delta
+
+    kernel = _normal_pdf(z[:, np.newaxis] * scale - t[np.newaxis, :])
+    h = kernel @ h_prev
+    h *= w * scale
+    return z, w, h
+
+
+__all__ = ["gridpts", "h1", "hupdate"]

gsdesign-0.0.1/tests/fixtures/README.md

@@ -0,0 +1,16 @@
+# Reference data fixtures
+
+The `.txt` files in this directory contain reference outputs from the original
+gsDesign2 R implementation. They are used to validate the Python port of the
+`gridpts`, `h1`, and `hupdate` routines.
+
+To regenerate the fixtures, run the helper script below (requires the
+gsDesign2 R package to be installed):
+
+```sh
+Rscript tests/fixtures/generate_reference_data.R
+```
+
+The script recomputes each dataset via the package's internal functions and
+writes the results in plain text so the pytest suite can consume them with
+`numpy.loadtxt`.

gsdesign-0.0.1/tests/fixtures/generate_reference_data.R

@@ -0,0 +1,45 @@
+options(digits = 16, scipen = 999)
+
+suppressPackageStartupMessages(library(gsDesign2))
+
+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
+  )
+}
+
+g <- gsDesign2:::gridpts(r = 5, mu = 0.5, a = -2, b = 2)
+write_matrix(
+  cbind(g$z, g$w),
+  "gridpts_r5_mu0.5_a-2_b2.txt"
+)
+
+h1_ref <- gsDesign2:::h1(r = 5, theta = 0.5, info = 2, a = -2, b = 2)
+write_matrix(
+  cbind(h1_ref$z, h1_ref$w, h1_ref$h),
+  "h1_r5_theta0.5_info2_a-2_b2.txt"
+)
+
+gm1 <- gsDesign2:::h1(r = 5, theta = 0.3, info = 1.5, a = -2, b = 2)
+hupdate_ref <- gsDesign2:::hupdate(
+  r = 5,
+  theta = 0.5,
+  info = 2.5,
+  a = -2,
+  b = 2,
+  thetam1 = 0.3,
+  im1 = 1.5,
+  gm1 = gm1
+)
+write_matrix(
+  cbind(hupdate_ref$z, hupdate_ref$w, hupdate_ref$h),
+  "hupdate_r5_theta0.5_info2.5_thetaprev0.3_infoprev1.5_a-2_b2.txt"
+)

gsdesign-0.0.1/tests/fixtures/gridpts_r5_mu0.5_a-2_b2.txt

@@ -0,0 +1,29 @@
+-2 0.0166666666666667
+-1.95 0.0666666666666667
+-1.9 0.0666666666666667
+-1.75 0.2
+-1.6 0.1
+-1.45 0.2
+-1.3 0.1
+-1.15 0.2
+-1 0.1
+-0.85 0.2
+-0.7 0.1
+-0.55 0.2
+-0.4 0.1
+-0.25 0.2
+-0.1 0.1
+0.05 0.2
+0.2 0.1
+0.35 0.2
+0.5 0.0999999999999999
+0.65 0.2
+0.8 0.1
+0.95 0.2
+1.1 0.1
+1.25 0.2
+1.4 0.1
+1.55 0.2
+1.7 0.1
+1.85 0.2
+2 0.05

gsdesign-0.0.1/tests/fixtures/h1_r5_theta0.5_info2_a-2_b2.txt

@@ -0,0 +1,31 @@
+-2 0.00118446353109125 0.0000121083238684652
+-1.99644660940673 0.004737854124365 0.000048901134406299
+-1.99289321881345 0.0511844635310913 0.000533389957968692
+-1.84289321881345 0.2 0.00308986942687904
+-1.69289321881345 0.1 0.00223945302948429
+-1.54289321881345 0.2 0.00634793036713348
+-1.39289321881345 0.1 0.00439835959804272
+-1.24289321881345 0.2 0.0119189412137632
+-1.09289321881345 0.1 0.00789501583008941
+-0.942893218813453 0.2 0.0204529849127956
+-0.792893218813453 0.1 0.0129517595665892
+-0.642893218813453 0.2 0.0320766654683839
+-0.492893218813452 0.1 0.0194186054983213
+-0.342893218813452 0.2 0.0459764281368466
+-0.192893218813452 0.1 0.0266085249898755
+-0.0428932188134525 0.2 0.0602274864309608
+0.107106781186547 0.1 0.03332246028918
+0.257106781186548 0.2 0.0721053924923297
+0.407106781186548 0.1 0.0381387815460524
+0.557106781186548 0.2 0.0788958661815777
+0.707106781186547 0.0999999999999999 0.0398942280401432
+0.857106781186547 0.2 0.0788958661815777
+1.00710678118655 0.1 0.0381387815460524
+1.15710678118655 0.2 0.0721053924923297
+1.30710678118655 0.1 0.03332246028918
+1.45710678118655 0.2 0.0602274864309608
+1.60710678118655 0.1 0.0266085249898755
+1.75710678118655 0.2 0.0459764281368467
+1.90710678118655 0.0654822031355754 0.0127157306985068
+1.95355339059327 0.0619288125423016 0.0113615225581578
+2 0.0154822031355754 0.0026777213989986

gsdesign-0.0.1/tests/fixtures/hupdate_r5_theta0.5_info2.5_thetaprev0.3_infoprev1.5_a-2_b2.txt

@@ -0,0 +1,31 @@
+-2 0.0150949025070158 0.0000769903094874132
+-1.95471529247895 0.0603796100280634 0.000360648259573358
+-1.9094305849579 0.0650949025070158 0.000453637555511597
+-1.7594305849579 0.2 0.00226308249491002
+-1.6094305849579 0.1 0.00176751849809336
+-1.4594305849579 0.2 0.00532161106376017
+-1.30943058495791 0.1 0.00386730566696142
+-1.15943058495791 0.2 0.0108735635349179
+-1.0094305849579 0.1 0.00740601835535395
+-0.859430584957905 0.2 0.0195837513130162
+-0.709430584957905 0.1 0.0125849259586546
+-0.559430584957905 0.2 0.0314887051813321
+-0.409430584957905 0.1 0.0191948082376024
+-0.259430584957905 0.2 0.0456519180921292
+-0.109430584957905 0.1 0.0264953977337527
+0.040569415042095 0.2 0.060070766179351
+0.190569415042095 0.1 0.0332633993810258
+0.340569415042095 0.2 0.0719917642881179
+0.490569415042095 0.1 0.0380637898902835
+0.640569415042095 0.2 0.0786564457361483
+0.790569415042095 0.0999999999999999 0.0396941599902116
+0.940569415042095 0.2 0.0782412744009736
+1.09056941504209 0.1 0.0376262137261268
+1.2405694150421 0.2 0.0705783338474663
+1.3905694150421 0.1 0.0322423441110482
+1.5405694150421 0.2 0.057325866269257
+1.6905694150421 0.1 0.0247577062768794
+1.8405694150421 0.2 0.041489467946484
+1.9905694150421 0.0515717641596508 0.0086812044484898
+1.99528470752105 0.00628705663860322 0.00105082035484165
+2 0.00157176415965081 0.00026083569600901