lexsync 0.1.1__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.
- lexsync/__init__.py +53 -0
- lexsync/__main__.py +5 -0
- lexsync/blocks.py +149 -0
- lexsync/cli.py +85 -0
- lexsync/corpora.py +331 -0
- lexsync/counterbalancing.py +399 -0
- lexsync/data/en_example.csv +3001 -0
- lexsync/data/es_example.csv +3001 -0
- lexsync/data/registry.yaml +149 -0
- lexsync/data/schema.yaml +193 -0
- lexsync/data/zh_example.csv +3001 -0
- lexsync/datasheet.py +752 -0
- lexsync/generation.py +280 -0
- lexsync/io_utils.py +609 -0
- lexsync/logging.py +88 -0
- lexsync/matching.py +614 -0
- lexsync/pairs.py +177 -0
- lexsync/paradigms.py +163 -0
- lexsync/py.typed +0 -0
- lexsync/querying.py +481 -0
- lexsync/run_pipeline.py +425 -0
- lexsync/scripting.py +845 -0
- lexsync/templates/jspsych/experiment_template.html +223 -0
- lexsync/templates/opensesame/README.md +36 -0
- lexsync/templates/opensesame/inline_send_triggers.py +18 -0
- lexsync/templates/opensesame/inline_trigger_setup.py +53 -0
- lexsync/templates/psychopy/mock_port.py +23 -0
- lexsync/templates/psychopy/trial_runner_template.py +300 -0
- lexsync/validation.py +267 -0
- lexsync-0.1.1.dist-info/METADATA +234 -0
- lexsync-0.1.1.dist-info/RECORD +35 -0
- lexsync-0.1.1.dist-info/WHEEL +4 -0
- lexsync-0.1.1.dist-info/entry_points.txt +2 -0
- lexsync-0.1.1.dist-info/licenses/LICENSE +33 -0
- lexsync-0.1.1.dist-info/licenses/LICENSE.note +108 -0
lexsync/datasheet.py
ADDED
|
@@ -0,0 +1,752 @@
|
|
|
1
|
+
"""Materials datasheet and pre-registration template.
|
|
2
|
+
|
|
3
|
+
A *materials datasheet* is a machine- and human-readable provenance record for a
|
|
4
|
+
design. It records where the items came from, how they were selected, matched and
|
|
5
|
+
counterbalanced, the realised control, and the seeds, versions and checksums needed
|
|
6
|
+
to reproduce them exactly. It is the shareable materials record whose scarcity
|
|
7
|
+
motivates lexsync (Bochynska et al., 2023; Roettger, 2019). The
|
|
8
|
+
module also emits an auto-filled Methods paragraph and a pre-registration
|
|
9
|
+
skeleton. Mirrors R_workflow/R/datasheet.R.
|
|
10
|
+
"""
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
import json
|
|
14
|
+
import platform
|
|
15
|
+
|
|
16
|
+
from .io_utils import _is_continuous, _round_dp, sha256_file
|
|
17
|
+
|
|
18
|
+
# The cap the pairwise (joint, optimal) matchers apply before pairing. Imported from
|
|
19
|
+
# matching so the datasheet can only ever record the value the selection used.
|
|
20
|
+
from .matching import PAIRWISE_CAP
|
|
21
|
+
|
|
22
|
+
# 1.1 added `materials_source["norms"]` (the design's joined norm tables, with their
|
|
23
|
+
# checksums and per-column coverage) and, for a pair-keyed design, a `relational`
|
|
24
|
+
# block plus an honest `selection["cross_engine"]`. Both were required by the rule
|
|
25
|
+
# that anything affecting item selection is recorded here: a norm table can carry the
|
|
26
|
+
# manipulated variable itself, and the pair path performs a real selection that the
|
|
27
|
+
# record used to describe as "n/a (user-supplied items)".
|
|
28
|
+
DATASHEET_VERSION = "1.1"
|
|
29
|
+
|
|
30
|
+
# Datasheet labels for the pseudoword generators in generation.py, keyed by the
|
|
31
|
+
# items.generation.method token. Kept character-for-character identical to
|
|
32
|
+
# .GENERATION_LABELS in datasheet.R so the two engines' records stay comparable.
|
|
33
|
+
_GENERATION_LABELS = {
|
|
34
|
+
"letter_substitution": "constrained letter substitution (deterministic pseudowords)",
|
|
35
|
+
"subsyllabic": "subsyllabic constituent swap (Wuggy-style, deterministic pseudowords)",
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def _lexsync_version() -> str:
|
|
40
|
+
"""The installed lexsync version, mirroring datasheet.R's packageVersion lookup."""
|
|
41
|
+
try:
|
|
42
|
+
from importlib.metadata import version
|
|
43
|
+
return version("lexsync")
|
|
44
|
+
except Exception:
|
|
45
|
+
# Deferred: __init__ imports this module before it binds __version__.
|
|
46
|
+
from . import __version__
|
|
47
|
+
return __version__
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def _versions(engine: str) -> dict:
|
|
51
|
+
out = {"engine": engine, "lexsync": _lexsync_version()}
|
|
52
|
+
if engine == "python":
|
|
53
|
+
import numpy as np
|
|
54
|
+
import pandas as pd
|
|
55
|
+
out["python"] = platform.python_version()
|
|
56
|
+
out["pandas"] = pd.__version__
|
|
57
|
+
out["numpy"] = np.__version__
|
|
58
|
+
try:
|
|
59
|
+
import scipy
|
|
60
|
+
out["scipy"] = scipy.__version__
|
|
61
|
+
except Exception:
|
|
62
|
+
pass
|
|
63
|
+
# Distribution metadata, because neither package exports __version__.
|
|
64
|
+
from importlib.metadata import version
|
|
65
|
+
for pkg in ("rapidfuzz", "pyyaml"):
|
|
66
|
+
try:
|
|
67
|
+
out[pkg] = version(pkg)
|
|
68
|
+
except Exception:
|
|
69
|
+
pass
|
|
70
|
+
# The OS completes the environment record; per-engine, like the rest of the block.
|
|
71
|
+
out["os"] = platform.system() + " " + platform.machine()
|
|
72
|
+
return out
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def _cross_engine(method, source: str, selected: bool = False) -> str:
|
|
76
|
+
"""Whether the R and Python engines select byte-identical materials.
|
|
77
|
+
|
|
78
|
+
The deterministic methods are byte-identical; ``mahalanobis`` and ``optimal``
|
|
79
|
+
are the exception, because they use a covariance-matrix inverse and an
|
|
80
|
+
assignment solver whose last bits differ between the two linear-algebra
|
|
81
|
+
backends (see matching.py).
|
|
82
|
+
|
|
83
|
+
``selected`` distinguishes the two things an item table can now mean. A plain
|
|
84
|
+
table design does no selection, so there is nothing for the engines to agree on
|
|
85
|
+
and "n/a" is the whole story. A pair-keyed continuous design selects over that
|
|
86
|
+
table, and that selection was measured to be byte-identical, so answering "n/a"
|
|
87
|
+
there understated the guarantee on the one path where a reader most needs it.
|
|
88
|
+
"""
|
|
89
|
+
if source == "table" and not selected:
|
|
90
|
+
return "n/a (user-supplied items)"
|
|
91
|
+
if method in ("mahalanobis", "optimal"):
|
|
92
|
+
return "approximate (platform linear algebra)"
|
|
93
|
+
return "byte-identical"
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def _relational_record(design: dict, stimuli) -> dict | None:
|
|
97
|
+
"""The pair-keyed part of the record, or None for a design that is not pair-keyed.
|
|
98
|
+
|
|
99
|
+
Derived from the design and the realised stimuli rather than passed in, so both
|
|
100
|
+
engines compute it from the same two objects and cannot disagree about it.
|
|
101
|
+
|
|
102
|
+
Three of these fields answer questions the rest of the datasheet gets wrong for a
|
|
103
|
+
pair design. ``n_pairs`` is stated because ``items["n_total"]`` counts ROWS, which
|
|
104
|
+
is one per pair per condition, so a reader comparing it against the design's
|
|
105
|
+
``n_per_condition`` would find it doubled. The member lexicon is named and
|
|
106
|
+
checksummed because it is where every member-level control came from, and nothing
|
|
107
|
+
else in the record mentions it. ``materials_source`` names the item table. And
|
|
108
|
+
the member dimensions are separated from the relational ones because they are
|
|
109
|
+
different kinds of variable: ``target.frequency`` is a property of one word,
|
|
110
|
+
``pair.overlap`` is a property of the pair, and only the second is unavailable
|
|
111
|
+
from any word-level norm database. Mirrors datasheet.R.
|
|
112
|
+
"""
|
|
113
|
+
items_cfg = design.get("items") or {}
|
|
114
|
+
members = list(items_cfg.get("members") or [])
|
|
115
|
+
if not members:
|
|
116
|
+
return None
|
|
117
|
+
cols = list(stimuli.columns)
|
|
118
|
+
# The union over members, not the first member's alone. join_member_norms gives
|
|
119
|
+
# every member the same dimensions, so the sets coincide in anything the pipeline
|
|
120
|
+
# produced; taking the union means a hand-built frame cannot report an empty list
|
|
121
|
+
# merely because the first member happens to carry no prefixed column.
|
|
122
|
+
# startswith, not a regex: a member name is user-supplied and may contain a
|
|
123
|
+
# character a regex would read as syntax.
|
|
124
|
+
member_dims = set()
|
|
125
|
+
for m in members:
|
|
126
|
+
prefix = m + "."
|
|
127
|
+
member_dims.update(c[len(prefix):] for c in cols if c.startswith(prefix))
|
|
128
|
+
lexicon = items_cfg.get("lexicon") or design.get("lexicon")
|
|
129
|
+
return {
|
|
130
|
+
"members": members,
|
|
131
|
+
"n_pairs": int(stimuli["set"].nunique()),
|
|
132
|
+
"member_lexicon": lexicon,
|
|
133
|
+
"member_lexicon_sha256": sha256_file(lexicon),
|
|
134
|
+
"member_dimensions": sorted(member_dims, key=lambda s: s.encode("utf-8")),
|
|
135
|
+
"relational_dimensions": sorted((c for c in cols if c.startswith("pair.")),
|
|
136
|
+
key=lambda s: s.encode("utf-8")),
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
def _resolve_tolerance_k(design: dict, schema: dict) -> dict:
|
|
141
|
+
"""The tolerance windows as match_stimuli resolves them.
|
|
142
|
+
|
|
143
|
+
Schema defaults, overridden per dimension by the design, the same resolution
|
|
144
|
+
the matcher performs. The nearest-neighbour methods apply these windows; the
|
|
145
|
+
pairwise ``joint`` and ``optimal`` methods never consult them, which is why the
|
|
146
|
+
datasheet attaches this block only for the methods that do.
|
|
147
|
+
"""
|
|
148
|
+
tol_k = dict((schema.get("matching") or {}).get("tolerance_k") or {})
|
|
149
|
+
tol_k.update((design.get("matching") or {}).get("tolerance_k") or {})
|
|
150
|
+
return tol_k
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
def _controlled(design: dict, source: str) -> list:
|
|
154
|
+
# A supplied pool goes through the same matcher as a corpus, so it controls the same
|
|
155
|
+
# dimensions; only the origin of the candidate words differs.
|
|
156
|
+
if source in ("corpus", "pool"):
|
|
157
|
+
return list(design.get("match_on") or [])
|
|
158
|
+
if source == "generate":
|
|
159
|
+
return ["length"]
|
|
160
|
+
return []
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
def _analysis(design: dict, source: str) -> dict:
|
|
164
|
+
"""A suggested crossed mixed-model formula for the design.
|
|
165
|
+
|
|
166
|
+
Handing the user an items-crossed model guards against the
|
|
167
|
+
language-as-fixed-effect fallacy (Clark, 1973; Baayen et al., 2008): items are
|
|
168
|
+
a random sample of the language, so an analysis that treats them as fixed
|
|
169
|
+
over-generalises. The manipulated factor is within subjects (each participant
|
|
170
|
+
sees every condition) and, for corpus/lexical-decision designs, between items
|
|
171
|
+
(each item belongs to one condition), so items take a random intercept; in the
|
|
172
|
+
counterbalanced table paradigms the factor is within items too, so items also
|
|
173
|
+
take a random slope.
|
|
174
|
+
"""
|
|
175
|
+
cont = design.get("continuous")
|
|
176
|
+
if cont:
|
|
177
|
+
predictor = cont["predictor"]
|
|
178
|
+
controls = list(cont.get("controls") or [])
|
|
179
|
+
fixed = " + ".join([predictor] + controls)
|
|
180
|
+
note = ("The predictor is kept continuous and analysed by regression or a "
|
|
181
|
+
"mixed model rather than dichotomised (Kuperman, 2015; Liben-Nowell "
|
|
182
|
+
"et al., 2019); the controls enter as covariates. Crossed random "
|
|
183
|
+
"effects for subjects and items guard the language-as-fixed-effect "
|
|
184
|
+
"fallacy (Clark, 1973; Baayen et al., 2008); reduce the structure if "
|
|
185
|
+
"it does not converge (Matuschek et al., 2017).")
|
|
186
|
+
# A pair design's member-prefixed terms carry a dot, which R formulas accept
|
|
187
|
+
# but Patsy reads as syntax, so the Python analyst needs the quoting stated.
|
|
188
|
+
if any("." in t for t in [predictor] + controls):
|
|
189
|
+
note += (" Dotted dimension names are valid in R formulas but must be "
|
|
190
|
+
"quoted as Q(\"...\") in Patsy-style Python interfaces.")
|
|
191
|
+
return {
|
|
192
|
+
"response": "the trial outcome (e.g. reaction time or accuracy)",
|
|
193
|
+
"suggested_model": f"response ~ {fixed} + (1 + {predictor} | subject) + (1 | item)",
|
|
194
|
+
"note": note,
|
|
195
|
+
}
|
|
196
|
+
paradigm = design.get("paradigm", "factorial")
|
|
197
|
+
if source == "generate" or paradigm == "lexical_decision":
|
|
198
|
+
factor, item_re = "lexicality", "(1 | item)"
|
|
199
|
+
elif paradigm in ("priming", "self_paced_reading"):
|
|
200
|
+
factor, item_re = "condition", "(1 + condition | item)"
|
|
201
|
+
else:
|
|
202
|
+
factor, item_re = "condition", "(1 | item)"
|
|
203
|
+
return {
|
|
204
|
+
"response": "the trial outcome (e.g. reaction time or accuracy)",
|
|
205
|
+
"suggested_model": f"response ~ {factor} + (1 + {factor} | subject) + {item_re}",
|
|
206
|
+
"note": ("Crossed random effects for subjects and items guard against the "
|
|
207
|
+
"language-as-fixed-effect fallacy (Clark, 1973; Baayen et al., 2008). "
|
|
208
|
+
"Begin with this maximal structure (Barr et al., 2013) and reduce it "
|
|
209
|
+
"if the model does not converge (Matuschek et al., 2017). The formula "
|
|
210
|
+
"is lme4 syntax, for lme4 in R or pymer4 in Python; statsmodels "
|
|
211
|
+
"MixedLM cannot take it directly and needs the random effects "
|
|
212
|
+
"restated in its own arguments. The equivalence tests in the realised "
|
|
213
|
+
"control are post-selection diagnostics on deterministically selected "
|
|
214
|
+
"items, not inferential tests over a sample."),
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
def build_datasheet(design, schema, report, stimuli, source_path, artifacts,
|
|
219
|
+
seed, engine="python", candidate_pool=None, norms=None,
|
|
220
|
+
balance=None, blocks=None, design_path=None, schema_path=None,
|
|
221
|
+
selection_audit=None, neighbourhood_reference=None) -> dict:
|
|
222
|
+
"""Assemble the datasheet dictionary from the pipeline's objects.
|
|
223
|
+
|
|
224
|
+
``candidate_pool`` (optional) is a list of ``{"condition", "n_candidates"}``
|
|
225
|
+
recording how many items satisfied each condition's window before matching,
|
|
226
|
+
the size of the discretionary pool the selection drew from, reported so that
|
|
227
|
+
item-selection bias is auditable (Forster, 2000; Simmons et al., 2011).
|
|
228
|
+
|
|
229
|
+
``norms`` (optional) is a list of norm-table provenance records from the design's
|
|
230
|
+
``norms:`` block. Each names a file, its sha256, the join key and the per-column
|
|
231
|
+
coverage. Recorded because a norm table can supply the very variable a design
|
|
232
|
+
manipulates, so a record that omitted it would describe a selection over columns
|
|
233
|
+
of unstated origin.
|
|
234
|
+
|
|
235
|
+
``balance`` (optional) is the balance-optimiser report from ``balance_lists``.
|
|
236
|
+
Recorded because it decides which items each participant sees.
|
|
237
|
+
|
|
238
|
+
``design_path`` / ``schema_path`` (optional) are the design and schema files the
|
|
239
|
+
run read; when given, their sha256 checksums complete the reproducibility
|
|
240
|
+
record, because those two files decide everything the seed does not.
|
|
241
|
+
|
|
242
|
+
``selection_audit`` (optional) is the matcher's audit record; its
|
|
243
|
+
``window_relaxations`` entries are recorded because a relaxed window changes
|
|
244
|
+
what "matched" means for that condition.
|
|
245
|
+
|
|
246
|
+
``neighbourhood_reference`` (optional) records the lexicon the neighbourhood
|
|
247
|
+
dimensions were computed against (``{"source", "n_words", "sha256"}``),
|
|
248
|
+
verbatim.
|
|
249
|
+
"""
|
|
250
|
+
source = (design.get("items") or {}).get("source", "corpus")
|
|
251
|
+
is_continuous = _is_continuous(design)
|
|
252
|
+
controlled = _controlled(design, source)
|
|
253
|
+
relational = _relational_record(design, stimuli)
|
|
254
|
+
conditions = list(dict.fromkeys(stimuli["condition"]))
|
|
255
|
+
|
|
256
|
+
realised = []
|
|
257
|
+
if report is not None:
|
|
258
|
+
for _, r in report["comparisons"].iterrows():
|
|
259
|
+
if is_continuous:
|
|
260
|
+
realised.append({
|
|
261
|
+
"dimension": r["dimension"], "role": r["role"],
|
|
262
|
+
"pearson_r": _num(r.get("pearson_r")),
|
|
263
|
+
"predictor_span": _num(r.get("predictor_span")),
|
|
264
|
+
})
|
|
265
|
+
else:
|
|
266
|
+
realised.append({
|
|
267
|
+
"dimension": r["dimension"],
|
|
268
|
+
"role": "controlled" if r["dimension"] in controlled else "manipulated/free",
|
|
269
|
+
"cohens_d": _num(r["cohens_d"]),
|
|
270
|
+
"ci_low": _num(r.get("d_ci_low")), "ci_high": _num(r.get("d_ci_high")),
|
|
271
|
+
"var_ratio": _num(r.get("var_ratio")),
|
|
272
|
+
"tost_p": _num(r.get("tost_p")), "equivalent": _bool(r.get("equivalent")),
|
|
273
|
+
})
|
|
274
|
+
|
|
275
|
+
if is_continuous:
|
|
276
|
+
# The controls are banded by the same tolerance windows the matcher uses, so
|
|
277
|
+
# the record states them here too; without them the banding is unreproducible.
|
|
278
|
+
selection = {"method": "continuous even-spread (predictor spanned, controls banded)",
|
|
279
|
+
"predictor": design["continuous"]["predictor"],
|
|
280
|
+
"controls": list(design["continuous"].get("controls") or []),
|
|
281
|
+
"tolerance_k": _resolve_tolerance_k(design, schema)}
|
|
282
|
+
elif source in ("corpus", "pool"):
|
|
283
|
+
method = ((design.get("matching") or {}).get("method")
|
|
284
|
+
or (schema.get("matching") or {}).get("method")
|
|
285
|
+
or "standardised_euclidean")
|
|
286
|
+
selection = {"method": method, "match_on": controlled}
|
|
287
|
+
if method in ("joint", "optimal"):
|
|
288
|
+
# The pairwise methods rank whole pairs and never consult the tolerance
|
|
289
|
+
# windows; recording tolerance_k here would claim a filter that was not
|
|
290
|
+
# applied. They get the cap they do apply instead, with a per-condition
|
|
291
|
+
# verdict on whether it fired.
|
|
292
|
+
selection["candidate_cap"] = {
|
|
293
|
+
"cap": int(PAIRWISE_CAP),
|
|
294
|
+
"applied": {c["condition"]: bool(c["n_candidates"] > PAIRWISE_CAP)
|
|
295
|
+
for c in (candidate_pool or [])
|
|
296
|
+
if c.get("condition") is not None
|
|
297
|
+
and c.get("n_candidates") is not None},
|
|
298
|
+
}
|
|
299
|
+
else:
|
|
300
|
+
selection["tolerance_k"] = _resolve_tolerance_k(design, schema)
|
|
301
|
+
elif source == "generate":
|
|
302
|
+
gen_method = ((design.get("items") or {}).get("generation") or {}).get(
|
|
303
|
+
"method", "letter_substitution")
|
|
304
|
+
selection = {"method": _GENERATION_LABELS.get(
|
|
305
|
+
gen_method, f"{gen_method} (deterministic pseudowords)"),
|
|
306
|
+
"generation_method": gen_method,
|
|
307
|
+
"matched_on": ["length"]}
|
|
308
|
+
else:
|
|
309
|
+
selection = {"method": "item table (user-supplied)"}
|
|
310
|
+
if candidate_pool is not None and source in ("corpus", "pool", "generate"):
|
|
311
|
+
selection["candidate_pool"] = candidate_pool
|
|
312
|
+
# A pair-keyed continuous design does select, over the item table.
|
|
313
|
+
selection["cross_engine"] = _cross_engine(
|
|
314
|
+
selection.get("method"), source, selected=is_continuous and relational is not None)
|
|
315
|
+
# A relaxed window changes what "matched" means for that condition, so the
|
|
316
|
+
# matcher's audit trail belongs in the record, not only in the run narration.
|
|
317
|
+
# Integers only, so both engines serialise the counts identically.
|
|
318
|
+
relaxations = (selection_audit or {}).get("window_relaxations") or []
|
|
319
|
+
if relaxations:
|
|
320
|
+
selection["window_relaxations"] = [
|
|
321
|
+
{"condition": r["condition"],
|
|
322
|
+
"n_within_tolerance": int(r["n_within_tolerance"]),
|
|
323
|
+
"n_needed": int(r["n_needed"])} for r in relaxations]
|
|
324
|
+
if neighbourhood_reference is not None:
|
|
325
|
+
selection["neighbourhood_reference"] = neighbourhood_reference
|
|
326
|
+
|
|
327
|
+
if source in ("corpus", "generate"):
|
|
328
|
+
provenance = ("wordfreq (Speer, 2022), data CC BY-SA 4.0; full corpus licence "
|
|
329
|
+
"and citation at https://github.com/pablobernabeu/lexsync/blob/"
|
|
330
|
+
"main/corpora/ATTRIBUTION.md")
|
|
331
|
+
elif source == "pool":
|
|
332
|
+
provenance = "user-supplied word pool, matched by lexsync"
|
|
333
|
+
else:
|
|
334
|
+
provenance = "user-supplied item table"
|
|
335
|
+
materials_source = {
|
|
336
|
+
"type": source, "path": _posix(source_path), "sha256": sha256_file(source_path),
|
|
337
|
+
"provenance": provenance,
|
|
338
|
+
}
|
|
339
|
+
# A supplied pool usually draws its dimensions from a corpus lexicon, and that
|
|
340
|
+
# lexicon is where every matched value came from, so it is named and checksummed
|
|
341
|
+
# here: `path` above records only the word list itself.
|
|
342
|
+
if source == "pool":
|
|
343
|
+
dim_lex = (design.get("items") or {}).get("lexicon") or design.get("lexicon")
|
|
344
|
+
materials_source["dimensions_from"] = (
|
|
345
|
+
dim_lex if dim_lex else "the supplied pool's own columns (no lexicon given)")
|
|
346
|
+
if dim_lex:
|
|
347
|
+
materials_source["dimensions_sha256"] = sha256_file(dim_lex)
|
|
348
|
+
# Added only when present, so a design with no `norms:` block gets no key at all
|
|
349
|
+
# rather than a "norms": null that every datasheet would then carry. Matches the R
|
|
350
|
+
# engine, where assigning NULL to a list element removes it.
|
|
351
|
+
if norms:
|
|
352
|
+
materials_source["norms"] = norms
|
|
353
|
+
|
|
354
|
+
# A corpus design draws on every schema dimension, and so does a pair-keyed
|
|
355
|
+
# design: every lexicon dimension is joined onto each member. A generate or plain
|
|
356
|
+
# table design reports only the ones it controlled, so the record does not claim
|
|
357
|
+
# dimensions that played no part in the selection.
|
|
358
|
+
all_dims = source in ("corpus", "pool") or relational is not None
|
|
359
|
+
# `or {}`, not a default argument, for the reason load_lexicon carries the same
|
|
360
|
+
# guard: an empty `dimensions:` key parses to None here, which is not iterable,
|
|
361
|
+
# while the R twin's schema$dimensions[keep] returns NULL and the record simply
|
|
362
|
+
# carries no dimensions.
|
|
363
|
+
schema_dims = schema.get("dimensions") or {}
|
|
364
|
+
dims = {d: schema_dims[d] for d in schema_dims if all_dims or d in controlled}
|
|
365
|
+
|
|
366
|
+
# The balance report is added only when the optimiser ran, for the same reason the
|
|
367
|
+
# norms record is: a key that is null on every design that does not use the feature
|
|
368
|
+
# is noise in a research artefact.
|
|
369
|
+
counterbalancing = {
|
|
370
|
+
"recipe": "latin_square_target" if source == "table" else "factorial",
|
|
371
|
+
"lists": (design.get("counterbalance") or {}).get("lists", 1),
|
|
372
|
+
}
|
|
373
|
+
if balance:
|
|
374
|
+
counterbalancing["optimise"] = balance
|
|
375
|
+
# Practice and filler trials change what a participant sees but not what is
|
|
376
|
+
# analysed, so the record has to state both counts: a reader comparing the stimuli
|
|
377
|
+
# file against the experiment would otherwise find them a different length with no
|
|
378
|
+
# explanation.
|
|
379
|
+
if blocks:
|
|
380
|
+
counterbalancing["blocks"] = blocks
|
|
381
|
+
|
|
382
|
+
# The equivalence settings the report's TOST verdicts were computed against,
|
|
383
|
+
# recorded so the Methods prose can state the bound it actually ran with.
|
|
384
|
+
equivalence = {"bound_d": (schema.get("equivalence") or {}).get("bound_d", 0.5),
|
|
385
|
+
"alpha": (schema.get("equivalence") or {}).get("alpha", 0.05)}
|
|
386
|
+
|
|
387
|
+
reproducibility = {"seed": seed, "versions": _versions(engine)}
|
|
388
|
+
# The design and schema decide everything the seed does not, so their checksums
|
|
389
|
+
# complete the reproducibility record when the pipeline names them.
|
|
390
|
+
if design_path is not None:
|
|
391
|
+
reproducibility["design_sha256"] = sha256_file(design_path)
|
|
392
|
+
if schema_path is not None:
|
|
393
|
+
reproducibility["schema_sha256"] = sha256_file(schema_path)
|
|
394
|
+
|
|
395
|
+
return {
|
|
396
|
+
"lexsync_datasheet_version": DATASHEET_VERSION,
|
|
397
|
+
"design": {
|
|
398
|
+
"name": design["name"], "language": design["language"],
|
|
399
|
+
"paradigm": design.get("paradigm", "factorial"), "source": source,
|
|
400
|
+
"description": design.get("description"),
|
|
401
|
+
"n_per_condition": design.get("n_per_condition") or design.get("n_per_cell"),
|
|
402
|
+
},
|
|
403
|
+
"materials_source": materials_source,
|
|
404
|
+
"dimensions": dims,
|
|
405
|
+
"selection": selection,
|
|
406
|
+
"relational": relational,
|
|
407
|
+
"analysis": _analysis(design, source),
|
|
408
|
+
"equivalence": equivalence,
|
|
409
|
+
"realised_control": realised,
|
|
410
|
+
"counterbalancing": counterbalancing,
|
|
411
|
+
"resampling": ({"n_sets": (design.get("resample") or {}).get("n_sets"),
|
|
412
|
+
"disjoint": True} if design.get("resample") else None),
|
|
413
|
+
"items": {
|
|
414
|
+
"n_total": int(len(stimuli)), "n_conditions": len(conditions),
|
|
415
|
+
"conditions": conditions,
|
|
416
|
+
"stimuli_file": _posix(artifacts.get("stimuli")),
|
|
417
|
+
"stimuli_sha256": sha256_file(artifacts.get("stimuli")),
|
|
418
|
+
},
|
|
419
|
+
"reproducibility": reproducibility,
|
|
420
|
+
"artifacts": [{"file": _posix(p), "sha256": sha256_file(p)}
|
|
421
|
+
for p in _artifact_paths(artifacts) if p],
|
|
422
|
+
}
|
|
423
|
+
|
|
424
|
+
|
|
425
|
+
def _posix(path):
|
|
426
|
+
"""Record a path in POSIX form, as R's file.path() already produces.
|
|
427
|
+
|
|
428
|
+
os.path.join gives backslashes on Windows, which would make the datasheet, a
|
|
429
|
+
record meant to travel with the materials and be read anywhere, describe the
|
|
430
|
+
machine that happened to build it, and disagree with the R engine's record of the
|
|
431
|
+
same file.
|
|
432
|
+
"""
|
|
433
|
+
return path.replace("\\", "/") if isinstance(path, str) else path
|
|
434
|
+
|
|
435
|
+
|
|
436
|
+
def _artifact_paths(artifacts: dict) -> list:
|
|
437
|
+
paths = [artifacts.get(k) for k in ("stimuli", "descriptives", "comparisons")]
|
|
438
|
+
exps = artifacts.get("experiments") or {}
|
|
439
|
+
paths += list(exps.values())
|
|
440
|
+
return paths
|
|
441
|
+
|
|
442
|
+
|
|
443
|
+
def _num(v):
|
|
444
|
+
try:
|
|
445
|
+
return None if v is None or v != v else _round_dp(float(v), 4)
|
|
446
|
+
except (TypeError, ValueError):
|
|
447
|
+
return None
|
|
448
|
+
|
|
449
|
+
|
|
450
|
+
def _bool(v):
|
|
451
|
+
return None if v is None or (isinstance(v, float) and v != v) else bool(v)
|
|
452
|
+
|
|
453
|
+
|
|
454
|
+
def _norms_note(ds: dict) -> str:
|
|
455
|
+
"""The norm tables named in the Methods prose.
|
|
456
|
+
|
|
457
|
+
Basenames only: the full paths and checksums are in the datasheet, and a paper's
|
|
458
|
+
Methods section wants the source, not the directory it happened to sit in on one
|
|
459
|
+
machine. Mirrors .norms_note in datasheet.R.
|
|
460
|
+
"""
|
|
461
|
+
norms = (ds.get("materials_source") or {}).get("norms")
|
|
462
|
+
if not norms:
|
|
463
|
+
return ""
|
|
464
|
+
files = ", ".join(str(t["path"]).replace("\\", "/").rsplit("/", 1)[-1] for t in norms)
|
|
465
|
+
return (" Norm dimensions were joined from %s, whose checksums and per-column "
|
|
466
|
+
"coverage are recorded in the datasheet." % files)
|
|
467
|
+
|
|
468
|
+
|
|
469
|
+
def methods_paragraph(ds: dict) -> str:
|
|
470
|
+
d = ds["design"]
|
|
471
|
+
src = ds["materials_source"]["type"]
|
|
472
|
+
n = d["n_per_condition"]
|
|
473
|
+
lang = d["language"].capitalize()
|
|
474
|
+
sel = ds.get("selection") or {}
|
|
475
|
+
# What was selected. A pair design's unit is the pair, and its `n_per_condition`
|
|
476
|
+
# counts pairs, so calling them "items" would misreport the size of the materials
|
|
477
|
+
# by a factor of the number of conditions.
|
|
478
|
+
rel = ds.get("relational")
|
|
479
|
+
unit = "items" if not rel else "-".join(rel["members"]) + " pairs"
|
|
480
|
+
if "predictor" in sel:
|
|
481
|
+
predictor = sel["predictor"]
|
|
482
|
+
controls = ", ".join(sel.get("controls") or []) or "the control dimensions"
|
|
483
|
+
rc = ds.get("realised_control") or []
|
|
484
|
+
span = next((r.get("predictor_span") for r in rc if r.get("predictor_span") is not None), None)
|
|
485
|
+
rs = [abs(r["pearson_r"]) for r in rc
|
|
486
|
+
if r.get("pearson_r") is not None and r["pearson_r"] == r["pearson_r"]]
|
|
487
|
+
span_str = f" (a span of {span:.2f})" if span is not None else ""
|
|
488
|
+
# Report |r| at 3 dp (its stored precision) so the text is identical across
|
|
489
|
+
# engines; a 2-dp format of, say, 0.165 rounds to 0.17 in Python and 0.16 in R.
|
|
490
|
+
corr_str = (f", and the largest predictor-control correlation was |r| = {max(rs):.3f}"
|
|
491
|
+
if rs else "")
|
|
492
|
+
cb = ds["counterbalancing"]
|
|
493
|
+
recipe_label = {"latin_square_target": "a Latin-square rotation",
|
|
494
|
+
"factorial": "a factorial split"}.get(cb["recipe"], cb["recipe"])
|
|
495
|
+
return (f"{n} {lang} {unit} were selected to span {predictor}{span_str} continuously "
|
|
496
|
+
f"while holding {controls} near-constant{corr_str}, for analysis by regression "
|
|
497
|
+
f"or a mixed model rather than a between-condition contrast (Kuperman, 2015; "
|
|
498
|
+
f"Liben-Nowell et al., 2019).{_norms_note(ds)} Materials were counterbalanced "
|
|
499
|
+
f"into {cb['lists']} list(s) ({recipe_label}) and generated for PsychoPy, "
|
|
500
|
+
f"OpenSesame and jsPsych. The selection is deterministic and reproducible "
|
|
501
|
+
f"(seed {ds['reproducibility']['seed']}; lexsync "
|
|
502
|
+
f"{ds['reproducibility']['versions']['lexsync']}).")
|
|
503
|
+
if src == "corpus":
|
|
504
|
+
ctrl = ", ".join(ds["selection"]["match_on"]) or "the control dimensions"
|
|
505
|
+
lead = (f"{n} items per condition were selected from the {lang} lexicon "
|
|
506
|
+
f"({ds['materials_source']['provenance']}) and matched item by item on "
|
|
507
|
+
f"{ctrl} using lexsync's {ds['selection']['method']} matcher")
|
|
508
|
+
elif src == "pool":
|
|
509
|
+
# A supplied pool is matched exactly as a corpus is; what differs, and what the
|
|
510
|
+
# Methods section has to say, is that the candidate words were chosen by the
|
|
511
|
+
# researcher rather than drawn from the whole lexicon.
|
|
512
|
+
ctrl = ", ".join(ds["selection"]["match_on"]) or "the control dimensions"
|
|
513
|
+
lead = (f"{n} {lang} items per condition were selected from a supplied candidate "
|
|
514
|
+
f"pool and matched item by item on {ctrl} using lexsync's "
|
|
515
|
+
f"{ds['selection']['method']} matcher, with the matched dimensions taken "
|
|
516
|
+
f"from {ds['materials_source']['dimensions_from']}")
|
|
517
|
+
elif src == "generate":
|
|
518
|
+
lead = (f"{n} real {lang} words and {n} length-matched pseudowords "
|
|
519
|
+
f"(generated by {ds['selection']['method']}) were assembled for a "
|
|
520
|
+
f"lexical-decision contrast")
|
|
521
|
+
else:
|
|
522
|
+
lead = (f"{ds['items']['n_total'] // max(1, ds['items']['n_conditions'])} items "
|
|
523
|
+
f"were drawn from an item table for a {d['paradigm']} design ({lang})")
|
|
524
|
+
ctrl_rows = [r for r in ds["realised_control"] if r["role"] == "controlled"]
|
|
525
|
+
defined = [r for r in ctrl_rows if r["cohens_d"] is not None]
|
|
526
|
+
control = ""
|
|
527
|
+
if ctrl_rows:
|
|
528
|
+
# Affirmative only when the stored verdicts support it: every controlled row
|
|
529
|
+
# has a defined d and every one of them passed the TOST. An undefined d
|
|
530
|
+
# (constant dimensions at different constants) is the worst possible failure
|
|
531
|
+
# of the matching, not an excludable row.
|
|
532
|
+
all_equivalent = (len(defined) == len(ctrl_rows)
|
|
533
|
+
and all(r.get("equivalent") is True for r in defined))
|
|
534
|
+
if all_equivalent and defined:
|
|
535
|
+
worst = max(defined, key=lambda r: abs(r["cohens_d"]))
|
|
536
|
+
control = (f". The realised control was close. The largest standardised difference on "
|
|
537
|
+
f"any matched dimension was {worst['cohens_d']:.2f} "
|
|
538
|
+
f"(90% CI [{worst['ci_low']:.2f}, {worst['ci_high']:.2f}]), within the "
|
|
539
|
+
f"{ds['equivalence']['bound_d']}-SD equivalence bound")
|
|
540
|
+
else:
|
|
541
|
+
control = (". Equivalence was not confirmed on every matched dimension; "
|
|
542
|
+
"the per-dimension differences are reported in the "
|
|
543
|
+
"realised-control table")
|
|
544
|
+
rs = ds.get("resampling")
|
|
545
|
+
resamp = (f". {rs['n_sets']} disjoint matched item sets were drawn, so items can be "
|
|
546
|
+
f"treated as a random factor" if rs else "")
|
|
547
|
+
cb = ds["counterbalancing"]
|
|
548
|
+
recipe_label = {"latin_square_target": "a Latin-square rotation",
|
|
549
|
+
"factorial": "a factorial split"}.get(cb["recipe"], cb["recipe"])
|
|
550
|
+
tail = (resamp + f". Materials were counterbalanced into {cb['lists']} list(s) "
|
|
551
|
+
f"({recipe_label}) and generated for PsychoPy, OpenSesame and jsPsych. The "
|
|
552
|
+
f"selection is deterministic and reproducible (seed "
|
|
553
|
+
f"{ds['reproducibility']['seed']}; lexsync "
|
|
554
|
+
f"{ds['reproducibility']['versions']['lexsync']}).")
|
|
555
|
+
cp = (ds.get("selection") or {}).get("candidate_pool")
|
|
556
|
+
pool_note = ""
|
|
557
|
+
if cp:
|
|
558
|
+
sizes = [c["n_candidates"] for c in cp if c.get("n_candidates") is not None]
|
|
559
|
+
if sizes:
|
|
560
|
+
pool_note = (f". The smallest condition was selected from {min(sizes)} "
|
|
561
|
+
"eligible candidates, and the selection was deterministic and "
|
|
562
|
+
"blind to any outcome measure")
|
|
563
|
+
cap_rec = (ds.get("selection") or {}).get("candidate_cap")
|
|
564
|
+
cap_note = ""
|
|
565
|
+
if cap_rec and any(cap_rec.get("applied", {}).values()):
|
|
566
|
+
cap_note = (f". Each candidate pool exceeding the pairwise cap was reduced to "
|
|
567
|
+
f"the {int(cap_rec['cap'])} candidates nearest the other "
|
|
568
|
+
f"condition's centroid before pairing")
|
|
569
|
+
ce_note = ""
|
|
570
|
+
if str((ds.get("selection") or {}).get("cross_engine", "")).startswith("approximate"):
|
|
571
|
+
ce_note = (". This design's matching method uses a covariance inverse or an "
|
|
572
|
+
"assignment solver, so the R and Python engines select equivalent "
|
|
573
|
+
"but not byte-identical materials")
|
|
574
|
+
bal = (ds.get("counterbalancing") or {}).get("optimise")
|
|
575
|
+
bal_note = "" if not bal else (
|
|
576
|
+
". Item sets were assigned to lists so as to equate the lists on %s rather than "
|
|
577
|
+
"by an arbitrary deal, by a deterministic integer search (%d swap(s); imbalance "
|
|
578
|
+
"reduced from %d to %d)"
|
|
579
|
+
% (", ".join(bal["dimensions"]), bal["n_swaps"],
|
|
580
|
+
bal["cost_before"], bal["cost_after"]))
|
|
581
|
+
return lead + control + pool_note + cap_note + ce_note + bal_note + tail + _norms_note(ds)
|
|
582
|
+
|
|
583
|
+
|
|
584
|
+
def prereg_template(ds: dict) -> str:
|
|
585
|
+
return (
|
|
586
|
+
"## Pre-registration template\n\n"
|
|
587
|
+
"*Auto-generated by lexsync. The Materials section is filled from the datasheet; "
|
|
588
|
+
"complete the remaining sections before data collection.*\n\n"
|
|
589
|
+
"### Study information\n- Title:\n- Authors:\n- Research questions:\n\n"
|
|
590
|
+
"### Hypotheses\n- H1:\n\n"
|
|
591
|
+
"### Design\n- Manipulated variable(s):\n- Measured variable(s):\n"
|
|
592
|
+
f"- Paradigm: {ds['design']['paradigm']}\n\n"
|
|
593
|
+
"### Materials (from the lexsync datasheet)\n" + methods_paragraph(ds) + "\n\n"
|
|
594
|
+
"### Sampling plan\n- Sample size and justification:\n- Stopping rule:\n\n"
|
|
595
|
+
"### Analysis plan\n- Statistical model: "
|
|
596
|
+
+ ds["analysis"]["suggested_model"] + "\n (" + ds["analysis"]["note"] + ")\n"
|
|
597
|
+
"- Inference criteria:\n"
|
|
598
|
+
"- Treatment of items (e.g. items as a random factor):\n"
|
|
599
|
+
)
|
|
600
|
+
|
|
601
|
+
|
|
602
|
+
def render_datasheet_md(ds: dict) -> str:
|
|
603
|
+
d = ds["design"]
|
|
604
|
+
lines = [f"# Materials datasheet — {d['name']} ({d['language']})", "",
|
|
605
|
+
f"*lexsync datasheet v{ds['lexsync_datasheet_version']}; "
|
|
606
|
+
f"{ds['reproducibility']['versions']['engine']} engine.*", "",
|
|
607
|
+
"## Provenance", "",
|
|
608
|
+
f"- **Paradigm:** {d['paradigm']} | **Item source:** {d['source']}",
|
|
609
|
+
f"- **Description:** {d.get('description') or '--'}",
|
|
610
|
+
f"- **Materials source:** `{ds['materials_source']['path']}` "
|
|
611
|
+
f"(sha256 `{(ds['materials_source']['sha256'] or '')[:16]}…`)"]
|
|
612
|
+
# Where a supplied pool's matched values came from. Without this the record names
|
|
613
|
+
# only the word list, and the numbers every control rests on have no stated origin.
|
|
614
|
+
# Appended here rather than inserted at an index, so the position stays right if a
|
|
615
|
+
# line above it is ever added or removed.
|
|
616
|
+
dim_from = (ds.get("materials_source") or {}).get("dimensions_from")
|
|
617
|
+
if dim_from:
|
|
618
|
+
dim_sha = (ds.get("materials_source") or {}).get("dimensions_sha256")
|
|
619
|
+
lines.append("- **Dimensions from:** `%s`%s"
|
|
620
|
+
% (dim_from, "" if not dim_sha else " (sha256 `%s…`)" % dim_sha[:16]))
|
|
621
|
+
lines += [
|
|
622
|
+
f"- **Selection:** {ds['selection']['method']}",
|
|
623
|
+
f"- **Cross-engine determinism:** {ds['selection'].get('cross_engine', 'byte-identical')}",
|
|
624
|
+
f"- **Counterbalancing:** {ds['counterbalancing']['recipe']}, "
|
|
625
|
+
f"{ds['counterbalancing']['lists']} list(s)",
|
|
626
|
+
f"- **Items:** {ds['items']['n_total']} rows across "
|
|
627
|
+
f"{ds['items']['n_conditions']} conditions "
|
|
628
|
+
f"({', '.join(ds['items']['conditions'])})",
|
|
629
|
+
f"- **Seed:** {ds['reproducibility']['seed']} | **Versions:** "
|
|
630
|
+
+ ", ".join(f"{k} {v}" for k, v in ds["reproducibility"]["versions"].items()), ""]
|
|
631
|
+
# Norm tables, with their checksums and coverage. A dimension covering only part of
|
|
632
|
+
# the lexicon matters to a reader: the uncovered rows carry NaN and are dropped by
|
|
633
|
+
# the tolerance windows, so coverage is part of how the pool was defined.
|
|
634
|
+
nrm = (ds.get("materials_source") or {}).get("norms")
|
|
635
|
+
if nrm:
|
|
636
|
+
lines += ["## Joined norms", "",
|
|
637
|
+
"| File | Key | Column | Coverage | sha256 |", "|---|---|---|---|---|"]
|
|
638
|
+
for t in nrm:
|
|
639
|
+
for cl in t["columns"]:
|
|
640
|
+
lines.append(f"| `{t['path']}` | {t['on']} | {cl['column']} | "
|
|
641
|
+
f"{cl['n_matched']} / {cl['n_total']} | "
|
|
642
|
+
f"`{(t.get('sha256') or '')[:16]}…` |")
|
|
643
|
+
lines.append("")
|
|
644
|
+
# Balance-aware list assignment. Reported because it decides which items each
|
|
645
|
+
# participant sees, and the before/after costs are what make the claim checkable
|
|
646
|
+
# rather than a bare assertion that the lists are balanced.
|
|
647
|
+
bal = (ds.get("counterbalancing") or {}).get("optimise")
|
|
648
|
+
if bal:
|
|
649
|
+
lines += ["## Balanced list assignment", "",
|
|
650
|
+
"- **Balanced on:** " + ", ".join(bal["dimensions"]),
|
|
651
|
+
"- **Imbalance:** %d before, %d after, in %d swap(s)"
|
|
652
|
+
% (bal["cost_before"], bal["cost_after"], bal["n_swaps"]),
|
|
653
|
+
"- **Cost unit:** " + bal["cost_unit"],
|
|
654
|
+
("- The search stopped at its pass bound rather than at a local "
|
|
655
|
+
"optimum, so a higher `counterbalance.max_passes` may balance the "
|
|
656
|
+
"lists further.") if bal.get("max_passes_reached") else
|
|
657
|
+
("- The search ran to a local optimum: no single exchange of two item "
|
|
658
|
+
"sets between lists would reduce the imbalance further."),
|
|
659
|
+
("- The search is a deterministic integer descent with a keyed-hash "
|
|
660
|
+
"tie-break, so it uses no random number generator and the R and "
|
|
661
|
+
"Python engines produce the same assignment."), ""]
|
|
662
|
+
rel = ds.get("relational")
|
|
663
|
+
if rel:
|
|
664
|
+
lines += ["## Pair-keyed items", "",
|
|
665
|
+
f"- **Members:** {', '.join(rel['members'])} | "
|
|
666
|
+
f"**Pairs:** {rel['n_pairs']}",
|
|
667
|
+
f"- **Member lexicon:** `{rel['member_lexicon']}` "
|
|
668
|
+
f"(sha256 `{(rel.get('member_lexicon_sha256') or '')[:16]}…`)",
|
|
669
|
+
"- **Member-level dimensions** (one word): "
|
|
670
|
+
+ ", ".join(rel["member_dimensions"]),
|
|
671
|
+
"- **Relational dimensions** (the pair): "
|
|
672
|
+
+ ", ".join(rel["relational_dimensions"]),
|
|
673
|
+
"- Selection ran on one row per pair and the result was re-expanded, so "
|
|
674
|
+
"every condition row of every chosen pair is present and the Latin-square "
|
|
675
|
+
"rotation is complete.", ""]
|
|
676
|
+
cp = (ds.get("selection") or {}).get("candidate_pool")
|
|
677
|
+
if cp:
|
|
678
|
+
parts = ", ".join(f"{c['condition']}: {c['n_candidates']}" for c in cp
|
|
679
|
+
if "condition" in c and "n_candidates" in c)
|
|
680
|
+
lines += ["## Selection transparency", "",
|
|
681
|
+
"- **Candidate pool** (items satisfying each condition's window before "
|
|
682
|
+
f"matching): {parts}.",
|
|
683
|
+
"- Selection is deterministic given the seed and blind to any outcome "
|
|
684
|
+
"measure, so it is reproducible and free of item-selection bias "
|
|
685
|
+
"(Forster, 2000; Simmons et al., 2011).", ""]
|
|
686
|
+
if ds["realised_control"] and "predictor" in (ds.get("selection") or {}):
|
|
687
|
+
lines += ["## Realised control (continuous predictor)", "",
|
|
688
|
+
"| Dimension | Role | r with predictor | Predictor span |",
|
|
689
|
+
"|---|---|---|---|"]
|
|
690
|
+
for r in ds["realised_control"]:
|
|
691
|
+
# "--", not an em dash: the R renderer's placeholder, kept identical.
|
|
692
|
+
rr = "--" if r.get("pearson_r") is None else f"{r['pearson_r']:.3f}"
|
|
693
|
+
sp = "--" if r.get("predictor_span") is None else f"{r['predictor_span']:.3f}"
|
|
694
|
+
lines.append(f"| {r['dimension']} | {r['role']} | {rr} | {sp} |")
|
|
695
|
+
lines.append("")
|
|
696
|
+
elif ds["realised_control"]:
|
|
697
|
+
lines += ["## Realised control", "",
|
|
698
|
+
"| Dimension | Role | Cohen's d | 90% CI | Var ratio | TOST p | Equivalent |",
|
|
699
|
+
"|---|---|---|---|---|---|---|"]
|
|
700
|
+
for r in ds["realised_control"]:
|
|
701
|
+
# "--", not an em dash: the R renderer's placeholder, kept identical.
|
|
702
|
+
# An undefined d (unequal constants) reaches every one of these cells.
|
|
703
|
+
ci = (f"[{r['ci_low']:.2f}, {r['ci_high']:.2f}]"
|
|
704
|
+
if r["ci_low"] is not None else "--")
|
|
705
|
+
d_str = "--" if r["cohens_d"] is None else f"{r['cohens_d']:.2f}"
|
|
706
|
+
vr = "--" if r.get("var_ratio") is None else f"{r['var_ratio']:.2f}"
|
|
707
|
+
lines.append(f"| {r['dimension']} | {r['role']} | {d_str} | {ci} | {vr} | "
|
|
708
|
+
f"{r['tost_p']} | {r['equivalent']} |")
|
|
709
|
+
lines.append("")
|
|
710
|
+
a = ds.get("analysis")
|
|
711
|
+
if a:
|
|
712
|
+
lines += ["## Suggested analysis", "",
|
|
713
|
+
f"- **Model:** `{a['suggested_model']}` — where the response is "
|
|
714
|
+
f"{a['response']}.",
|
|
715
|
+
f"- {a['note']}", ""]
|
|
716
|
+
lines += ["## Methods paragraph", "", methods_paragraph(ds), "", prereg_template(ds)]
|
|
717
|
+
return "\n".join(lines)
|
|
718
|
+
|
|
719
|
+
|
|
720
|
+
def _at_15_significant_digits(o):
|
|
721
|
+
"""Round every float in the record to 15 significant digits.
|
|
722
|
+
|
|
723
|
+
The R engine writes this JSON with jsonlite, whose numeric precision is a single
|
|
724
|
+
setting for the whole document; 15 significant digits (``digits = NA``) is R's full
|
|
725
|
+
display precision and the closest common ground. Without this the two engines'
|
|
726
|
+
records disagreed on any value that had not already been rounded on the way in.
|
|
727
|
+
A `tolerance_k` of 1/9 was written to 16 digits here and 15 there, so a reader
|
|
728
|
+
diffing the two records saw a difference that meant nothing.
|
|
729
|
+
|
|
730
|
+
Fifteen digits is ample for a provenance record: every value in it either came from
|
|
731
|
+
a human-written design file or was deliberately rounded to four places. The design
|
|
732
|
+
file remains the authoritative source for an exact re-run.
|
|
733
|
+
"""
|
|
734
|
+
if isinstance(o, float):
|
|
735
|
+
return float("%.15g" % o)
|
|
736
|
+
if isinstance(o, dict):
|
|
737
|
+
return {k: _at_15_significant_digits(v) for k, v in o.items()}
|
|
738
|
+
if isinstance(o, list):
|
|
739
|
+
return [_at_15_significant_digits(v) for v in o]
|
|
740
|
+
return o
|
|
741
|
+
|
|
742
|
+
|
|
743
|
+
def write_datasheet(ds: dict, json_path: str, md_path: str) -> tuple:
|
|
744
|
+
import os
|
|
745
|
+
os.makedirs(os.path.dirname(json_path) or ".", exist_ok=True)
|
|
746
|
+
with open(json_path, "w", encoding="utf-8", newline="\n") as handle:
|
|
747
|
+
json.dump(_at_15_significant_digits(ds), handle, indent=2, ensure_ascii=False,
|
|
748
|
+
sort_keys=True)
|
|
749
|
+
handle.write("\n")
|
|
750
|
+
with open(md_path, "w", encoding="utf-8", newline="\n") as handle:
|
|
751
|
+
handle.write(render_datasheet_md(ds) + "\n")
|
|
752
|
+
return json_path, md_path
|