pilotr 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.
pilotr/__init__.py ADDED
@@ -0,0 +1,8 @@
1
+ """pilotr, for simulating experimental and behavioural data from a portable design specification."""
2
+ from .core import RNG, as241, inv_logit
3
+ from .simulate import simulate, load_spec, Dataset
4
+ from .power import power, power_curve, power_mixed
5
+
6
+ __version__ = "0.1.0"
7
+ __all__ = ["RNG", "as241", "inv_logit", "simulate", "load_spec", "Dataset",
8
+ "power", "power_curve", "power_mixed"]
pilotr/core.py ADDED
@@ -0,0 +1,190 @@
1
+ """Portable numerical core for pilotr.
2
+
3
+ Everything here is implemented to be bit-identical with the R port. The
4
+ components are a shared L'Ecuyer (1988) combined LCG for uniforms, Wichura's
5
+ AS 241 inverse-normal, a hand-rolled Cholesky factorisation, and inverse-CDF
6
+ transforms for the response families. The routines avoid NumPy randomness, so
7
+ the random stream remains aligned across the two languages.
8
+ """
9
+
10
+ from __future__ import annotations
11
+ import math
12
+
13
+ # --- L'Ecuyer (1988) combined LCG -------------------------------------------------
14
+ # All products stay below 2**53, so integer arithmetic is exact in IEEE-754 doubles.
15
+
16
+ _M1 = 2147483563
17
+ _M2 = 2147483399
18
+ _A1 = 40014
19
+ _A2 = 40692
20
+
21
+
22
+ class RNG:
23
+ """Shared cross-language random-number generator.
24
+
25
+ The combined linear congruential generator of L'Ecuyer (1988), implemented identically
26
+ in R and Python so that a given seed yields the same stream in both. All intermediate
27
+ products stay below `2**53`, so the arithmetic is exact in IEEE-754 doubles. The
28
+ draw-order contract is documented in the specification at
29
+ https://github.com/pablobernabeu/pilotr/blob/main/spec/SPEC.md.
30
+
31
+ Parameters
32
+ ----------
33
+ seed : int
34
+ Seed for the generator (coerced to a non-negative integer).
35
+ """
36
+
37
+ __slots__ = ("s1", "s2")
38
+
39
+ def __init__(self, seed: int):
40
+ seed = int(abs(seed))
41
+ self.s1 = 1 + (seed % (_M1 - 1))
42
+ self.s2 = 1 + ((_A2 * self.s1) % (_M2 - 1))
43
+ for _ in range(10): # warm-up
44
+ self.uniform()
45
+
46
+ def uniform(self) -> float:
47
+ """Return one draw from the standard uniform distribution on (0, 1)."""
48
+ self.s1 = (_A1 * self.s1) % _M1
49
+ self.s2 = (_A2 * self.s2) % _M2
50
+ d = self.s1 - self.s2
51
+ if d < 1:
52
+ d += _M1 - 1
53
+ return d / _M1
54
+
55
+ def normal(self) -> float:
56
+ """Return one draw from the standard normal distribution."""
57
+ return as241(self.uniform())
58
+
59
+ def normals(self, k: int) -> list[float]:
60
+ """Return a list of `k` standard-normal draws."""
61
+ return [self.normal() for _ in range(k)]
62
+
63
+
64
+ # --- Wichura (1988) Algorithm AS 241: inverse normal CDF (PPND16) -----------------
65
+
66
+ def as241(p: float) -> float:
67
+ """Inverse standard-normal CDF (quantile function), Wichura's (1988) Algorithm AS 241.
68
+
69
+ The PPND16 routine underlying R's `qnorm`, accurate to full double precision.
70
+
71
+ Parameters
72
+ ----------
73
+ p : float
74
+ A probability in the open interval (0, 1).
75
+
76
+ Returns
77
+ -------
78
+ float
79
+ The standard-normal quantile for `p`.
80
+ """
81
+ q = p - 0.5
82
+ if abs(q) <= 0.425:
83
+ r = 0.180625 - q * q
84
+ num = (((((((2509.0809287301226727 * r + 33430.575583588128105) * r +
85
+ 67265.770927008700853) * r + 45921.953931549871457) * r +
86
+ 13731.693765509461125) * r + 1971.5909503065514427) * r +
87
+ 133.14166789178437745) * r + 3.387132872796366608)
88
+ den = (((((((5226.495278852854561 * r + 28729.085735721942674) * r +
89
+ 39307.89580009271061) * r + 21213.794301586595867) * r +
90
+ 5394.1960214247511077) * r + 687.1870074920579083) * r +
91
+ 42.313330701600911252) * r + 1.0)
92
+ return q * num / den
93
+ r = p if q < 0 else 1.0 - p
94
+ r = math.sqrt(-math.log(r))
95
+ if r <= 5.0:
96
+ r -= 1.6
97
+ num = (((((((7.7454501427834140764e-4 * r + 0.0227238449892691845833) * r +
98
+ 0.24178072517745061177) * r + 1.27045825245236838258) * r +
99
+ 3.64784832476320460504) * r + 5.7694972214606914055) * r +
100
+ 4.6303378461565452959) * r + 1.42343711074968357734)
101
+ den = (((((((1.05075007164441684324e-9 * r + 5.475938084995344946e-4) * r +
102
+ 0.0151986665636164571966) * r + 0.14810397642748007459) * r +
103
+ 0.68976733498510000455) * r + 1.6763848301838038494) * r +
104
+ 2.05319162663775882187) * r + 1.0)
105
+ else:
106
+ r -= 5.0
107
+ num = (((((((2.01033439929228813265e-7 * r + 2.71155556874348757815e-5) * r +
108
+ 0.0012426609473880784386) * r + 0.026532189526576123093) * r +
109
+ 0.29656057182850489123) * r + 1.7848265399172913358) * r +
110
+ 5.4637849111641143699) * r + 6.6579046435011037772)
111
+ den = (((((((2.04426310338993978564e-15 * r + 1.4215117583164458887e-7) * r +
112
+ 1.8463183175100546818e-5) * r + 7.868691311456132591e-4) * r +
113
+ 0.0148753612908506148525) * r + 0.13692988092273580531) * r +
114
+ 0.59983220655588793769) * r + 1.0)
115
+ z = num / den
116
+ return -z if q < 0 else z
117
+
118
+
119
+ # --- Linear algebra (kept hand-rolled so rounding matches the R port exactly) -----
120
+
121
+ def cholesky(cov: list[list[float]]) -> list[list[float]]:
122
+ """Lower Cholesky factor L with L Lᵀ = cov (Cholesky–Banachiewicz)."""
123
+ n = len(cov)
124
+ L = [[0.0] * n for _ in range(n)]
125
+ for i in range(n):
126
+ for j in range(i + 1):
127
+ s = sum(L[i][k] * L[j][k] for k in range(j))
128
+ if i == j:
129
+ L[i][j] = math.sqrt(max(cov[i][i] - s, 0.0))
130
+ else:
131
+ L[i][j] = (cov[i][j] - s) / L[j][j] if L[j][j] != 0.0 else 0.0
132
+ return L
133
+
134
+
135
+ def matvec(L: list[list[float]], z: list[float]) -> list[float]:
136
+ return [sum(L[i][k] * z[k] for k in range(len(z))) for i in range(len(L))]
137
+
138
+
139
+ # --- Response transforms (inverse-CDF / link functions) ---------------------------
140
+
141
+ def inv_logit(x: float) -> float:
142
+ """Logistic (inverse-logit) link `1 / (1 + exp(-x))`, evaluated stably for large `|x|`."""
143
+ if x >= 0:
144
+ return 1.0 / (1.0 + math.exp(-x))
145
+ e = math.exp(x)
146
+ return e / (1.0 + e)
147
+
148
+
149
+ def poisson_inv(lam: float, u: float) -> int:
150
+ """Inverse-CDF Poisson draw from a uniform u."""
151
+ p = math.exp(-lam)
152
+ cum = p
153
+ k = 0
154
+ while u > cum and k < 1_000_000:
155
+ k += 1
156
+ p *= lam / k
157
+ cum += p
158
+ return k
159
+
160
+
161
+ def ordinal_inv(eta: float, thresholds: list[float], u: float) -> int:
162
+ """Cumulative-logit ordinal draw: P(Y<=k) = invlogit(theta_k - eta). 1-indexed category."""
163
+ for k, th in enumerate(thresholds):
164
+ if u <= inv_logit(th - eta):
165
+ return k + 1
166
+ return len(thresholds) + 1
167
+
168
+
169
+ def gamma_mt(rng, shape: float) -> float:
170
+ """Marsaglia-Tsang Gamma(shape, scale=1) draw from the shared RNG (normals and uniforms in a
171
+ rejection loop). The floating-point operations are identical in R and Python, so the
172
+ accept/reject decisions also agree, which preserves parity across the two languages."""
173
+ if shape < 1.0:
174
+ g = gamma_mt(rng, shape + 1.0)
175
+ return g * rng.uniform() ** (1.0 / shape)
176
+ d = shape - 1.0 / 3.0
177
+ c = 1.0 / math.sqrt(9.0 * d)
178
+ while True:
179
+ x = rng.normal()
180
+ v = (1.0 + c * x) ** 3
181
+ if v <= 0.0:
182
+ continue
183
+ if math.log(rng.uniform()) < 0.5 * x * x + d - d * v + d * math.log(v):
184
+ return d * v
185
+
186
+
187
+ def beta_draw(rng, a: float, b: float) -> float:
188
+ """Beta(a, b) via two Gamma draws: X/(X+Y), X~Gamma(a), Y~Gamma(b)."""
189
+ x = gamma_mt(rng, a)
190
+ return x / (x + gamma_mt(rng, b))
pilotr/power.py ADDED
@@ -0,0 +1,315 @@
1
+ """Simulation-based power and design analysis (Type S / Type M).
2
+
3
+ For each of the `n_sims` Monte Carlo replicates, we simulate a fresh data set from the
4
+ known ground-truth spec, fit the analysis model, and record the estimate and p-value. In
5
+ addition to classical power (the proportion of significant replicates), we report the
6
+ design-analysis quantities of Gelman and Carlin (2014), computed over the significant
7
+ replicates.
8
+
9
+ * Type S (sign) error: P(estimate has the wrong sign | significant)
10
+ * Type M (magnitude): E(|estimate| / |true effect| | significant) (exaggeration ratio)
11
+
12
+ The two-group Gaussian design uses a two-sample t-test (`power`). Crossed mixed-effects
13
+ designs use a statsmodels MixedLM backend (`power_mixed`), which is conservative for
14
+ random-slope designs; the R package's lme4 backend is the reference there.
15
+
16
+ Every analysis takes a `workers` argument that spreads the replicates over local
17
+ processes. Each replicate seeds the shared cross-language RNG from its own index, so the
18
+ results are identical to a serial run whatever the worker count. The per-replicate
19
+ functions are module-level so that they pickle under the Windows spawn start method.
20
+ """
21
+
22
+ from __future__ import annotations
23
+ import copy, functools, statistics
24
+ from .simulate import simulate, load_spec
25
+
26
+
27
+ def _check_workers(workers):
28
+ """Validate `workers` as a single positive whole number and return it as an int."""
29
+ if isinstance(workers, bool) or not isinstance(workers, int) or workers < 1:
30
+ raise ValueError("workers must be a positive whole number")
31
+ return workers
32
+
33
+
34
+ def _map_replicates(rep, seeds, executor):
35
+ """Run `rep` over the per-replicate seeds, serially or on the executor.
36
+
37
+ `executor.map` returns results in input order, so the downstream reductions match the
38
+ serial code exactly.
39
+ """
40
+ if executor is None:
41
+ return [rep(seed) for seed in seeds]
42
+ n_workers = getattr(executor, "_max_workers", 1) or 1
43
+ return list(executor.map(rep, seeds, chunksize=max(1, len(seeds) // (4 * n_workers))))
44
+
45
+
46
+ def _power_replicate(seed, spec, fname, lev0, lev1, yname):
47
+ """One two-group replicate: simulate at `seed`, t-test, return (estimate, p-value)."""
48
+ from scipy import stats # lazy: imported in each worker process on first use
49
+
50
+ s = copy.deepcopy(spec)
51
+ s["seed"] = seed
52
+ d = simulate(s)
53
+ g0 = [r[yname] for r in d.rows if r[fname] == lev0]
54
+ g1 = [r[yname] for r in d.rows if r[fname] == lev1]
55
+ t = stats.ttest_ind(g1, g0, equal_var=True)
56
+ return statistics.mean(g1) - statistics.mean(g0), t.pvalue
57
+
58
+
59
+ def power(spec, n_sims=1000, alpha=0.05, workers=1):
60
+ """Simulation-based power and design analysis for a two-group Gaussian design.
61
+
62
+ Repeatedly simulate from the specification, apply a two-sample t-test, and report power
63
+ together with the Type S (sign) and Type M (magnitude) errors of Gelman and Carlin
64
+ (2014), computed over the significant replicates.
65
+
66
+ Parameters
67
+ ----------
68
+ spec : dict or str
69
+ A two-group Gaussian design specification (dict or path to a JSON file).
70
+ n_sims : int, optional
71
+ Number of Monte Carlo replicates (default 1000).
72
+ alpha : float, optional
73
+ Two-sided significance level (default 0.05).
74
+ workers : int, optional
75
+ Number of local worker processes over which to spread the replicates (default 1,
76
+ serial). Each replicate seeds the shared RNG from its own index, so any worker
77
+ count returns results identical to a serial run.
78
+
79
+ Returns
80
+ -------
81
+ dict
82
+ Keys: `n_sims`, `alpha`, `power`, `n_significant`, `true_effect`, `mean_estimate`,
83
+ `type_s`, `type_m`.
84
+
85
+ Raises
86
+ ------
87
+ NotImplementedError
88
+ If the design is not a single two-level between-subjects Gaussian factor.
89
+
90
+ Notes
91
+ -----
92
+ Requires `scipy` (imported lazily, in each worker process when parallel); install the
93
+ `power` or `dev` extra.
94
+ """
95
+ workers = _check_workers(workers)
96
+ from scipy import stats as _stats # noqa: F401 fail fast before simulating
97
+
98
+ if workers == 1:
99
+ return _power_impl(spec, n_sims, alpha, None)
100
+ from concurrent.futures import ProcessPoolExecutor
101
+ with ProcessPoolExecutor(max_workers=workers) as executor:
102
+ return _power_impl(spec, n_sims, alpha, executor)
103
+
104
+
105
+ def _power_impl(spec, n_sims, alpha, executor):
106
+ """The replicate loop behind `power`, taking an optional executor so that sweep
107
+ functions can start one process pool and reuse it across grid points."""
108
+ if isinstance(spec, str):
109
+ spec = load_spec(spec)
110
+ if spec["response"]["family"] != "gaussian":
111
+ raise NotImplementedError("The power backend currently handles only the gaussian two-group design.")
112
+
113
+ between = [f for f in spec["factors"] if f.get("between")]
114
+ if len(between) != 1 or len(between[0]["levels"]) != 2:
115
+ raise NotImplementedError("The power backend expects exactly one 2-level between factor.")
116
+ factor = between[0]
117
+ fname = factor["name"]
118
+ lev0, lev1 = factor["levels"]
119
+ col, vals = next(iter(factor["contrasts"].items()))
120
+ true_effect = spec["fixed"]["coefficients"][col] * (vals[1] - vals[0])
121
+ yname = spec["response"]["name"]
122
+
123
+ base_seed = spec["seed"]
124
+ rep = functools.partial(_power_replicate, spec=spec, fname=fname,
125
+ lev0=lev0, lev1=lev1, yname=yname)
126
+ results = _map_replicates(rep, [base_seed + i for i in range(n_sims)], executor)
127
+ estimates = [r[0] for r in results]
128
+ pvals = [r[1] for r in results]
129
+
130
+ sig = [i for i, p in enumerate(pvals) if p < alpha]
131
+ power_val = len(sig) / n_sims
132
+ if sig:
133
+ type_s = sum(1 for i in sig if (estimates[i] > 0) != (true_effect > 0)) / len(sig)
134
+ type_m = statistics.mean(abs(estimates[i]) / abs(true_effect) for i in sig)
135
+ else:
136
+ type_s = type_m = float("nan")
137
+
138
+ return {
139
+ "n_sims": n_sims, "alpha": alpha, "power": power_val,
140
+ "n_significant": len(sig), "true_effect": true_effect,
141
+ "mean_estimate": statistics.mean(estimates),
142
+ "type_s": type_s, "type_m": type_m,
143
+ }
144
+
145
+
146
+ def _power_mixed_replicate(seed, spec, fname, l2c, yname, fam, shift):
147
+ """One mixed-model replicate: simulate at `seed`, fit MixedLM, return (estimate,
148
+ p-value), or None when the fit fails."""
149
+ import math, warnings
150
+ import pandas as pd
151
+ import statsmodels.formula.api as smf
152
+
153
+ vcf = {"subj_i": "0 + C(subject)", "subj_s": "0 + C(subject):cc",
154
+ "item_i": "0 + C(item)", "item_s": "0 + C(item):cc"}
155
+ s = copy.deepcopy(spec)
156
+ s["seed"] = seed
157
+ df = pd.DataFrame(simulate(s).rows)
158
+ df["cc"] = df[fname].map(l2c)
159
+ df["yv"] = [math.log(v - shift) for v in df[yname]] if fam == "shifted_lognormal" else list(df[yname])
160
+ df["grp"] = 1
161
+ try:
162
+ with warnings.catch_warnings():
163
+ warnings.simplefilter("ignore")
164
+ m = smf.mixedlm("yv ~ cc", df, groups="grp", vc_formula=vcf).fit() # REML (default)
165
+ return float(m.fe_params["cc"]), float(m.pvalues["cc"])
166
+ except Exception:
167
+ return None
168
+
169
+
170
+ def power_mixed(spec, n_sims=50, alpha=0.05, workers=1):
171
+ """Crossed mixed-effects simulation-based power in Python, via statsmodels MixedLM with
172
+ by-subject and by-item random intercepts and slopes as (independent) variance components.
173
+
174
+ This is pilotr's own simulation loop over the portable design specification, not a
175
+ wrapper around an existing power package. It covers territory pioneered by simr (Green
176
+ and MacLeod, 2016, doi:10.1111/2041-210x.12504) and mixedpower (Kumle, Vo and Draschkow,
177
+ 2021, doi:10.3758/s13428-021-01546-0); pilotr differs in being driven by the portable
178
+ cross-language spec, in reporting Type S and Type M errors and in built-in
179
+ parallelisation via `workers` (default 1, serial), which returns results identical to a
180
+ serial run for any worker count.
181
+
182
+ Accuracy caveat (verified behaviour, not a bug). statsmodels fits crossed random effects
183
+ as independent variance components and, in our tests, substantially overstates random-slope
184
+ variance (for example, a by-subject slope SD of about 0.12 estimated against 0.04 true).
185
+ This inflates the fixed-effect standard error. For designs with by-subject or by-item random
186
+ slopes, the backend is therefore markedly conservative. On the crossed RT design it
187
+ reports power around 0.48, against the R/lme4 reference of about 0.73. It still recovers the
188
+ fixed effect (mean estimate about 0.048 against 0.05 true) and the Type S and Type M
189
+ quantities correctly, and it is reliable for random-intercept designs. We recommend treating
190
+ its output as a conservative lower bound and using the R/lme4 `power_mixed` as the reference
191
+ whenever random slopes or random-effect correlations matter. Data generation is identical
192
+ across R and Python. This discrepancy arises solely in the Python LMM estimator.
193
+
194
+ Parameters
195
+ ----------
196
+ spec : dict or str
197
+ A design specification (dict or path to a JSON file) with exactly one within-unit
198
+ factor and a crossed design with an item unit.
199
+ n_sims : int, optional
200
+ Number of Monte Carlo replicates (default 50, smaller than `power`'s 1000 because
201
+ each replicate fits a mixed model).
202
+ alpha : float, optional
203
+ Two-sided significance level (default 0.05).
204
+ workers : int, optional
205
+ Number of local worker processes over which to spread the replicates (default 1,
206
+ serial). Each replicate seeds the shared RNG from its own index, so any worker
207
+ count returns results identical to a serial run.
208
+
209
+ Returns
210
+ -------
211
+ dict
212
+ Keys: `backend` (the estimator used), `n_sims`, `n_converged` (how many replicates
213
+ the model fit), `alpha`, `power`, `n_significant`, `true_effect`, `mean_estimate`,
214
+ `type_s`, `type_m`. `power` is the proportion of significant results among the
215
+ `n_converged` converged replicates, not among `n_sims`.
216
+
217
+ Raises
218
+ ------
219
+ ValueError
220
+ If the spec has no item unit (`power_mixed` requires a crossed design).
221
+ NotImplementedError
222
+ If the design does not have exactly one within-unit factor.
223
+
224
+ Notes
225
+ -----
226
+ Requires the `mixed` extra (`statsmodels` and `pandas`, imported lazily in each worker
227
+ process when parallel).
228
+ """
229
+ workers = _check_workers(workers)
230
+ import pandas as _pd # noqa: F401 fail fast before simulating
231
+ import statsmodels.formula.api as _smf # noqa: F401
232
+
233
+ if isinstance(spec, str):
234
+ spec = load_spec(spec)
235
+ if "item" not in spec["units"]:
236
+ raise ValueError("power_mixed() requires a crossed design with an item unit.")
237
+ within = [f for f in spec["factors"] if f.get("vary_within")]
238
+ if len(within) != 1:
239
+ raise NotImplementedError("The Python power_mixed backend expects exactly one within factor.")
240
+ f = within[0]
241
+ fname = f["name"]
242
+ col, vals = next(iter(f["contrasts"].items()))
243
+ l2c = {f["levels"][i]: vals[i] for i in range(len(f["levels"]))}
244
+ beta = spec["fixed"]["coefficients"][col]
245
+ yname, fam = spec["response"]["name"], spec["response"]["family"]
246
+ shift = spec["response"].get("shift", 0.0)
247
+ base = spec["seed"]
248
+
249
+ rep = functools.partial(_power_mixed_replicate, spec=spec, fname=fname, l2c=l2c,
250
+ yname=yname, fam=fam, shift=shift)
251
+ seeds = [base + i for i in range(n_sims)]
252
+ if workers == 1:
253
+ results = _map_replicates(rep, seeds, None)
254
+ else:
255
+ from concurrent.futures import ProcessPoolExecutor
256
+ with ProcessPoolExecutor(max_workers=workers) as executor:
257
+ results = _map_replicates(rep, seeds, executor)
258
+ est = [r[0] for r in results if r is not None]
259
+ pv = [r[1] for r in results if r is not None]
260
+
261
+ sig = [i for i, p in enumerate(pv) if p < alpha]
262
+ return {
263
+ "backend": "statsmodels MixedLM (crossed variance components, REML)",
264
+ "n_sims": n_sims, "n_converged": len(pv), "alpha": alpha,
265
+ "power": len(sig) / len(pv) if pv else float("nan"),
266
+ "n_significant": len(sig), "true_effect": beta,
267
+ "mean_estimate": statistics.mean(est) if est else float("nan"),
268
+ "type_s": (sum(1 for i in sig if (est[i] > 0) != (beta > 0)) / len(sig)) if sig else float("nan"),
269
+ "type_m": statistics.mean(abs(est[i]) / abs(beta) for i in sig) if sig else float("nan"),
270
+ }
271
+
272
+
273
+ def power_curve(spec, subject_ns, n_sims=1000, alpha=0.05, workers=1):
274
+ """Power curve over sample size for a two-group Gaussian design.
275
+
276
+ Sweep the number of subjects and compute `power` at each grid point.
277
+
278
+ Parameters
279
+ ----------
280
+ spec : dict or str
281
+ A two-group Gaussian design specification.
282
+ subject_ns : iterable of int
283
+ Subject counts to evaluate.
284
+ n_sims : int, optional
285
+ Replicates per grid point (default 1000).
286
+ alpha : float, optional
287
+ Significance level (default 0.05).
288
+ workers : int, optional
289
+ Number of local worker processes over which to spread the replicates at each grid
290
+ point (default 1, serial). One process pool is started and reused across the whole
291
+ sweep, and any worker count returns results identical to a serial run.
292
+
293
+ Returns
294
+ -------
295
+ list of dict
296
+ One dict per grid point, with keys `n_subject`, `power`, `type_m`.
297
+ """
298
+ workers = _check_workers(workers)
299
+ if isinstance(spec, str):
300
+ spec = load_spec(spec)
301
+
302
+ def sweep(executor):
303
+ out = []
304
+ for n in subject_ns:
305
+ s = copy.deepcopy(spec)
306
+ s["units"]["subject"]["n"] = n
307
+ r = _power_impl(s, n_sims, alpha, executor)
308
+ out.append({"n_subject": n, "power": r["power"], "type_m": r["type_m"]})
309
+ return out
310
+
311
+ if workers == 1:
312
+ return sweep(None)
313
+ from concurrent.futures import ProcessPoolExecutor
314
+ with ProcessPoolExecutor(max_workers=workers) as executor: # one pool for the sweep
315
+ return sweep(executor)
pilotr/simulate.py ADDED
@@ -0,0 +1,271 @@
1
+ """Spec parsing and the generative simulation engine.
2
+
3
+ The model is a linear predictor with user-specified fixed effect sizes, covering categorical
4
+ contrasts and continuous predictors as well as their interactions. To this it adds crossed by-subject and
5
+ by-item random intercepts and slopes (on contrasts or continuous predictors), and passes the
6
+ result through a link and a response family. The RNG draw order follows spec/SPEC.md, namely
7
+ per-subject item subsets (partial crossing only) -> continuous predictors -> subject random
8
+ effects -> item random effects -> extra grouping-factor random effects -> per-row response
9
+ draws (one deviate per row, except the beta family's rejection sampler, which consumes a
10
+ variable number). Specs without partial crossing or a `predictors` block keep the original
11
+ stream.
12
+ """
13
+
14
+ from __future__ import annotations
15
+ import json, math, itertools
16
+ from .core import RNG, cholesky, matvec, inv_logit, poisson_inv, ordinal_inv, beta_draw
17
+
18
+
19
+ class Dataset:
20
+ """A simulated data set: named columns and a list of row dicts.
21
+
22
+ Returned by `simulate`. Lightweight and dependency-free; build a pandas `DataFrame`
23
+ from `dataset.rows` when you need one.
24
+
25
+ Attributes
26
+ ----------
27
+ columns : list of str
28
+ Column names, in order.
29
+ rows : list of dict
30
+ One dict per observation, keyed by column name.
31
+ """
32
+
33
+ def __init__(self, columns, rows):
34
+ self.columns = columns
35
+ self.rows = rows # list of dict
36
+
37
+ def __len__(self):
38
+ return len(self.rows)
39
+
40
+ def column(self, name):
41
+ """Return the values in column `name` as a list."""
42
+ return [r[name] for r in self.rows]
43
+
44
+ def head(self, n=6):
45
+ """Return the first `n` rows (default 6) as a list of dicts."""
46
+ return self.rows[:n]
47
+
48
+ def to_csv(self, path):
49
+ """Write the data set to `path` as CSV: a header row then one row per observation."""
50
+ with open(path, "w", newline="") as f:
51
+ f.write(",".join(self.columns) + "\n")
52
+ for r in self.rows:
53
+ f.write(",".join(_fmt(r[c]) for c in self.columns) + "\n")
54
+
55
+
56
+ def _fmt(v):
57
+ return repr(v) if isinstance(v, float) else str(v)
58
+
59
+
60
+ def load_spec(path):
61
+ """Load a JSON design specification from a file.
62
+
63
+ Parameters
64
+ ----------
65
+ path : str
66
+ Path to a JSON design-specification file.
67
+
68
+ Returns
69
+ -------
70
+ dict
71
+ The parsed specification, ready for `simulate` or `power`.
72
+ """
73
+ with open(path, "r") as f:
74
+ return json.load(f)
75
+
76
+
77
+ def _ranef(unit_spec):
78
+ """Return (columns, lower-Cholesky L) for a unit's random-effect covariance."""
79
+ cols = ["intercept"] + list(unit_spec.get("slopes", {}).keys())
80
+ sds = [unit_spec["intercept_sd"]] + [unit_spec.get("slopes", {})[c] for c in cols[1:]]
81
+ n = len(cols)
82
+ R = [[1.0 if i == j else 0.0 for j in range(n)] for i in range(n)]
83
+ for key, val in unit_spec.get("correlations", {}).items():
84
+ a, b = [s.strip() for s in key.replace("~", ",").split(",")]
85
+ i, j = cols.index(a), cols.index(b)
86
+ R[i][j] = R[j][i] = val
87
+ cov = [[sds[i] * R[i][j] * sds[j] for j in range(n)] for i in range(n)]
88
+ return cols, cholesky(cov)
89
+
90
+
91
+ def _design_value(cvals, key):
92
+ """A coefficient/slope key is a column name or an 'a:b' interaction (product of columns)."""
93
+ if ":" in key:
94
+ v = 1.0
95
+ for part in key.split(":"):
96
+ v *= cvals.get(part, 0.0)
97
+ return v
98
+ return cvals.get(key, 0.0)
99
+
100
+
101
+ def _sample_items(rng, n_items, m):
102
+ """Sample m distinct items from 1..n_items via partial Fisher-Yates on the shared RNG.
103
+ This supports partial crossing, where each subject sees a self-selected subset of items."""
104
+ pool = list(range(1, n_items + 1))
105
+ for k in range(m):
106
+ j = k + int(rng.uniform() * (n_items - k))
107
+ pool[k], pool[j] = pool[j], pool[k]
108
+ return sorted(pool[:m])
109
+
110
+
111
+ def simulate(spec) -> Dataset:
112
+ """Simulate a data set from a design specification.
113
+
114
+ Build a linear predictor from the fixed effect sizes (categorical contrasts, continuous
115
+ predictors and their interactions) plus the crossed by-subject and by-item random
116
+ intercepts and slopes, then map it through the chosen response family.
117
+
118
+ Parameters
119
+ ----------
120
+ spec : dict or str
121
+ A design specification, either an already-parsed `dict` or a path to a JSON spec
122
+ file. The format is documented at
123
+ https://github.com/pablobernabeu/pilotr/blob/main/spec/SPEC.md.
124
+
125
+ Returns
126
+ -------
127
+ Dataset
128
+ A table with one row per observation: a `subject` column, an optional `item` column,
129
+ any grouping, factor, and continuous-predictor columns, and the response column named
130
+ by ``spec["response"]["name"]``.
131
+ """
132
+ if isinstance(spec, str):
133
+ spec = load_spec(spec)
134
+
135
+ S = spec["units"]["subject"]["n"]
136
+ has_item = "item" in spec["units"]
137
+ I = spec["units"]["item"]["n"] if has_item else 1
138
+
139
+ factors = spec.get("factors", [])
140
+ predictors = spec.get("predictors", [])
141
+ within = [f for f in factors if f.get("vary_within")]
142
+ between = [f for f in factors if f.get("between")]
143
+
144
+ rng = RNG(spec["seed"])
145
+ per_subject = spec["units"]["item"].get("per_subject") if has_item else None
146
+ if per_subject is not None:
147
+ if per_subject < 1:
148
+ raise ValueError(f"per_subject ({per_subject}) must be at least 1")
149
+ if per_subject > I:
150
+ raise ValueError(f"per_subject ({per_subject}) cannot exceed the number of items ({I})")
151
+
152
+ # ---- build design rows in canonical order ----
153
+ # When per_subject is set, each subject's item subset is sampled here, which is the first
154
+ # RNG consumption (see spec/SPEC.md). Full-crossing specs draw nothing here, keeping the stream.
155
+ within_level_ranges = [range(len(f["levels"])) for f in within]
156
+ rows = []
157
+ for s in range(1, S + 1):
158
+ items_s = _sample_items(rng, I, per_subject) if per_subject else range(1, I + 1)
159
+ for t in items_s:
160
+ for combo in (itertools.product(*within_level_ranges) if within else [()]):
161
+ level_idx = {}
162
+ for f, li in zip(within, combo):
163
+ level_idx[f["name"]] = li
164
+ for f in between:
165
+ n_lev = len(f["levels"])
166
+ unit = s if f["between"] == "subject" else t
167
+ n_unit = S if f["between"] == "subject" else I
168
+ level_idx[f["name"]] = ((unit - 1) * n_lev) // n_unit
169
+ cvals, labels = {}, {}
170
+ for f in factors:
171
+ li = level_idx[f["name"]]
172
+ labels[f["name"]] = f["levels"][li]
173
+ for col, vals in f["contrasts"].items():
174
+ cvals[col] = vals[li]
175
+ rows.append({"subject": s, "item": t if has_item else None,
176
+ "labels": labels, "cvals": cvals})
177
+
178
+ # ---- continuous predictors: one draw per unit (subject- or item-level) ----
179
+ pred_values = {}
180
+ for p in predictors:
181
+ unit, n_unit = p["varies_by"], (S if p["varies_by"] == "subject" else I)
182
+ if unit == "item" and not has_item:
183
+ raise ValueError(f"predictor '{p['name']}' varies_by item but design has no items")
184
+ mean, sd = p.get("mean", 0.0), p.get("sd", 1.0)
185
+ pred_values[p["name"]] = {u: mean + sd * rng.normal() for u in range(1, n_unit + 1)}
186
+ for r in rows:
187
+ for p in predictors:
188
+ r["cvals"][p["name"]] = pred_values[p["name"]][r["subject"] if p["varies_by"] == "subject" else r["item"]]
189
+
190
+ # ---- random effects (subject then item) ----
191
+ random_spec = spec.get("random", {}) or {}
192
+ b_subject, subj_cols = {}, []
193
+ if "subject" in random_spec:
194
+ subj_cols, L = _ranef(random_spec["subject"])
195
+ for s in range(1, S + 1):
196
+ b_subject[s] = matvec(L, rng.normals(len(subj_cols)))
197
+ b_item, item_cols = {}, []
198
+ if has_item and "item" in random_spec:
199
+ item_cols, L = _ranef(random_spec["item"])
200
+ for t in range(1, I + 1):
201
+ b_item[t] = matvec(L, rng.normals(len(item_cols)))
202
+
203
+ # ---- additional grouping factors (e.g. units nested in higher-level clusters) ----
204
+ # Any random-effect entry other than subject/item declares `over` (which unit it groups)
205
+ # and `n` (number of groups). Units are assigned to groups in equal blocks.
206
+ extra = [(k, v) for k, v in random_spec.items() if k not in ("subject", "item")]
207
+ b_group, group_meta = {}, {}
208
+ for gname, gspec in extra:
209
+ over, K = gspec["over"], gspec["n"]
210
+ n_over = S if over == "subject" else I
211
+ cols, L = _ranef(gspec)
212
+ group_of = {u: ((u - 1) * K) // n_over for u in range(1, n_over + 1)}
213
+ group_meta[gname] = (over, cols, group_of)
214
+ b_group[gname] = {g: matvec(L, rng.normals(len(cols))) for g in range(K)}
215
+
216
+ # ---- linear predictor + response per row (residual draws happen here) ----
217
+ intercept = spec["fixed"]["intercept"]
218
+ coeffs = spec["fixed"]["coefficients"]
219
+ resp = spec["response"]
220
+ family, yname = resp["family"], resp["name"]
221
+ sigma, shift = resp.get("sigma"), resp.get("shift", 0.0)
222
+ thresholds, ndp = resp.get("thresholds"), resp.get("round")
223
+
224
+ out_cols = (["subject"] + (["item"] if has_item else []) + [g for g, _ in extra] +
225
+ [f["name"] for f in factors] + [p["name"] for p in predictors] + [yname])
226
+ out_rows = []
227
+ for r in rows:
228
+ cv = r["cvals"]
229
+ eta = intercept + sum(beta * _design_value(cv, col) for col, beta in coeffs.items())
230
+ if r["subject"] in b_subject:
231
+ b = b_subject[r["subject"]]
232
+ eta += b[0] + sum(b[j] * cv.get(subj_cols[j], 0.0) for j in range(1, len(subj_cols)))
233
+ if has_item and r["item"] in b_item:
234
+ b = b_item[r["item"]]
235
+ eta += b[0] + sum(b[j] * cv.get(item_cols[j], 0.0) for j in range(1, len(item_cols)))
236
+ for gname, (over, cols, group_of) in group_meta.items():
237
+ b = b_group[gname][group_of[r[over]]]
238
+ eta += b[0] + sum(b[j] * cv.get(cols[j], 0.0) for j in range(1, len(cols)))
239
+
240
+ if family == "gaussian":
241
+ y = eta + sigma * rng.normal()
242
+ elif family == "shifted_lognormal":
243
+ y = shift + math.exp(eta + sigma * rng.normal())
244
+ elif family == "lognormal":
245
+ y = math.exp(eta + sigma * rng.normal())
246
+ elif family == "bernoulli":
247
+ y = 1 if rng.uniform() < inv_logit(eta) else 0
248
+ elif family == "poisson":
249
+ y = poisson_inv(math.exp(eta), rng.uniform())
250
+ elif family == "ordinal":
251
+ y = ordinal_inv(eta, thresholds, rng.uniform())
252
+ elif family == "beta":
253
+ mu, phi = inv_logit(eta), resp.get("phi", 10.0)
254
+ y = beta_draw(rng, mu * phi, (1.0 - mu) * phi)
255
+ else:
256
+ raise ValueError(f"unknown family: {family}")
257
+ if ndp is not None and isinstance(y, float):
258
+ y = round(y, ndp)
259
+
260
+ out = {"subject": r["subject"]}
261
+ if has_item:
262
+ out["item"] = r["item"]
263
+ for gname, (over, cols, group_of) in group_meta.items():
264
+ out[gname] = group_of[r[over]] + 1
265
+ out.update(r["labels"])
266
+ for p in predictors:
267
+ out[p["name"]] = cv[p["name"]]
268
+ out[yname] = y
269
+ out_rows.append(out)
270
+
271
+ return Dataset(out_cols, out_rows)
@@ -0,0 +1,78 @@
1
+ Metadata-Version: 2.4
2
+ Name: pilotr
3
+ Version: 0.1.0
4
+ Summary: Simulate experimental and behavioural data from a portable design specification (cross-language with the R package of the same name).
5
+ Author-email: Pablo Bernabeu <pcbernabeu@gmail.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://pablobernabeu.github.io/pilotr/
8
+ Project-URL: Repository, https://github.com/pablobernabeu/pilotr
9
+ Project-URL: Documentation, https://pablobernabeu.github.io/pilotr/py/
10
+ Project-URL: Issues, https://github.com/pablobernabeu/pilotr/issues
11
+ Keywords: simulation,power analysis,mixed-effects,experimental design,behavioural science
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.9
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Topic :: Scientific/Engineering
22
+ Classifier: Topic :: Scientific/Engineering :: Mathematics
23
+ Requires-Python: >=3.9
24
+ Description-Content-Type: text/markdown
25
+ License-File: LICENSE
26
+ Provides-Extra: power
27
+ Requires-Dist: scipy>=1.7; extra == "power"
28
+ Provides-Extra: mixed
29
+ Requires-Dist: scipy>=1.7; extra == "mixed"
30
+ Requires-Dist: statsmodels>=0.13; extra == "mixed"
31
+ Requires-Dist: pandas>=1.3; extra == "mixed"
32
+ Provides-Extra: dev
33
+ Requires-Dist: scipy>=1.7; extra == "dev"
34
+ Requires-Dist: statsmodels>=0.13; extra == "dev"
35
+ Requires-Dist: pandas>=1.3; extra == "dev"
36
+ Requires-Dist: pytest>=7; extra == "dev"
37
+ Dynamic: license-file
38
+
39
+ # pilotr (Python)
40
+
41
+ Python implementation of pilotr. It simulates experimental and behavioural data from a
42
+ portable JSON design specification, producing output that is bit-identical to the
43
+ [R package of the same name](https://pablobernabeu.github.io/pilotr/). See the
44
+ [project README](https://github.com/pablobernabeu/pilotr) for the full toolkit (the no-code
45
+ app, the R package and the specification format).
46
+
47
+ ## Install
48
+
49
+ ```bash
50
+ pip install pilotr # core engine (pure Python, dependency-free)
51
+ pip install "pilotr[power]" # + scipy, for the simulation-based power demo
52
+ ```
53
+
54
+ Requires Python 3.9 or later; the generative core has no dependencies.
55
+
56
+ For development, install from a checkout of the repository instead: clone
57
+ <https://github.com/pablobernabeu/pilotr> and run `pip install .` (or `pip install ".[dev]"`)
58
+ from the `python` directory.
59
+
60
+ ## Quick start
61
+
62
+ ```python
63
+ from pilotr import simulate
64
+
65
+ spec = {
66
+ "name": "two_group", "seed": 2024,
67
+ "units": {"subject": {"n": 64}},
68
+ "factors": [{"name": "group", "levels": ["control", "treatment"],
69
+ "contrasts": {"effect": [-0.5, 0.5]}, "between": "subject"}],
70
+ "fixed": {"intercept": 100, "coefficients": {"effect": 5}},
71
+ "response": {"family": "gaussian", "name": "score", "sigma": 10},
72
+ }
73
+
74
+ data = simulate(spec) # 64 rows
75
+ ```
76
+
77
+ Given the same specification and seed, this reproduces the data generated by the R package
78
+ to full floating-point precision.
@@ -0,0 +1,9 @@
1
+ pilotr/__init__.py,sha256=F13CHu6HX-uvAm1kSqVT05QLYp90j8_8uRJ95I4Cj_A,392
2
+ pilotr/core.py,sha256=AZu6r9RFnbT-73sw-Z5DDwslC2RR2nBotMn6CCZs4Is,7152
3
+ pilotr/power.py,sha256=QdKb-agxgCFfRFxigxgflPRg8YdYUCQyjNhwIU3YlEo,13992
4
+ pilotr/simulate.py,sha256=3QbrD3OL3v-2i4OF2_jbuz_TIHLS68UiOXGLOF8bkpQ,11408
5
+ pilotr-0.1.0.dist-info/licenses/LICENSE,sha256=V6zxJEIxfuR2jJtsXg9HpC5B8P0ZXKM-LdAKSP_J8aQ,1071
6
+ pilotr-0.1.0.dist-info/METADATA,sha256=u7UvLKDL_4qBQ0kcjXWlDZilvi1BPpOm3gKWtSBRTLo,3164
7
+ pilotr-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
8
+ pilotr-0.1.0.dist-info/top_level.txt,sha256=yxCE48nPxbDSHKR5UbpyKsFJ3_-l7m1mgoMWabfmJDg,7
9
+ pilotr-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (83.0.0)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Pablo Bernabeu
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 @@
1
+ pilotr