compatpower 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,15 @@
1
+ name: tests
2
+ on: [push, pull_request]
3
+ jobs:
4
+ test:
5
+ runs-on: ubuntu-latest
6
+ strategy:
7
+ matrix:
8
+ python-version: ["3.10", "3.12", "3.13"]
9
+ steps:
10
+ - uses: actions/checkout@v4
11
+ - uses: actions/setup-python@v5
12
+ with:
13
+ python-version: ${{ matrix.python-version }}
14
+ - run: pip install -e ".[test]"
15
+ - run: pytest -q
@@ -0,0 +1,6 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.egg-info/
4
+ dist/
5
+ build/
6
+ .pytest_cache/
@@ -0,0 +1,11 @@
1
+ {
2
+ "title": "compatpower: power, equivalence and design of in vitro compatibility assays between biological control agents and pesticides",
3
+ "upload_type": "software",
4
+ "license": "MIT",
5
+ "creators": [
6
+ {"name": "Siriani, Allan Lincoln Rodrigues", "orcid": "0000-0001-6351-2642", "affiliation": "São Paulo State University (UNESP)"},
7
+ {"name": "Leite, Susi Meire Maximino", "orcid": "0009-0002-8764-680X", "affiliation": "Centro Paula Souza (CPS), Fatec Pompeia"}
8
+ ],
9
+ "keywords": ["statistical power", "equivalence test", "compatibility", "entomopathogenic fungi", "biological control", "pesticides", "experimental design"],
10
+ "description": "Simulation-based power, equivalence (TOST) and run-by-plate allocation for in vitro compatibility assays, with parameter estimation from a laboratory's own plate counts."
11
+ }
@@ -0,0 +1,18 @@
1
+ cff-version: 1.2.0
2
+ message: "If you use this software, please cite it as below."
3
+ title: "compatpower: power, equivalence and design of in vitro compatibility assays between biological control agents and pesticides"
4
+ version: 0.1.0
5
+ doi: "10.5281/zenodo.24380785"
6
+ date-released: "2026-11-19"
7
+ license: MIT
8
+ repository-code: "https://github.com/siriani/compatpower"
9
+ authors:
10
+ - family-names: Siriani
11
+ given-names: Allan Lincoln Rodrigues
12
+ orcid: "https://orcid.org/0000-0001-6351-2642"
13
+ affiliation: "Graduate Program in Agribusiness and Development, School of Sciences and Engineering, São Paulo State University (UNESP), Tupã, Brazil"
14
+ - family-names: Leite
15
+ given-names: Susi Meire Maximino
16
+ orcid: "https://orcid.org/0009-0002-8764-680X"
17
+ affiliation: "Centro Paula Souza (CPS), Faculdade de Tecnologia Shunji Nishimura (Fatec Pompeia), Pompeia, Brazil"
18
+ keywords: [statistical power, equivalence test, compatibility, entomopathogenic fungi, biological control, pesticides, experimental design]
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Allan Lincoln Rodrigues Siriani and Susi Meire Maximino Leite
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,78 @@
1
+ Metadata-Version: 2.5
2
+ Name: compatpower
3
+ Version: 0.1.0
4
+ Summary: Power, equivalence and design of in vitro compatibility assays between biological control agents and pesticides
5
+ Project-URL: Repository, https://github.com/siriani/compatpower
6
+ Author: Allan Lincoln Rodrigues Siriani, Susi Meire Maximino Leite
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Keywords: biological control,compatibility,entomopathogenic fungi,equivalence test,experimental design,pesticides,statistical power
10
+ Classifier: Intended Audience :: Science/Research
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
13
+ Classifier: Topic :: Scientific/Engineering :: Mathematics
14
+ Requires-Python: >=3.10
15
+ Requires-Dist: numpy>=1.24
16
+ Requires-Dist: pandas>=2.0
17
+ Requires-Dist: scipy>=1.10
18
+ Provides-Extra: test
19
+ Requires-Dist: pytest>=7; extra == 'test'
20
+ Description-Content-Type: text/markdown
21
+
22
+ # compatpower
23
+
24
+ [![tests](https://github.com/siriani/compatpower/actions/workflows/tests.yml/badge.svg)](https://github.com/siriani/compatpower/actions/workflows/tests.yml)
25
+ [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.24380785.svg)](https://doi.org/10.5281/zenodo.24380785)
26
+
27
+ **Power, equivalence and design of in vitro compatibility assays between biological control agents and pesticides.**
28
+
29
+ In vitro compatibility assays (for example, colony-forming units of an entomopathogenic fungus on medium with a pesticide) are often run on a single day with 3–5 plates per treatment. "Compatible" is then declared when the treatment does not differ significantly from the control. `compatpower` simulates such assays to answer three planning questions:
30
+
31
+ - How likely is my design to detect a given reduction (power)?
32
+ - How likely is it to **demonstrate compatibility** with an equivalence test (TOST on the treatment/control ratio)?
33
+ - Given a fixed number of plates, how should I split them into independent runs (days) and plates per run?
34
+
35
+ ## Model
36
+ Plate counts follow a negative binomial (variance = μ + μ²/k). Each run (day) shifts both groups by a random effect (`sd_run`). The product effect may vary between runs, which is the run × treatment interaction (`tau`). Analyses compared:
37
+ - `run`: the run is the experimental unit (paired *t* test on per-run log mean differences). This is recommended and keeps the nominal error rate.
38
+ - `pooled`: plates are treated as replicates, as is common practice. Error inflates when `tau > 0`.
39
+ - `blocked`: plates with the run as a block, equivalent to a random-run-intercept mixed model.
40
+
41
+ ## Install
42
+ ```bash
43
+ pip install compatpower # after release
44
+ pip install git+https://github.com/siriani/compatpower
45
+ ```
46
+
47
+ ## Quick start
48
+ ```python
49
+ from compatpower import AssayModel, power, equivalence, design_table, allocate, estimate_model
50
+
51
+ m = AssayModel(mu0=25, k=4.3, sd_run=0.48, tau=0.15) # defaults: CFU of a B. bassiana isolate
52
+ power(runs=6, plates=10, reduction=0.3, model=m) # ~0.70
53
+ equivalence(runs=8, plates=20, margin=(0.75, 1/0.75), model=m)
54
+ allocate(total_plates=60, reduction=0.3, model=m) # 2x30 vs 10x6 vs 20x3 ...
55
+ design_table(model=m) # runs x plates table
56
+
57
+ import pandas as pd # your own counts: run, group, count [, product]
58
+ model, report = estimate_model(pd.read_csv("my_counts.csv"))
59
+ ```
60
+
61
+ Command line:
62
+ ```bash
63
+ compatpower power --runs 6 --plates 10 --reduction 0.3
64
+ compatpower allocate --total 60
65
+ compatpower table --out design.csv
66
+ compatpower estimate examples/example_counts.csv
67
+ ```
68
+
69
+ ## Defaults and caveats
70
+ The default parameters are estimated from CFU counts of *Beauveria bassiana* isolate IBCB 170 over three runs. `sd_run` is imprecise (three runs), and `tau` was assumed (0.15), because it can be estimated only when the same product is tested in several runs. Estimate the parameters from your own data whenever possible (`estimate_model`). Analyses use log(count + 0.5). A negative binomial mixed model is the natural alternative for final analyses.
71
+
72
+ ## Citation
73
+ Siriani ALR, Leite SMM. compatpower: power, equivalence and design of in vitro compatibility assays between biological control agents and pesticides (version 0.1.0). Zenodo; 2026. https://doi.org/10.5281/zenodo.24380785
74
+
75
+ Please also cite the accompanying article (in preparation).
76
+
77
+ ## License
78
+ MIT
@@ -0,0 +1,57 @@
1
+ # compatpower
2
+
3
+ [![tests](https://github.com/siriani/compatpower/actions/workflows/tests.yml/badge.svg)](https://github.com/siriani/compatpower/actions/workflows/tests.yml)
4
+ [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.24380785.svg)](https://doi.org/10.5281/zenodo.24380785)
5
+
6
+ **Power, equivalence and design of in vitro compatibility assays between biological control agents and pesticides.**
7
+
8
+ In vitro compatibility assays (for example, colony-forming units of an entomopathogenic fungus on medium with a pesticide) are often run on a single day with 3–5 plates per treatment. "Compatible" is then declared when the treatment does not differ significantly from the control. `compatpower` simulates such assays to answer three planning questions:
9
+
10
+ - How likely is my design to detect a given reduction (power)?
11
+ - How likely is it to **demonstrate compatibility** with an equivalence test (TOST on the treatment/control ratio)?
12
+ - Given a fixed number of plates, how should I split them into independent runs (days) and plates per run?
13
+
14
+ ## Model
15
+ Plate counts follow a negative binomial (variance = μ + μ²/k). Each run (day) shifts both groups by a random effect (`sd_run`). The product effect may vary between runs, which is the run × treatment interaction (`tau`). Analyses compared:
16
+ - `run`: the run is the experimental unit (paired *t* test on per-run log mean differences). This is recommended and keeps the nominal error rate.
17
+ - `pooled`: plates are treated as replicates, as is common practice. Error inflates when `tau > 0`.
18
+ - `blocked`: plates with the run as a block, equivalent to a random-run-intercept mixed model.
19
+
20
+ ## Install
21
+ ```bash
22
+ pip install compatpower # after release
23
+ pip install git+https://github.com/siriani/compatpower
24
+ ```
25
+
26
+ ## Quick start
27
+ ```python
28
+ from compatpower import AssayModel, power, equivalence, design_table, allocate, estimate_model
29
+
30
+ m = AssayModel(mu0=25, k=4.3, sd_run=0.48, tau=0.15) # defaults: CFU of a B. bassiana isolate
31
+ power(runs=6, plates=10, reduction=0.3, model=m) # ~0.70
32
+ equivalence(runs=8, plates=20, margin=(0.75, 1/0.75), model=m)
33
+ allocate(total_plates=60, reduction=0.3, model=m) # 2x30 vs 10x6 vs 20x3 ...
34
+ design_table(model=m) # runs x plates table
35
+
36
+ import pandas as pd # your own counts: run, group, count [, product]
37
+ model, report = estimate_model(pd.read_csv("my_counts.csv"))
38
+ ```
39
+
40
+ Command line:
41
+ ```bash
42
+ compatpower power --runs 6 --plates 10 --reduction 0.3
43
+ compatpower allocate --total 60
44
+ compatpower table --out design.csv
45
+ compatpower estimate examples/example_counts.csv
46
+ ```
47
+
48
+ ## Defaults and caveats
49
+ The default parameters are estimated from CFU counts of *Beauveria bassiana* isolate IBCB 170 over three runs. `sd_run` is imprecise (three runs), and `tau` was assumed (0.15), because it can be estimated only when the same product is tested in several runs. Estimate the parameters from your own data whenever possible (`estimate_model`). Analyses use log(count + 0.5). A negative binomial mixed model is the natural alternative for final analyses.
50
+
51
+ ## Citation
52
+ Siriani ALR, Leite SMM. compatpower: power, equivalence and design of in vitro compatibility assays between biological control agents and pesticides (version 0.1.0). Zenodo; 2026. https://doi.org/10.5281/zenodo.24380785
53
+
54
+ Please also cite the accompanying article (in preparation).
55
+
56
+ ## License
57
+ MIT
@@ -0,0 +1,65 @@
1
+ run,group,product,count
2
+ day1,control,,15
3
+ day1,control,,16
4
+ day1,control,,15
5
+ day1,control,,13
6
+ day1,control,,10
7
+ day1,control,,12
8
+ day1,control,,24
9
+ day1,control,,9
10
+ day1,treatment,A,8
11
+ day1,treatment,A,24
12
+ day1,treatment,A,13
13
+ day1,treatment,A,13
14
+ day1,treatment,A,8
15
+ day1,treatment,A,12
16
+ day1,treatment,A,15
17
+ day1,treatment,A,21
18
+ day2,control,,57
19
+ day2,control,,25
20
+ day2,control,,36
21
+ day2,control,,13
22
+ day2,control,,15
23
+ day2,control,,14
24
+ day2,control,,63
25
+ day2,control,,16
26
+ day2,treatment,A,23
27
+ day2,treatment,A,25
28
+ day2,treatment,A,8
29
+ day2,treatment,A,9
30
+ day2,treatment,A,30
31
+ day2,treatment,A,15
32
+ day2,treatment,A,18
33
+ day2,treatment,A,17
34
+ day3,control,,20
35
+ day3,control,,14
36
+ day3,control,,5
37
+ day3,control,,6
38
+ day3,control,,3
39
+ day3,control,,15
40
+ day3,control,,12
41
+ day3,control,,10
42
+ day3,treatment,A,12
43
+ day3,treatment,A,7
44
+ day3,treatment,A,1
45
+ day3,treatment,A,4
46
+ day3,treatment,A,7
47
+ day3,treatment,A,12
48
+ day3,treatment,A,8
49
+ day3,treatment,A,2
50
+ day4,control,,82
51
+ day4,control,,22
52
+ day4,control,,43
53
+ day4,control,,41
54
+ day4,control,,18
55
+ day4,control,,66
56
+ day4,control,,51
57
+ day4,control,,49
58
+ day4,treatment,A,49
59
+ day4,treatment,A,31
60
+ day4,treatment,A,8
61
+ day4,treatment,A,18
62
+ day4,treatment,A,73
63
+ day4,treatment,A,34
64
+ day4,treatment,A,23
65
+ day4,treatment,A,22
@@ -0,0 +1,39 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "compatpower"
7
+ dynamic = ["version"]
8
+ description = "Power, equivalence and design of in vitro compatibility assays between biological control agents and pesticides"
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ requires-python = ">=3.10"
13
+ authors = [
14
+ { name = "Allan Lincoln Rodrigues Siriani" },
15
+ { name = "Susi Meire Maximino Leite" },
16
+ ]
17
+ keywords = ["statistical power", "equivalence test", "compatibility", "entomopathogenic fungi", "biological control", "pesticides", "experimental design"]
18
+ classifiers = [
19
+ "Programming Language :: Python :: 3",
20
+ "Intended Audience :: Science/Research",
21
+ "Topic :: Scientific/Engineering :: Bio-Informatics",
22
+ "Topic :: Scientific/Engineering :: Mathematics",
23
+ ]
24
+ dependencies = ["numpy>=1.24", "scipy>=1.10", "pandas>=2.0"]
25
+
26
+ [project.optional-dependencies]
27
+ test = ["pytest>=7"]
28
+
29
+ [project.scripts]
30
+ compatpower = "compatpower.cli:main"
31
+
32
+ [project.urls]
33
+ Repository = "https://github.com/siriani/compatpower"
34
+
35
+ [tool.hatch.version]
36
+ path = "src/compatpower/__init__.py"
37
+
38
+ [tool.hatch.build.targets.wheel]
39
+ packages = ["src/compatpower"]
@@ -0,0 +1,10 @@
1
+ """compatpower: power, equivalence and design of in vitro compatibility assays
2
+ between biological control agents and pesticides."""
3
+ __version__ = "0.1.0"
4
+
5
+ from .model import AssayModel, simulate_counts
6
+ from .design import allocate, design_table, equivalence, power, required_runs
7
+ from .estimate import estimate_model, estimate_k
8
+
9
+ __all__ = ["AssayModel", "simulate_counts", "power", "equivalence", "design_table", "allocate",
10
+ "required_runs", "estimate_model", "estimate_k", "__version__"]
@@ -0,0 +1,75 @@
1
+ """Vectorised tests applied to simulated assays (all on the log(count + 0.5) scale)."""
2
+ from __future__ import annotations
3
+
4
+ import numpy as np
5
+ from scipy import stats
6
+
7
+ OFFSET = 0.5
8
+
9
+
10
+ def _run_differences(yc: np.ndarray, yt: np.ndarray) -> np.ndarray:
11
+ """Per-run difference of log mean counts, shape (n_sim, runs)."""
12
+ return np.log(yt.mean(2) + OFFSET) - np.log(yc.mean(2) + OFFSET)
13
+
14
+
15
+ def test_run_level(yc: np.ndarray, yt: np.ndarray, alpha: float = 0.05) -> np.ndarray:
16
+ """Paired t test on per-run differences (run = experimental unit). Needs >= 2 runs."""
17
+ runs = yc.shape[1]
18
+ if runs < 2:
19
+ raise ValueError("run-level analysis needs at least 2 runs")
20
+ d = _run_differences(yc, yt)
21
+ m, se = d.mean(1), d.std(1, ddof=1) / np.sqrt(runs)
22
+ with np.errstate(divide="ignore", invalid="ignore"):
23
+ p = 2 * stats.t.sf(np.abs(m / se), runs - 1)
24
+ return np.nan_to_num(p, nan=1.0) < alpha
25
+
26
+
27
+ def test_plates_pooled(yc: np.ndarray, yt: np.ndarray, alpha: float = 0.05) -> np.ndarray:
28
+ """Welch t test pooling all plates (plates treated as replicates; common practice)."""
29
+ n = yc.shape[0]
30
+ lc = np.log(yc.reshape(n, -1) + OFFSET)
31
+ lt = np.log(yt.reshape(n, -1) + OFFSET)
32
+ p = stats.ttest_ind(lt, lc, axis=1, equal_var=False).pvalue
33
+ return np.nan_to_num(p, nan=1.0) < alpha
34
+
35
+
36
+ def test_plates_blocked(yc: np.ndarray, yt: np.ndarray, alpha: float = 0.05) -> np.ndarray:
37
+ """Additive ANOVA (run + group) on plates; equals a random-run-intercept model. Needs >= 2 runs."""
38
+ _, runs, plates = yc.shape
39
+ if runs < 2:
40
+ raise ValueError("blocked analysis needs at least 2 runs")
41
+ lc, lt = np.log(yc + OFFSET), np.log(yt + OFFSET)
42
+ mc, mt = lc.mean(2), lt.mean(2)
43
+ d = mt - mc
44
+ dbar = d.mean(1)
45
+ ss_within = ((lc - mc[..., None]) ** 2).sum((1, 2)) + ((lt - mt[..., None]) ** 2).sum((1, 2))
46
+ ss_inter = plates * ((d - dbar[:, None]) ** 2).sum(1) / 2
47
+ df = 2 * runs * plates - runs - 1
48
+ se = np.sqrt((ss_within + ss_inter) / df * 2 / (plates * runs))
49
+ with np.errstate(divide="ignore", invalid="ignore"):
50
+ p = 2 * stats.t.sf(np.abs(dbar / se), df)
51
+ return np.nan_to_num(p, nan=1.0) < alpha
52
+
53
+
54
+ def tost(yc: np.ndarray, yt: np.ndarray, margin: tuple[float, float] = (0.8, 1.25),
55
+ alpha: float = 0.05) -> np.ndarray:
56
+ """Two one-sided tests for equivalence of the treatment/control ratio.
57
+
58
+ Run level when there are >= 2 runs; plate level (Welch-type SE) when there is a single run.
59
+ """
60
+ lo, hi = np.log(margin[0]), np.log(margin[1])
61
+ if not lo < 0 < hi:
62
+ raise ValueError("margin must bracket 1, e.g. (0.8, 1.25)")
63
+ n, runs, plates = yc.shape
64
+ if runs >= 2:
65
+ d = _run_differences(yc, yt)
66
+ m, se, df = d.mean(1), d.std(1, ddof=1) / np.sqrt(runs), runs - 1
67
+ else:
68
+ lc = np.log(yc.reshape(n, -1) + OFFSET)
69
+ lt = np.log(yt.reshape(n, -1) + OFFSET)
70
+ m = lt.mean(1) - lc.mean(1)
71
+ se = np.sqrt(lt.var(1, ddof=1) / plates + lc.var(1, ddof=1) / plates)
72
+ df = 2 * plates - 2
73
+ with np.errstate(divide="ignore", invalid="ignore"):
74
+ p = np.maximum(stats.t.sf((m - lo) / se, df), stats.t.cdf((m - hi) / se, df))
75
+ return np.nan_to_num(p, nan=1.0) < alpha
@@ -0,0 +1,78 @@
1
+ """Command-line interface: `compatpower power|equivalence|table|allocate|estimate`."""
2
+ from __future__ import annotations
3
+
4
+ import argparse
5
+ import json
6
+ import sys
7
+
8
+ import pandas as pd
9
+
10
+ from . import __version__
11
+ from .design import allocate, design_table, equivalence, power
12
+ from .estimate import estimate_model
13
+ from .model import AssayModel
14
+
15
+
16
+ def _model_args(p: argparse.ArgumentParser) -> None:
17
+ d = AssayModel()
18
+ p.add_argument("--mu0", type=float, default=d.mu0, help="mean count per control plate")
19
+ p.add_argument("--k", type=float, default=d.k, help="negative binomial k within a run")
20
+ p.add_argument("--sd-run", type=float, default=d.sd_run, help="SD of run effect (log scale)")
21
+ p.add_argument("--tau", type=float, default=d.tau, help="SD of run x treatment interaction (log scale)")
22
+ p.add_argument("--n-sim", type=int, default=2000)
23
+ p.add_argument("--seed", type=int, default=1)
24
+ p.add_argument("--alpha", type=float, default=0.05)
25
+
26
+
27
+ def _model(a: argparse.Namespace) -> AssayModel:
28
+ return AssayModel(mu0=a.mu0, k=a.k, sd_run=a.sd_run, tau=a.tau)
29
+
30
+
31
+ def _margin(s: str) -> tuple[float, float]:
32
+ lo, hi = (float(x) for x in s.split(","))
33
+ return lo, hi
34
+
35
+
36
+ def main(argv: list[str] | None = None) -> int:
37
+ ap = argparse.ArgumentParser(prog="compatpower", description="Power and design of in vitro compatibility assays")
38
+ ap.add_argument("--version", action="version", version=__version__)
39
+ sub = ap.add_subparsers(dest="cmd", required=True)
40
+
41
+ p = sub.add_parser("power", help="power for a design"); _model_args(p)
42
+ p.add_argument("--runs", type=int, required=True); p.add_argument("--plates", type=int, required=True)
43
+ p.add_argument("--reduction", type=float, default=0.3); p.add_argument("--analysis", default="run", choices=["run", "pooled", "blocked"])
44
+
45
+ e = sub.add_parser("equivalence", help="probability of showing equivalence"); _model_args(e)
46
+ e.add_argument("--runs", type=int, required=True); e.add_argument("--plates", type=int, required=True)
47
+ e.add_argument("--margin", type=_margin, default=(0.75, 1 / 0.75), help="e.g. 0.75,1.333")
48
+
49
+ t = sub.add_parser("table", help="design table runs x plates"); _model_args(t)
50
+ t.add_argument("--margin", type=_margin, default=(0.75, 1 / 0.75)); t.add_argument("--out", help="CSV output")
51
+
52
+ al = sub.add_parser("allocate", help="split a fixed number of plates per group into runs"); _model_args(al)
53
+ al.add_argument("--total", type=int, required=True); al.add_argument("--reduction", type=float, default=0.3)
54
+ al.add_argument("--margin", type=_margin, default=(0.75, 1 / 0.75))
55
+
56
+ es = sub.add_parser("estimate", help="estimate mu0, k, sd_run (and tau) from a CSV of plate counts")
57
+ es.add_argument("csv", help="columns: run, group (control/treatment), count [, product]")
58
+
59
+ a = ap.parse_args(argv)
60
+ if a.cmd == "estimate":
61
+ model, rep = estimate_model(pd.read_csv(a.csv))
62
+ print(json.dumps(rep, indent=1, default=float))
63
+ return 0
64
+ m = _model(a)
65
+ if a.cmd == "power":
66
+ print(f"{power(a.runs, a.plates, a.reduction, m, a.analysis, a.alpha, a.n_sim, a.seed):.3f}")
67
+ elif a.cmd == "equivalence":
68
+ print(f"{equivalence(a.runs, a.plates, a.margin, m, 0.0, a.alpha, a.n_sim, a.seed):.3f}")
69
+ elif a.cmd == "table":
70
+ df = design_table(margin=a.margin, model=m, alpha=a.alpha, n_sim=a.n_sim, seed=a.seed)
71
+ df.to_csv(a.out, index=False) if a.out else print(df.round(3).to_string(index=False))
72
+ elif a.cmd == "allocate":
73
+ print(allocate(a.total, a.reduction, m, a.margin, alpha=a.alpha, n_sim=a.n_sim, seed=a.seed).round(3).to_string(index=False))
74
+ return 0
75
+
76
+
77
+ if __name__ == "__main__":
78
+ sys.exit(main())
@@ -0,0 +1,78 @@
1
+ """Power, equivalence and allocation for compatibility assay designs."""
2
+ from __future__ import annotations
3
+
4
+ import itertools
5
+ from typing import Iterable
6
+
7
+ import numpy as np
8
+ import pandas as pd
9
+
10
+ from .analysis import test_plates_blocked, test_plates_pooled, test_run_level, tost
11
+ from .model import AssayModel, simulate_counts
12
+
13
+ ANALYSES = {"run": test_run_level, "pooled": test_plates_pooled, "blocked": test_plates_blocked}
14
+
15
+
16
+ def _rng(seed: int | None) -> np.random.Generator:
17
+ return np.random.default_rng(seed)
18
+
19
+
20
+ def power(runs: int, plates: int, reduction: float, model: AssayModel = AssayModel(),
21
+ analysis: str = "run", alpha: float = 0.05, n_sim: int = 2000, seed: int | None = 1) -> float:
22
+ """Probability of a significant difference (power if reduction > 0; type I error if reduction = 0).
23
+
24
+ analysis: "run" (run = experimental unit; recommended), "pooled" (plates as replicates) or
25
+ "blocked" (plates, run as block). "run" and "blocked" need runs >= 2.
26
+ """
27
+ if analysis not in ANALYSES:
28
+ raise ValueError(f"analysis must be one of {list(ANALYSES)}")
29
+ yc, yt = simulate_counts(model, runs, plates, reduction, n_sim, _rng(seed))
30
+ return float(ANALYSES[analysis](yc, yt, alpha).mean())
31
+
32
+
33
+ def equivalence(runs: int, plates: int, margin: tuple[float, float] = (0.8, 1.25),
34
+ model: AssayModel = AssayModel(), true_reduction: float = 0.0, alpha: float = 0.05,
35
+ n_sim: int = 2000, seed: int | None = 1) -> float:
36
+ """Probability that TOST declares equivalence (ratio within `margin`) given the true reduction."""
37
+ yc, yt = simulate_counts(model, runs, plates, true_reduction, n_sim, _rng(seed))
38
+ return float(tost(yc, yt, margin, alpha).mean())
39
+
40
+
41
+ def design_table(runs: Iterable[int] = (3, 4, 5, 6, 8, 10), plates: Iterable[int] = (3, 5, 10, 20),
42
+ reductions: Iterable[float] = (0.2, 0.3, 0.5), margin: tuple[float, float] = (0.75, 1 / 0.75),
43
+ model: AssayModel = AssayModel(), alpha: float = 0.05, n_sim: int = 2000,
44
+ seed: int | None = 1) -> pd.DataFrame:
45
+ """Run-level power for each reduction and probability of showing equivalence, for each runs x plates."""
46
+ rows = []
47
+ for i, (r, n) in enumerate(itertools.product(runs, plates)):
48
+ s = None if seed is None else seed + i
49
+ row = {"runs": r, "plates": n, "total_plates": r * n}
50
+ for red in reductions:
51
+ row[f"power_{round(red * 100)}pct"] = power(r, n, red, model, "run", alpha, n_sim, s)
52
+ row["equivalence"] = equivalence(r, n, margin, model, 0.0, alpha, n_sim, s)
53
+ rows.append(row)
54
+ return pd.DataFrame(rows)
55
+
56
+
57
+ def allocate(total_plates: int, reduction: float = 0.3, model: AssayModel = AssayModel(),
58
+ margin: tuple[float, float] = (0.75, 1 / 0.75), min_plates: int = 2, alpha: float = 0.05,
59
+ n_sim: int = 2000, seed: int | None = 1) -> pd.DataFrame:
60
+ """Compare ways of splitting a fixed number of plates per group into runs x plates."""
61
+ rows = []
62
+ for r in range(2, total_plates // min_plates + 1):
63
+ if total_plates % r:
64
+ continue
65
+ n = total_plates // r
66
+ rows.append({"runs": r, "plates": n,
67
+ "power": power(r, n, reduction, model, "run", alpha, n_sim, seed),
68
+ "equivalence": equivalence(r, n, margin, model, 0.0, alpha, n_sim, seed)})
69
+ return pd.DataFrame(rows)
70
+
71
+
72
+ def required_runs(plates: int, reduction: float = 0.3, target: float = 0.8, model: AssayModel = AssayModel(),
73
+ max_runs: int = 30, alpha: float = 0.05, n_sim: int = 2000, seed: int | None = 1) -> int | None:
74
+ """Smallest number of runs reaching `target` power with `plates` per group per run (None if > max_runs)."""
75
+ for r in range(2, max_runs + 1):
76
+ if power(r, plates, reduction, model, "run", alpha, n_sim, seed) >= target:
77
+ return r
78
+ return None
@@ -0,0 +1,74 @@
1
+ """Estimate model parameters from a laboratory's own plate counts.
2
+
3
+ Input: a table with one row per plate and columns `run`, `group` ("control"/"treatment") and `count`.
4
+ Optionally `product`, to estimate tau from the same product tested in several runs.
5
+ """
6
+ from __future__ import annotations
7
+
8
+ import numpy as np
9
+ import pandas as pd
10
+ from scipy import optimize, special
11
+
12
+ from .model import AssayModel
13
+
14
+
15
+ def _nb_negloglik(log_k: float, groups: list[np.ndarray]) -> float:
16
+ k = np.exp(log_k)
17
+ ll = 0.0
18
+ for y in groups:
19
+ mu = max(y.mean(), 1e-9)
20
+ ll += np.sum(special.gammaln(y + k) - special.gammaln(k) - special.gammaln(y + 1)
21
+ + k * np.log(k / (k + mu)) + y * np.log(mu / (k + mu)))
22
+ return -ll
23
+
24
+
25
+ def estimate_k(groups: list[np.ndarray]) -> float:
26
+ """Maximum-likelihood NB size parameter k with a separate mean per group."""
27
+ res = optimize.minimize_scalar(_nb_negloglik, bounds=(-4, 10), args=(groups,), method="bounded")
28
+ return float(np.exp(res.x))
29
+
30
+
31
+ def estimate_model(df: pd.DataFrame, tau: float | None = None) -> tuple[AssayModel, dict]:
32
+ """Fit mu0, k and sd_run from control plates (and k also from treatment plates).
33
+
34
+ sd_run is estimated by the method of moments: variance of log control means across runs minus their
35
+ expected sampling variance. tau is estimated only if a `product` column has the same product in >= 2 runs;
36
+ otherwise the given value (or 0.15) is used. Returns the model and a report dict with diagnostics.
37
+ """
38
+ need = {"run", "group", "count"}
39
+ if not need <= set(df.columns):
40
+ raise ValueError(f"columns required: {sorted(need)}")
41
+ df = df.assign(group=df["group"].str.lower().str.strip())
42
+ groups = [g["count"].to_numpy(float) for _, g in df.groupby(["run", "group"])]
43
+ ctrl = [g["count"].to_numpy(float) for _, g in df[df.group == "control"].groupby("run")]
44
+ if not ctrl:
45
+ raise ValueError("no control plates found (group == 'control')")
46
+ k = estimate_k(groups)
47
+ log_means = np.array([np.log(y.mean()) for y in ctrl])
48
+ mu0 = float(np.exp(log_means.mean()))
49
+ report = {"n_runs_control": len(ctrl), "n_plates": int(len(df)), "k": k}
50
+ if len(ctrl) >= 2:
51
+ samp = np.mean([(1 / y.mean() + 1 / k) / len(y) for y in ctrl])
52
+ sd_run = float(np.sqrt(max(log_means.var(ddof=1) - samp, 0.0)))
53
+ else:
54
+ sd_run = 0.0
55
+ report["warning_sd_run"] = "only one run: sd_run set to 0 (cannot be estimated)"
56
+ tau_hat = None
57
+ if "product" in df.columns:
58
+ diffs = []
59
+ for (prod, run), g in df[df.group == "treatment"].groupby(["product", "run"]):
60
+ c = df[(df.run == run) & (df.group == "control")]["count"]
61
+ if len(c):
62
+ diffs.append((prod, np.log(g["count"].mean() + .5) - np.log(c.mean() + .5),
63
+ (1 / max(g["count"].mean(), .5) + 1 / k) / len(g) + (1 / max(c.mean(), .5) + 1 / k) / len(c)))
64
+ d = pd.DataFrame(diffs, columns=["product", "diff", "samp"])
65
+ rep = d.groupby("product").filter(lambda x: len(x) >= 2)
66
+ if len(rep):
67
+ v = rep.groupby("product").apply(lambda x: x["diff"].var(ddof=1) - x["samp"].mean(), include_groups=False)
68
+ tau_hat = float(np.sqrt(max(v.mean(), 0.0)))
69
+ report["n_products_repeated"] = int(rep["product"].nunique())
70
+ if tau_hat is None:
71
+ tau_hat = 0.15 if tau is None else tau
72
+ report["warning_tau"] = "tau not estimable (no product tested in >= 2 runs); using assumed value"
73
+ report.update(mu0=mu0, sd_run=sd_run, tau=tau_hat)
74
+ return AssayModel(mu0=mu0, k=k, sd_run=sd_run, tau=tau_hat), report
@@ -0,0 +1,57 @@
1
+ """Simulation model for in vitro compatibility assays.
2
+
3
+ Counts (e.g. colony-forming units, CFU) on each plate follow a negative binomial (NB2) distribution:
4
+
5
+ y_rgi ~ NB2(mu_rg, k), Var(y) = mu + mu^2 / k
6
+ log mu_rg = log mu0 + a_r + g * (log(1 - reduction) + c_r)
7
+ a_r ~ N(0, sd_run) run (day) effect shared by control and treatment
8
+ c_r ~ N(0, tau) run x treatment interaction: the product effect varies between runs
9
+
10
+ r = run (independent repetition of the assay), g = 0 for control and 1 for treatment, i = plate.
11
+ """
12
+ from __future__ import annotations
13
+
14
+ from dataclasses import dataclass, asdict
15
+
16
+ import numpy as np
17
+
18
+
19
+ @dataclass(frozen=True)
20
+ class AssayModel:
21
+ """Parameters of the data-generating model.
22
+
23
+ mu0: mean count per control plate.
24
+ k: negative binomial size (dispersion) parameter within a run; smaller k = more variable plates.
25
+ sd_run: SD of the run effect on the log scale (day-to-day drift of the mean).
26
+ tau: SD of the run x treatment interaction on the log scale.
27
+ """
28
+
29
+ mu0: float = 25.0
30
+ k: float = 4.3
31
+ sd_run: float = 0.48
32
+ tau: float = 0.15
33
+
34
+ def __post_init__(self) -> None:
35
+ if self.mu0 <= 0 or self.k <= 0 or self.sd_run < 0 or self.tau < 0:
36
+ raise ValueError("mu0 and k must be > 0; sd_run and tau must be >= 0")
37
+
38
+ def as_dict(self) -> dict:
39
+ return asdict(self)
40
+
41
+
42
+ def simulate_counts(model: AssayModel, runs: int, plates: int, reduction: float, n_sim: int,
43
+ rng: np.random.Generator) -> tuple[np.ndarray, np.ndarray]:
44
+ """Simulate control and treatment counts with shape (n_sim, runs, plates)."""
45
+ if runs < 1 or plates < 1:
46
+ raise ValueError("runs and plates must be >= 1")
47
+ if not 0 <= reduction < 1:
48
+ raise ValueError("reduction must be in [0, 1)")
49
+ a = rng.normal(0, model.sd_run, (n_sim, runs, 1))
50
+ c = rng.normal(0, model.tau, (n_sim, runs, 1))
51
+ mu_c = model.mu0 * np.exp(a)
52
+ mu_t = model.mu0 * np.exp(a + np.log1p(-reduction) + c)
53
+ shape = (n_sim, runs, plates)
54
+ k = model.k
55
+ yc = rng.negative_binomial(k, k / (k + np.broadcast_to(mu_c, shape)))
56
+ yt = rng.negative_binomial(k, k / (k + np.broadcast_to(mu_t, shape)))
57
+ return yc, yt
@@ -0,0 +1,53 @@
1
+ import numpy as np
2
+ import pandas as pd
3
+ import pytest
4
+
5
+ from compatpower import AssayModel, allocate, equivalence, estimate_model, power, simulate_counts
6
+ from compatpower.cli import main
7
+
8
+ M = AssayModel(mu0=25, k=4.3, sd_run=0.48, tau=0.15)
9
+
10
+
11
+ def test_type_one_error_run_level_is_nominal():
12
+ p = power(5, 10, 0.0, AssayModel(tau=0.3), "run", n_sim=4000, seed=3)
13
+ assert 0.035 < p < 0.065
14
+
15
+
16
+ def test_pooled_plates_inflate_error_with_interaction():
17
+ p = power(5, 20, 0.0, AssayModel(tau=0.3), "pooled", n_sim=3000, seed=4)
18
+ assert p > 0.12
19
+
20
+
21
+ def test_power_increases_with_runs():
22
+ assert power(8, 10, 0.3, M, n_sim=1500) > power(3, 10, 0.3, M, n_sim=1500)
23
+
24
+
25
+ def test_single_run_cannot_show_equivalence():
26
+ assert equivalence(1, 20, (0.8, 1.25), M, n_sim=1500) < 0.01
27
+
28
+
29
+ def test_allocation_favours_more_runs():
30
+ a = allocate(60, 0.3, M, n_sim=800)
31
+ assert a.iloc[-1]["power"] > a.iloc[0]["power"]
32
+
33
+
34
+ def test_estimate_recovers_parameters():
35
+ rng = np.random.default_rng(0)
36
+ true = AssayModel(mu0=30, k=5, sd_run=0.3, tau=0.0)
37
+ yc, yt = simulate_counts(true, 40, 10, 0.2, 1, rng)
38
+ rows = [(r, g, int(v)) for g, y in (("control", yc), ("treatment", yt)) for r in range(40) for v in y[0, r]]
39
+ m, rep = estimate_model(pd.DataFrame(rows, columns=["run", "group", "count"]))
40
+ assert 3 < m.k < 8 and 0.15 < m.sd_run < 0.45 and 22 < m.mu0 < 40
41
+ assert "warning_tau" in rep
42
+
43
+
44
+ def test_bad_inputs():
45
+ with pytest.raises(ValueError):
46
+ AssayModel(k=0)
47
+ with pytest.raises(ValueError):
48
+ power(1, 5, 0.3, M, "run")
49
+
50
+
51
+ def test_cli_power(capsys):
52
+ assert main(["power", "--runs", "4", "--plates", "5", "--n-sim", "200"]) == 0
53
+ assert 0 <= float(capsys.readouterr().out) <= 1