pystatsbio 1.0.0__tar.gz

pystatsbio-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pystatsbio-1.0.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Fixtures (generated, but tracked)
+# tests/fixtures/*.json are tracked in git

pystatsbio-1.0.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## 1.0.0
+
+Initial release.
+
+### Modules
+
+- **`power/`** — Sample size and power calculations for clinical trial designs:
+  two-sample and paired t-tests, proportions (chi-squared, Fisher exact), log-rank
+  (survival), one-way and factorial ANOVA, non-inferiority/equivalence/superiority
+  for means and proportions, crossover bioequivalence (PowerTOST method), and
+  cluster-randomized trials. Validated against R packages `pwr`, `TrialSize`,
+  `gsDesign`, `PowerTOST`, and `samplesize`.
+
+- **`doseresponse/`** — Dose-response modeling for preclinical pharmacology:
+  4-parameter log-logistic (4PL/LL.4), 5-parameter log-logistic (5PL/LL.5),
+  Weibull-1, Weibull-2, Brain-Cousens hormesis models. EC50/IC50 estimation,
+  relative potency (parallelism-tested), benchmark dose (BMD/BMDL) analysis,
+  and GPU-accelerated batch fitting for high-throughput screening. Validated
+  against R packages `drc` and `BMDS`.
+
+- **`diagnostic/`** — Diagnostic accuracy analysis for biomarker evaluation:
+  ROC curves with DeLong AUC and confidence intervals, Delong AUC comparison test,
+  sensitivity/specificity/PPV/NPV/likelihood ratios at any threshold, optimal
+  cutoff selection (Youden, min-distance, cost-weighted), and batch AUC computation
+  for biomarker panel screening. Validated against R packages `pROC`,
+  `OptimalCutpoints`, and `epiR`.
+
+- **`pk/`** — Non-compartmental pharmacokinetic analysis (NCA): AUC (linear,
+  log-linear, linear-up/log-down trapezoidal), Cmax, Tmax, terminal elimination
+  rate constant (lambda_z), half-life, clearance (IV and extravascular), volume of
+  distribution, AUMC, and MRT. Validated against R packages `PKNCA` and
+  `NonCompart`.

pystatsbio-1.0.0/CLAUDE.md

