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/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