compatpower 0.1.0__py3-none-any.whl
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.
- compatpower/__init__.py +10 -0
- compatpower/analysis.py +75 -0
- compatpower/cli.py +78 -0
- compatpower/design.py +78 -0
- compatpower/estimate.py +74 -0
- compatpower/model.py +57 -0
- compatpower-0.1.0.dist-info/METADATA +78 -0
- compatpower-0.1.0.dist-info/RECORD +11 -0
- compatpower-0.1.0.dist-info/WHEEL +4 -0
- compatpower-0.1.0.dist-info/entry_points.txt +2 -0
- compatpower-0.1.0.dist-info/licenses/LICENSE +21 -0
compatpower/__init__.py
ADDED
|
@@ -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__"]
|
compatpower/analysis.py
ADDED
|
@@ -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
|
compatpower/cli.py
ADDED
|
@@ -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())
|
compatpower/design.py
ADDED
|
@@ -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
|
compatpower/estimate.py
ADDED
|
@@ -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
|
compatpower/model.py
ADDED
|
@@ -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,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
|
+
[](https://github.com/siriani/compatpower/actions/workflows/tests.yml)
|
|
25
|
+
[](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,11 @@
|
|
|
1
|
+
compatpower/__init__.py,sha256=Rsl9W8xgnkszPN9lAg1JRjsp_1wAcSlhJQT9liGc3W4,501
|
|
2
|
+
compatpower/analysis.py,sha256=YNSTRZ5n0r-WGWeoCR57DZLENwLbiPWv_aOzyEM06lE,3231
|
|
3
|
+
compatpower/cli.py,sha256=rWJ2H8ZhtqXOcWPjzxC2xzBHz7yAPY5ytv1vw_xUD_c,3718
|
|
4
|
+
compatpower/design.py,sha256=hVT4T6CrirXHNk-BnU-6nwpb2YjY_AZhbTP2F4Fg1o0,3914
|
|
5
|
+
compatpower/estimate.py,sha256=8Rznq2mHwm1IYRo9BsIzlEtjJVPiKdiCSpZNruGGDtw,3645
|
|
6
|
+
compatpower/model.py,sha256=N0Vb0G8ofzwjTfMDvgUT9xnlYFeZUfyxoJBocnOm4L0,2219
|
|
7
|
+
compatpower-0.1.0.dist-info/METADATA,sha256=5UEoVzm7JlICwgNBOiXdc9C6Vb-TA7bn-qHBASAOeUw,4347
|
|
8
|
+
compatpower-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
9
|
+
compatpower-0.1.0.dist-info/entry_points.txt,sha256=FAFLxnM3z9N0rER_dO8NQVfUzyjGziMLOvxzjUt2oEk,53
|
|
10
|
+
compatpower-0.1.0.dist-info/licenses/LICENSE,sha256=5QSo51tT0uDl_2kQxvohvxxD9ywW6JqgaqaTLlr4zxA,1118
|
|
11
|
+
compatpower-0.1.0.dist-info/RECORD,,
|
|
@@ -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.
|