pilotr 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.
- pilotr-0.1.0/LICENSE +21 -0
- pilotr-0.1.0/PKG-INFO +78 -0
- pilotr-0.1.0/README.md +40 -0
- pilotr-0.1.0/pilotr/__init__.py +8 -0
- pilotr-0.1.0/pilotr/core.py +190 -0
- pilotr-0.1.0/pilotr/power.py +315 -0
- pilotr-0.1.0/pilotr/simulate.py +271 -0
- pilotr-0.1.0/pilotr.egg-info/PKG-INFO +78 -0
- pilotr-0.1.0/pilotr.egg-info/SOURCES.txt +14 -0
- pilotr-0.1.0/pilotr.egg-info/dependency_links.txt +1 -0
- pilotr-0.1.0/pilotr.egg-info/requires.txt +14 -0
- pilotr-0.1.0/pilotr.egg-info/top_level.txt +1 -0
- pilotr-0.1.0/pyproject.toml +42 -0
- pilotr-0.1.0/setup.cfg +4 -0
- pilotr-0.1.0/tests/test_basics.py +98 -0
- pilotr-0.1.0/tests/test_parallel.py +95 -0
pilotr-0.1.0/LICENSE
ADDED
|
@@ -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.
|
pilotr-0.1.0/PKG-INFO
ADDED
|
@@ -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.
|
pilotr-0.1.0/README.md
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# pilotr (Python)
|
|
2
|
+
|
|
3
|
+
Python implementation of pilotr. It simulates experimental and behavioural data from a
|
|
4
|
+
portable JSON design specification, producing output that is bit-identical to the
|
|
5
|
+
[R package of the same name](https://pablobernabeu.github.io/pilotr/). See the
|
|
6
|
+
[project README](https://github.com/pablobernabeu/pilotr) for the full toolkit (the no-code
|
|
7
|
+
app, the R package and the specification format).
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
pip install pilotr # core engine (pure Python, dependency-free)
|
|
13
|
+
pip install "pilotr[power]" # + scipy, for the simulation-based power demo
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Requires Python 3.9 or later; the generative core has no dependencies.
|
|
17
|
+
|
|
18
|
+
For development, install from a checkout of the repository instead: clone
|
|
19
|
+
<https://github.com/pablobernabeu/pilotr> and run `pip install .` (or `pip install ".[dev]"`)
|
|
20
|
+
from the `python` directory.
|
|
21
|
+
|
|
22
|
+
## Quick start
|
|
23
|
+
|
|
24
|
+
```python
|
|
25
|
+
from pilotr import simulate
|
|
26
|
+
|
|
27
|
+
spec = {
|
|
28
|
+
"name": "two_group", "seed": 2024,
|
|
29
|
+
"units": {"subject": {"n": 64}},
|
|
30
|
+
"factors": [{"name": "group", "levels": ["control", "treatment"],
|
|
31
|
+
"contrasts": {"effect": [-0.5, 0.5]}, "between": "subject"}],
|
|
32
|
+
"fixed": {"intercept": 100, "coefficients": {"effect": 5}},
|
|
33
|
+
"response": {"family": "gaussian", "name": "score", "sigma": 10},
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
data = simulate(spec) # 64 rows
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Given the same specification and seed, this reproduces the data generated by the R package
|
|
40
|
+
to full floating-point precision.
|
|
@@ -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"]
|
|
@@ -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))
|
|
@@ -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)
|
|
@@ -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,14 @@
|
|
|
1
|
+
LICENSE
|
|
2
|
+
README.md
|
|
3
|
+
pyproject.toml
|
|
4
|
+
pilotr/__init__.py
|
|
5
|
+
pilotr/core.py
|
|
6
|
+
pilotr/power.py
|
|
7
|
+
pilotr/simulate.py
|
|
8
|
+
pilotr.egg-info/PKG-INFO
|
|
9
|
+
pilotr.egg-info/SOURCES.txt
|
|
10
|
+
pilotr.egg-info/dependency_links.txt
|
|
11
|
+
pilotr.egg-info/requires.txt
|
|
12
|
+
pilotr.egg-info/top_level.txt
|
|
13
|
+
tests/test_basics.py
|
|
14
|
+
tests/test_parallel.py
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
pilotr
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "pilotr"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Simulate experimental and behavioural data from a portable design specification (cross-language with the R package of the same name)."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.9"
|
|
11
|
+
authors = [{ name = "Pablo Bernabeu", email = "pcbernabeu@gmail.com" }]
|
|
12
|
+
license = "MIT"
|
|
13
|
+
license-files = ["LICENSE"]
|
|
14
|
+
keywords = ["simulation", "power analysis", "mixed-effects", "experimental design", "behavioural science"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 3 - Alpha",
|
|
17
|
+
"Intended Audience :: Science/Research",
|
|
18
|
+
"Operating System :: OS Independent",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Programming Language :: Python :: 3.9",
|
|
21
|
+
"Programming Language :: Python :: 3.10",
|
|
22
|
+
"Programming Language :: Python :: 3.11",
|
|
23
|
+
"Programming Language :: Python :: 3.12",
|
|
24
|
+
"Programming Language :: Python :: 3.13",
|
|
25
|
+
"Topic :: Scientific/Engineering",
|
|
26
|
+
"Topic :: Scientific/Engineering :: Mathematics",
|
|
27
|
+
]
|
|
28
|
+
dependencies = [] # the generative core is pure-Python and dependency-free
|
|
29
|
+
|
|
30
|
+
[project.optional-dependencies]
|
|
31
|
+
power = ["scipy>=1.7"] # two-group Gaussian power (p-values)
|
|
32
|
+
mixed = ["scipy>=1.7", "statsmodels>=0.13", "pandas>=1.3"] # crossed mixed-effects power
|
|
33
|
+
dev = ["scipy>=1.7", "statsmodels>=0.13", "pandas>=1.3", "pytest>=7"]
|
|
34
|
+
|
|
35
|
+
[project.urls]
|
|
36
|
+
Homepage = "https://pablobernabeu.github.io/pilotr/"
|
|
37
|
+
Repository = "https://github.com/pablobernabeu/pilotr"
|
|
38
|
+
Documentation = "https://pablobernabeu.github.io/pilotr/py/"
|
|
39
|
+
Issues = "https://github.com/pablobernabeu/pilotr/issues"
|
|
40
|
+
|
|
41
|
+
[tool.setuptools]
|
|
42
|
+
packages = ["pilotr"]
|
pilotr-0.1.0/setup.cfg
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
"""Minimal validation suite (run with: pytest python/tests).
|
|
2
|
+
|
|
3
|
+
Covers the three things a methods-package reviewer checks first: the RNG is
|
|
4
|
+
deterministic, the inverse-normal is numerically correct, and the engine recovers the
|
|
5
|
+
ground-truth parameters it was given.
|
|
6
|
+
"""
|
|
7
|
+
import os, sys, statistics, math
|
|
8
|
+
sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
|
|
9
|
+
|
|
10
|
+
import pytest
|
|
11
|
+
|
|
12
|
+
from pilotr import RNG, as241, simulate, load_spec
|
|
13
|
+
|
|
14
|
+
SPEC = os.path.join(os.path.dirname(__file__), "..", "..", "spec", "examples")
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def test_rng_is_deterministic():
|
|
18
|
+
a = [RNG(123).uniform() for _ in range(1)]
|
|
19
|
+
b = RNG(123).uniform()
|
|
20
|
+
assert a[0] == b
|
|
21
|
+
stream = RNG(7); xs = [stream.uniform() for _ in range(1000)]
|
|
22
|
+
assert all(0.0 < x < 1.0 for x in xs)
|
|
23
|
+
assert len(set(xs)) == len(xs) # no immediate repeats
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def test_as241_matches_known_quantiles():
|
|
27
|
+
# qnorm(0.975) = 1.959963985; qnorm(0.5) = 0; symmetric
|
|
28
|
+
assert abs(as241(0.975) - 1.959963984540054) < 1e-9
|
|
29
|
+
assert abs(as241(0.5)) < 1e-12
|
|
30
|
+
assert abs(as241(0.975) + as241(0.025)) < 1e-9
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def test_gaussian_recovers_effect_at_large_n():
|
|
34
|
+
s = load_spec(os.path.join(SPEC, "between_2group_gaussian.json"))
|
|
35
|
+
s["units"]["subject"]["n"] = 40000
|
|
36
|
+
d = simulate(s)
|
|
37
|
+
g0 = [r["score"] for r in d.rows if r["group"] == "control"]
|
|
38
|
+
g1 = [r["score"] for r in d.rows if r["group"] == "treatment"]
|
|
39
|
+
assert len(g0) == len(g1) == 20000
|
|
40
|
+
assert abs((statistics.mean(g1) - statistics.mean(g0)) - 5.0) < 0.3
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def test_mixed_rt_has_expected_structure():
|
|
44
|
+
d = simulate(os.path.join(SPEC, "crossed_mixed_rt.json"))
|
|
45
|
+
assert len(d) == 30 * 24 * 2
|
|
46
|
+
rel = [r["RT"] for r in d.rows if r["condition"] == "related"]
|
|
47
|
+
unr = [r["RT"] for r in d.rows if r["condition"] == "unrelated"]
|
|
48
|
+
assert min(rel) > 200 # shifted-lognormal floor = shift (200 ms non-decision time)
|
|
49
|
+
assert statistics.mean(unr) > statistics.mean(rel) # positive priming effect
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def test_simulation_is_reproducible():
|
|
53
|
+
d1 = simulate(os.path.join(SPEC, "crossed_mixed_rt.json"))
|
|
54
|
+
d2 = simulate(os.path.join(SPEC, "crossed_mixed_rt.json"))
|
|
55
|
+
assert [r["RT"] for r in d1.rows] == [r["RT"] for r in d2.rows]
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def test_beta_family_in_unit_interval_and_ordered():
|
|
59
|
+
d = simulate(os.path.join(SPEC, "beta_proportion.json"))
|
|
60
|
+
vals = [r["prop"] for r in d.rows]
|
|
61
|
+
assert all(0.0 < v < 1.0 for v in vals)
|
|
62
|
+
ctrl = [r["prop"] for r in d.rows if r["group"] == "control"]
|
|
63
|
+
trt = [r["prop"] for r in d.rows if r["group"] == "treatment"]
|
|
64
|
+
assert statistics.mean(trt) > statistics.mean(ctrl) # grp +0.8 on the logit scale
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def test_partial_crossing_subset_size():
|
|
68
|
+
d = simulate(os.path.join(SPEC, "partial_crossing.json"))
|
|
69
|
+
items_by_subject = {}
|
|
70
|
+
for r in d.rows:
|
|
71
|
+
items_by_subject.setdefault(r["subject"], set()).add(r["item"])
|
|
72
|
+
assert len(items_by_subject) == 60
|
|
73
|
+
assert all(len(v) == 12 for v in items_by_subject.values()) # per_subject = 12
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def test_per_subject_must_lie_between_1_and_n_items():
|
|
77
|
+
# The same inputs must raise in the R twin, preserving cross-language parity.
|
|
78
|
+
spec = {
|
|
79
|
+
"name": "pc", "seed": 1,
|
|
80
|
+
"units": {"subject": {"n": 2}, "item": {"n": 3, "per_subject": 5}},
|
|
81
|
+
"factors": [{"name": "cond", "levels": ["a", "b"],
|
|
82
|
+
"contrasts": {"cond": [-0.5, 0.5]}, "vary_within": ["subject", "item"]}],
|
|
83
|
+
"fixed": {"intercept": 6, "coefficients": {"cond": 0.05}},
|
|
84
|
+
"random": {"subject": {"intercept_sd": 0.1}, "item": {"intercept_sd": 0.1}},
|
|
85
|
+
"response": {"family": "gaussian", "name": "y", "sigma": 0.3},
|
|
86
|
+
}
|
|
87
|
+
with pytest.raises(ValueError, match="cannot exceed the number of items"):
|
|
88
|
+
simulate(spec)
|
|
89
|
+
spec["units"]["item"]["per_subject"] = 0
|
|
90
|
+
with pytest.raises(ValueError, match="at least 1"):
|
|
91
|
+
simulate(spec)
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def test_additional_grouping_column_present():
|
|
95
|
+
d = simulate(os.path.join(SPEC, "nested_clusters.json"))
|
|
96
|
+
assert "site" in d.columns
|
|
97
|
+
sites = set(r["site"] for r in d.rows)
|
|
98
|
+
assert sites == set(range(1, 13)) # 12 clusters
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
"""Parallel execution must reproduce the serial stream exactly. Every replicate seeds
|
|
2
|
+
the shared cross-language RNG from its own index, so the worker count can change only
|
|
3
|
+
the wall-clock time, never a number.
|
|
4
|
+
"""
|
|
5
|
+
import math, os, sys
|
|
6
|
+
sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
|
|
7
|
+
|
|
8
|
+
import pytest
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
def assert_identical(a, b):
|
|
12
|
+
"""Assert two result dicts are identical, treating NaN as equal to NaN (the Type S and
|
|
13
|
+
Type M entries are NaN when no replicate reaches significance)."""
|
|
14
|
+
assert a.keys() == b.keys()
|
|
15
|
+
for k in a:
|
|
16
|
+
va, vb = a[k], b[k]
|
|
17
|
+
if isinstance(va, float) and isinstance(vb, float) and math.isnan(va) and math.isnan(vb):
|
|
18
|
+
continue
|
|
19
|
+
assert va == vb, f"{k}: {va!r} != {vb!r}"
|
|
20
|
+
|
|
21
|
+
pytest.importorskip("scipy") # the power backends need scipy, an optional extra
|
|
22
|
+
|
|
23
|
+
from pilotr import power, power_curve
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def _spec():
|
|
27
|
+
return {
|
|
28
|
+
"name": "par", "seed": 11,
|
|
29
|
+
"units": {"subject": {"n": 24}},
|
|
30
|
+
"factors": [{"name": "group", "levels": ["control", "treatment"],
|
|
31
|
+
"contrasts": {"effect": [-0.5, 0.5]}, "between": "subject"}],
|
|
32
|
+
"fixed": {"intercept": 100, "coefficients": {"effect": 5}},
|
|
33
|
+
"response": {"family": "gaussian", "name": "score", "sigma": 10},
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def test_workers_is_validated():
|
|
38
|
+
for bad in (0, -1, 1.5, "two", True):
|
|
39
|
+
with pytest.raises(ValueError):
|
|
40
|
+
power(_spec(), n_sims=2, workers=bad)
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def test_power_parallel_matches_serial():
|
|
44
|
+
serial = power(_spec(), n_sims=8, workers=1)
|
|
45
|
+
parallel2 = power(_spec(), n_sims=8, workers=2)
|
|
46
|
+
assert serial == parallel2
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def test_power_curve_parallel_matches_serial():
|
|
50
|
+
serial = power_curve(_spec(), subject_ns=[16, 24], n_sims=8, workers=1)
|
|
51
|
+
parallel2 = power_curve(_spec(), subject_ns=[16, 24], n_sims=8, workers=2)
|
|
52
|
+
assert serial == parallel2
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def test_power_mixed_rejects_spec_without_items():
|
|
56
|
+
pytest.importorskip("statsmodels")
|
|
57
|
+
pytest.importorskip("pandas")
|
|
58
|
+
from pilotr import power_mixed
|
|
59
|
+
|
|
60
|
+
spec = {
|
|
61
|
+
"name": "w", "seed": 1,
|
|
62
|
+
"units": {"subject": {"n": 20}},
|
|
63
|
+
"factors": [{"name": "cond", "levels": ["a", "b"],
|
|
64
|
+
"contrasts": {"cond": [-0.5, 0.5]}, "vary_within": "subject"}],
|
|
65
|
+
"fixed": {"intercept": 6, "coefficients": {"cond": 0.05}},
|
|
66
|
+
"random": {"subject": {"intercept_sd": 0.12, "slopes": {"cond": 0.04},
|
|
67
|
+
"correlations": {"intercept~cond": 0.2}}},
|
|
68
|
+
"response": {"family": "gaussian", "name": "y", "sigma": 0.3},
|
|
69
|
+
}
|
|
70
|
+
with pytest.raises(ValueError, match="requires a crossed design with an item unit"):
|
|
71
|
+
power_mixed(spec, n_sims=2)
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def test_power_mixed_parallel_matches_serial():
|
|
75
|
+
pytest.importorskip("statsmodels")
|
|
76
|
+
pytest.importorskip("pandas")
|
|
77
|
+
from pilotr import power_mixed
|
|
78
|
+
|
|
79
|
+
spec = {
|
|
80
|
+
"name": "parmix", "seed": 3,
|
|
81
|
+
"units": {"subject": {"n": 10}, "item": {"n": 6}},
|
|
82
|
+
"factors": [{"name": "cond", "levels": ["a", "b"],
|
|
83
|
+
"contrasts": {"cond": [-0.5, 0.5]}, "vary_within": "subject"}],
|
|
84
|
+
"fixed": {"intercept": 6, "coefficients": {"cond": 0.05}},
|
|
85
|
+
"random": {
|
|
86
|
+
"subject": {"intercept_sd": 0.12, "slopes": {"cond": 0.04},
|
|
87
|
+
"correlations": {"intercept~cond": 0.2}},
|
|
88
|
+
"item": {"intercept_sd": 0.08, "slopes": {"cond": 0.02},
|
|
89
|
+
"correlations": {"intercept~cond": -0.1}},
|
|
90
|
+
},
|
|
91
|
+
"response": {"family": "shifted_lognormal", "name": "RT", "sigma": 0.3, "shift": 200},
|
|
92
|
+
}
|
|
93
|
+
serial = power_mixed(spec, n_sims=4, workers=1)
|
|
94
|
+
parallel2 = power_mixed(spec, n_sims=4, workers=2)
|
|
95
|
+
assert_identical(serial, parallel2)
|