@@ -0,0 +1,190 @@
+# Coding Bible
+
+## Preamble
+
+This document is not a style guide. It is not a set of preferences. It is not a list of
+suggestions that can be weighed against convenience or time pressure.
+
+Every rule in this document exists because its absence has caused real, costly, documented
+failures in real systems — bugs that took days to trace, security holes that went undetected
+for months, codebases that became unmaintainable within a year of being written. The rules
+are the scar tissue. They are what you get when you ask experienced engineers what they wish
+someone had forced them to do the first time.
+
+When you are implementing something and a rule feels inconvenient, that feeling is a signal,
+not a reason to deviate. Inconvenience usually means the rule is doing its job — preventing
+the path of least resistance from becoming a future liability.
+
+**These rules are non-negotiable and not subject to contextual override.** The following
+exceptions are not acceptable justifications for deviation:
+
+- "This is a prototype / MVP / quick fix." Prototypes become production. Quick fixes become
+  permanent. Code written without discipline under time pressure is the most dangerous code
+  that exists.
+- "This is a small module that doesn't need it." Small modules grow. The time to enforce
+  structure is before the module is large enough to make restructuring painful.
+- "The architecture requires it." If the architecture requires violating these rules, the
+  architecture is wrong. Fix the architecture.
+- "It would take too long to do it correctly." It will take longer to fix it later. It always
+  does.
+
+If a genuine, documented edge case exists where a rule cannot be followed, that exception
+must be explicitly marked in a comment at the relevant location, stating which rule is being
+waived, why, and what mitigating measures are in place. Undocumented deviations are bugs.
+
+---
+
+## The Underlying Principle
+
+All seven rules are expressions of one idea:
+
+**Make the wrong thing hard to do accidentally.**
+
+Good architecture is not about making correct behavior possible. Correct behavior is always
+possible. Good architecture is about making incorrect behavior require deliberate, visible,
+documented effort — so that mistakes are loud, localized, and recoverable rather than silent,
+diffuse, and permanent.
+
+When in doubt, ask: *am I making the wrong thing easy to do accidentally?* If yes, stop and
+apply the relevant rule before continuing.
+
+---
+
+These rules are non-negotiable. They exist because every one of them corresponds to a
+real failure mode with real consequences. If you think a rule doesn't apply to a specific
+case, you are probably wrong. If you are certain it doesn't apply, document why explicitly
+in a comment before proceeding.
+
+---
+
+## 1. Fail Fast, Fail Loud, No Defaults
+
+Do not insert default behavior that fails silently. If something breaks, the system must
+break immediately, obviously, and traceably.
+
+**Rules:**
+- Raise explicit, descriptive errors. Never swallow exceptions.
+- Never return a default value to mask a missing or invalid state.
+- Log the failure with enough context to reproduce it.
+
+**Corollary — No Optimistic Assumptions:**
+Do not assume inputs are valid, dependencies are available, or external calls succeed.
+Assert and verify. If an assumption is required, document it and enforce it with a guard.
+
+---
+
+## 2. Trust Your Neighbors — Validate Input, Not Output
+
+You own your output contract. You do not trust anyone else's input contract.
+
+**Rules:**
+- All external inputs (API calls, user input, file reads, environment variables) must be
+  validated at the boundary before use.
+- Internal module output does not need re-validation by the caller — the module is
+  responsible for the correctness of what it emits.
+
+**Corollary — Define Your Contracts:**
+Every module must have an explicit, documented input/output contract. If a caller violates
+the input contract, the module must fail loudly (see Rule 1), not silently compensate.
+
+---
+
+## 3. UNIX Philosophy — One Module, One Job
+
+Each module does one thing only, and does that one thing well. If a module needs to do
+multiple things, it must be split into multiple files.
+
+**Rules:**
+- No file should be the sole owner of more than one domain concept.
+- If you find yourself writing "and" when describing what a file does, split it.
+- Tight coupling between modules is a design failure, not an implementation detail.
+
+**Corollary — No God Files:**
+A module that knows everything, owns everything, or touches everything is a liability.
+If removing a module would require changes across more than two other modules, it is
+probably doing too much.
+
+---
+
+## 4. LOC Limits — No Bloated Monoliths
+
+Files must not become monoliths. Complexity must be managed through decomposition,
+not consolidation.
+
+**Rules:**
+- **Hard limit: 500 lines of code** (comments and docstrings excluded). Do not exceed this
+  under any circumstances.
+- **Soft limit: 400 lines of code.** Above 400 lines, actively look for split opportunities.
+- If a file "requires" more than 500 lines, that is a signal the abstraction is wrong —
+  split it into multiple focused files.
+
+**Corollary — Splitting Is Not Optional:**
+Exceeding the hard limit is never acceptable, even temporarily. Split first, implement after.
+
+---
+
+## 5. No Hidden State — Explicit Data Flow
+
+All state must be explicitly passed or managed through clearly defined interfaces.
+Hidden state is a bug waiting to be discovered at the worst possible time.
+
+**Rules:**
+- No global variables. No module-level mutable state unless explicitly documented and
+  architecturally justified.
+- No implicit state — if a function's behavior depends on something, that something must
+  appear in its signature or be explicitly injected.
+- No hidden coupling between modules. If two modules share state, that relationship must
+  be visible and intentional.
+
+**Corollary — Spooky Action at a Distance Is a Bug:**
+If changing module A causes unexpected behavior in module B, and there is no explicit
+interface between them, the architecture is broken. Fix the architecture, not the symptom.
+
+---
+
+## 6. Deterministic Behavior by Default
+
+All functions must be deterministic unless explicitly documented otherwise.
+
+**Rules:**
+- No randomness, time-dependent logic, or non-deterministic behavior without explicit
+  documentation and an injectable seed or clock interface for testing.
+- Functions that depend on system time, random state, or external non-deterministic
+  sources must be flagged with a `# NON-DETERMINISTIC:` comment explaining why.
+- Non-deterministic behavior must be isolatable — wrap it so the rest of the system
+  can be tested deterministically.
+
+**Corollary — Reproducibility Is Not Optional:**
+If a bug cannot be reliably reproduced, it cannot be reliably fixed. Non-determinism
+is the enemy of reproducibility. Treat it like a dependency that must be explicitly
+managed, not a feature.
+
+---
+
+## 7. Tests Are First-Class Citizens
+
+Every module must have corresponding tests. Tests are not optional, not afterthoughts,
+and not someone else's job.
+
+**Rules:**
+- Every module must have a corresponding test file covering:
+  - **Normal cases** — expected inputs produce expected outputs.
+  - **Edge cases** — boundary conditions, empty inputs, maximum values, type boundaries.
+  - **Failure cases** — invalid inputs produce the correct explicit errors (see Rule 1).
+- No module ships without tests. No exceptions.
+- Tests must be runnable in isolation — no test should depend on the state left by
+  another test.
+
+**Corollary — Untested Code Is Unverified Assumptions:**
+If there is no test for a behavior, that behavior is assumed, not verified. Assumptions
+accumulate into system failures. If you cannot write a test for something, that is a signal
+the design is wrong.
+
+---
+
+## Meta-Rule
+
+If any of these rules feel inconvenient, that feeling is the point. These rules exist
+precisely because the convenient path leads to the failure modes each rule was written
+to prevent. When in doubt, ask: *am I making the wrong thing easy to do accidentally?*
+If yes, apply the relevant rule.

pystatsbio-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hai-Shuo
+
+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.

pystatsbio-1.0.0/PKG-INFO

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: pystatsbio
+Version: 1.0.0
+Summary: Biotech and pharmaceutical statistical computing for Python
+Project-URL: Homepage, https://sgcx.org/technology/pystatsbio/
+Project-URL: Documentation, https://sgcx.org/docs/pystatsbio/
+Project-URL: Repository, https://github.com/sgcx-org/pystatsbio
+Project-URL: Issues, https://github.com/sgcx-org/pystatsbio/issues
+Author-email: Hai-Shuo <contact@sgcx.org>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: biostatistics,clinical-trials,diagnostics,dose-response,gpu,pharmacokinetics,power-analysis,sample-size
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.24
+Requires-Dist: pystatistics>=0.1.0
+Requires-Dist: scipy>=1.10
+Provides-Extra: all
+Requires-Dist: furo; extra == 'all'
+Requires-Dist: mypy>=1.0; extra == 'all'
+Requires-Dist: pytest-cov>=4.0; extra == 'all'
+Requires-Dist: pytest>=7.0; extra == 'all'
+Requires-Dist: ruff>=0.1; extra == 'all'
+Requires-Dist: sphinx>=6.0; extra == 'all'
+Requires-Dist: torch>=2.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: furo; extra == 'docs'
+Requires-Dist: sphinx>=6.0; extra == 'docs'
+Provides-Extra: gpu
+Requires-Dist: torch>=2.0; extra == 'gpu'
+Description-Content-Type: text/markdown
+
+# PyStatsBio
+
+Biotech and pharmaceutical statistical computing for Python.
+
+Built on [PyStatistics](https://github.com/sgcx-org/pystatistics) for the general statistical
+computing layer. PyStatsBio provides domain-specific methods for the drug development pipeline:
+dose-response modeling, sample size/power, diagnostic accuracy, and non-compartmental
+pharmacokinetics.
+
+---
+
+## Design Philosophy
+
+PyStatsBio follows the same principles as PyStatistics:
+
+1. **Fail fast, fail loud** — no silent fallbacks or "helpful" defaults
+2. **Explicit over implicit** — require parameters, don't assume intent
+3. **R-level validation** — every function is validated against a named R reference
+
+Each function states exactly which R function it replicates and to what tolerance.
+
+---
+
+## Quick Start
+
+```python
+# --- Clinical trial power / sample size ---
+from pystatsbio import power
+
+# Solve for sample size (two-sample t-test)
+result = power.power_t_test(d=0.5, power=0.80, alpha=0.05, type="two.sample")
+print(result.n)          # per-group sample size
+print(result.summary())
+
+# Solve for power given n
+result = power.power_t_test(n=64, d=0.5, alpha=0.05, type="two.sample")
+print(result.power)
+
+# Paired t-test
+result = power.power_paired_t_test(d=0.3, power=0.80, alpha=0.05)
+print(result.n)
+
+# Proportions
+result = power.power_prop_test(p1=0.30, p2=0.50, power=0.80, alpha=0.05)
+print(result.n)
+
+# Survival (log-rank)
+result = power.power_logrank(
+    p1=0.60, p2=0.40, accrual=12, follow=24, power=0.80, alpha=0.05
+)
+print(result.n_events, result.n_total)
+
+# Non-inferiority for means
+result = power.power_noninf_mean(
+    delta=0.0, sigma=1.0, margin=0.5, power=0.80, alpha=0.05
+)
+print(result.n)
+
+# Crossover bioequivalence (PowerTOST method)
+result = power.power_crossover_be(cv=0.20, power=0.80, alpha=0.05)
+print(result.n)          # subjects per sequence
+
+# Cluster-randomized trial
+result = power.power_cluster(
+    d=0.5, icc=0.05, m=20, power=0.80, alpha=0.05
+)
+print(result.n_clusters)
+
+
+# --- Dose-response modeling ---
+import numpy as np
+from pystatsbio import doseresponse
+
+dose = np.array([0.001, 0.01, 0.1, 1.0, 10.0, 100.0])
+response = np.array([2.1, 3.5, 12.0, 48.0, 87.5, 97.8])
+
+# Fit 4PL (LL.4) model
+result = doseresponse.fit_drm(dose, response, model="LL.4")
+print(result.params)     # CurveParams(b, c, d, e) — Hill slope, lower, upper, EC50
+print(result.ec50)
+print(result.summary())
+
+# Fit 5PL (asymmetric)
+result = doseresponse.fit_drm(dose, response, model="LL.5")
+print(result.params)
+
+# Extract EC50 with confidence interval
+ec50_result = doseresponse.ec50(result)
+print(ec50_result.ec50, ec50_result.ci_lower, ec50_result.ci_upper)
+
+# Relative potency (reference vs. test compound)
+ref_result = doseresponse.fit_drm(dose, response, model="LL.4")
+test_result = doseresponse.fit_drm(dose * 3, response, model="LL.4")
+rp = doseresponse.relative_potency(ref_result, test_result)
+print(rp.ratio, rp.ci_lower, rp.ci_upper, rp.parallel)
+
+# Benchmark dose (BMD/BMDL)
+bmd_result = doseresponse.bmd(result, bmr=0.10)
+print(bmd_result.bmd, bmd_result.bmdl)
+
+# Batch fitting (GPU-accelerated for HTS)
+# responses: (n_curves, n_doses) array
+responses = np.random.rand(500, 6) * 100
+batch = doseresponse.fit_drm_batch(dose, responses, model="LL.4", backend="auto")
+print(batch.ec50)        # shape (500,)
+print(batch.params)      # CurveParams with shape-(500,) arrays
+
+
+# --- Diagnostic accuracy ---
+from pystatsbio import diagnostic
+
+scores = np.array([0.1, 0.4, 0.35, 0.8, 0.9, 0.15, 0.6, 0.75, 0.55, 0.95])
+labels = np.array([0, 0, 0, 1, 1, 0, 1, 1, 0, 1])
+
+# ROC curve + AUC
+roc_result = diagnostic.roc(scores, labels)
+print(roc_result.auc, roc_result.ci_lower, roc_result.ci_upper)
+print(roc_result.sensitivity, roc_result.specificity)
+
+# Compare two biomarkers (DeLong test)
+scores2 = np.random.rand(10)
+test_result = diagnostic.roc_test(scores, scores2, labels)
+print(test_result.p_value, test_result.summary())
+
+# Full diagnostic accuracy at a threshold
+da = diagnostic.diagnostic_accuracy(scores, labels, threshold=0.5)
+print(da.sensitivity, da.specificity, da.ppv, da.npv, da.lr_pos, da.lr_neg)
+
+# Optimal cutoff selection
+cutoff = diagnostic.optimal_cutoff(roc_result, method="youden")
+print(cutoff.threshold, cutoff.sensitivity, cutoff.specificity, cutoff.youden_index)
+
+# Batch AUC for biomarker panel screening
+# panel: (n_biomarkers, n_subjects) array
+panel = np.random.rand(200, 100)
+batch_auc = diagnostic.batch_auc(panel, labels[:100] if len(labels) >= 100 else np.random.randint(0, 2, 100))
+print(batch_auc.auc)     # shape (200,) — one AUC per biomarker
+
+
+# --- Pharmacokinetics (NCA) ---
+from pystatsbio import pk
+
+time = np.array([0, 0.5, 1, 2, 4, 6, 8, 12, 24])
+conc = np.array([0, 8.5, 12.1, 10.4, 7.2, 4.9, 3.1, 1.4, 0.3])
+
+result = pk.nca(time, conc, route="ev", dose=100.0)
+print(result.cmax, result.tmax)
+print(result.auc_last, result.auc_inf)
+print(result.half_life)
+print(result.cl, result.vd)
+print(result.aumc_last, result.mrt)
+print(result.summary())
+```
+
+---
+
+## Modules
+
+| Module | Status | Description |
+|--------|--------|-------------|
+| `power/` | Complete | Sample size and power for clinical trial designs |
+| `doseresponse/` | Complete | 4PL/5PL curve fitting, EC50, relative potency, BMD, batch HTS |
+| `diagnostic/` | Complete | ROC, AUC, sensitivity/specificity, optimal cutoff, batch biomarker |
+| `pk/` | Complete | Non-compartmental PK analysis (NCA): AUC, Cmax, CL, Vd, MRT |
+
+### `power` — Sample Size and Power
+
+| Function | R equivalent |
+|----------|--------------|
+| `power_t_test()` | `pwr::pwr.t.test()` |
+| `power_paired_t_test()` | `pwr::pwr.t.test(type="paired")` |
+| `power_prop_test()` | `pwr::pwr.2p.test()` |
+| `power_fisher_test()` | `TrialSize::TwoSampleProportion.Equality()` |
+| `power_logrank()` | `gsDesign::nSurv()` |
+| `power_anova_oneway()` | `pwr::pwr.anova.test()` |
+| `power_anova_factorial()` | `TrialSize::FactorialDesign()` |
+| `power_noninf_mean()` | `TrialSize::TwoSampleMean.NIS()` |
+| `power_noninf_prop()` | `TrialSize::TwoSampleProportion.NIS()` |
+| `power_equiv_mean()` | `TrialSize::TwoSampleMean.Equivalence()` |
+| `power_superiority_mean()` | `TrialSize::TwoSampleMean.Superiority()` |
+| `power_crossover_be()` | `PowerTOST::sampleSize()` |
+| `power_cluster()` | `samplesize::n.twogroup()` with ICC |
+
+### `doseresponse` — Dose-Response Modeling
+
+| Function | R equivalent |
+|----------|--------------|
+| `fit_drm()` | `drc::drm()` |
+| `fit_drm_batch()` | vectorized `drc::drm()` |
+| `ec50()` | `drc::ED()` |
+| `relative_potency()` | `drc::EDcomp()` with parallelism test |
+| `bmd()` | `drc::bmd()` / `BMDS` |
+
+Models: `LL.4` (4PL), `LL.5` (5PL), `W1.4` (Weibull-1), `W2.4` (Weibull-2),
+`BC.4` (Brain-Cousens hormesis).
+
+### `diagnostic` — Diagnostic Accuracy
+
+| Function | R equivalent |
+|----------|-------------|
+| `roc()` | `pROC::roc()` with DeLong CI |
+| `roc_test()` | `pROC::roc.test()` (DeLong) |
+| `diagnostic_accuracy()` | `epiR::epi.tests()` |
+| `optimal_cutoff()` | `OptimalCutpoints::optimal.cutpoints()` |
+| `batch_auc()` | vectorized `pROC::auc()` |
+
+### `pk` — Non-Compartmental Analysis
+
+| Function | R equivalent |
+|----------|-------------|
+| `nca()` | `PKNCA::pk.nca()` / `NonCompart::sNCA()` |
+
+AUC methods: `linear`, `log`, `linear-up/log-down` (FDA default).
+Routes: `iv` (intravenous), `ev` (extravascular).
+
+---
+
+## Installation
+
+```bash
+pip install pystatsbio
+
+# With GPU support (requires PyTorch)
+pip install pystatsbio[gpu]
+
+# Development
+pip install pystatsbio[dev]
+```
+
+Requires Python 3.11+. Core dependencies: `pystatistics`, `numpy`, `scipy`.
+
+---
+
+## License
+
+MIT
+
+## Author
+
+Hai-Shuo (contact@sgcx.org)