lexsync 0.1.1__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.
Files changed (72) hide show
  1. lexsync-0.1.1/.gitignore +88 -0
  2. lexsync-0.1.1/LICENSE +33 -0
  3. lexsync-0.1.1/LICENSE.note +108 -0
  4. lexsync-0.1.1/PKG-INFO +234 -0
  5. lexsync-0.1.1/README.md +188 -0
  6. lexsync-0.1.1/pyproject.toml +192 -0
  7. lexsync-0.1.1/src/lexsync/__init__.py +53 -0
  8. lexsync-0.1.1/src/lexsync/__main__.py +5 -0
  9. lexsync-0.1.1/src/lexsync/blocks.py +149 -0
  10. lexsync-0.1.1/src/lexsync/cli.py +85 -0
  11. lexsync-0.1.1/src/lexsync/corpora.py +331 -0
  12. lexsync-0.1.1/src/lexsync/counterbalancing.py +399 -0
  13. lexsync-0.1.1/src/lexsync/data/en_example.csv +3001 -0
  14. lexsync-0.1.1/src/lexsync/data/es_example.csv +3001 -0
  15. lexsync-0.1.1/src/lexsync/data/registry.yaml +149 -0
  16. lexsync-0.1.1/src/lexsync/data/schema.yaml +193 -0
  17. lexsync-0.1.1/src/lexsync/data/zh_example.csv +3001 -0
  18. lexsync-0.1.1/src/lexsync/datasheet.py +752 -0
  19. lexsync-0.1.1/src/lexsync/generation.py +280 -0
  20. lexsync-0.1.1/src/lexsync/io_utils.py +609 -0
  21. lexsync-0.1.1/src/lexsync/logging.py +88 -0
  22. lexsync-0.1.1/src/lexsync/matching.py +614 -0
  23. lexsync-0.1.1/src/lexsync/pairs.py +177 -0
  24. lexsync-0.1.1/src/lexsync/paradigms.py +163 -0
  25. lexsync-0.1.1/src/lexsync/py.typed +0 -0
  26. lexsync-0.1.1/src/lexsync/querying.py +481 -0
  27. lexsync-0.1.1/src/lexsync/run_pipeline.py +425 -0
  28. lexsync-0.1.1/src/lexsync/scripting.py +845 -0
  29. lexsync-0.1.1/src/lexsync/templates/jspsych/experiment_template.html +223 -0
  30. lexsync-0.1.1/src/lexsync/templates/opensesame/README.md +36 -0
  31. lexsync-0.1.1/src/lexsync/templates/opensesame/inline_send_triggers.py +18 -0
  32. lexsync-0.1.1/src/lexsync/templates/opensesame/inline_trigger_setup.py +53 -0
  33. lexsync-0.1.1/src/lexsync/templates/psychopy/mock_port.py +23 -0
  34. lexsync-0.1.1/src/lexsync/templates/psychopy/trial_runner_template.py +300 -0
  35. lexsync-0.1.1/src/lexsync/validation.py +267 -0
  36. lexsync-0.1.1/tests/conftest.py +34 -0
  37. lexsync-0.1.1/tests/helper_repo.py +58 -0
  38. lexsync-0.1.1/tests/test_apps.py +194 -0
  39. lexsync-0.1.1/tests/test_balance.py +155 -0
  40. lexsync-0.1.1/tests/test_blocks.py +227 -0
  41. lexsync-0.1.1/tests/test_byte_parity.py +110 -0
  42. lexsync-0.1.1/tests/test_categorisation.py +140 -0
  43. lexsync-0.1.1/tests/test_cli.py +76 -0
  44. lexsync-0.1.1/tests/test_config.py +51 -0
  45. lexsync-0.1.1/tests/test_corpora.py +491 -0
  46. lexsync-0.1.1/tests/test_counterbalancing.py +81 -0
  47. lexsync-0.1.1/tests/test_datasheet.py +435 -0
  48. lexsync-0.1.1/tests/test_dimensions.py +98 -0
  49. lexsync-0.1.1/tests/test_es_gender_build.py +63 -0
  50. lexsync-0.1.1/tests/test_exact_reductions.py +287 -0
  51. lexsync-0.1.1/tests/test_generation_subsyllabic.py +49 -0
  52. lexsync-0.1.1/tests/test_hash_primitive.py +80 -0
  53. lexsync-0.1.1/tests/test_init.py +45 -0
  54. lexsync-0.1.1/tests/test_injection.py +198 -0
  55. lexsync-0.1.1/tests/test_io_utils.py +104 -0
  56. lexsync-0.1.1/tests/test_jspsych_export.py +62 -0
  57. lexsync-0.1.1/tests/test_matching.py +501 -0
  58. lexsync-0.1.1/tests/test_metadata.py +209 -0
  59. lexsync-0.1.1/tests/test_norms.py +173 -0
  60. lexsync-0.1.1/tests/test_osexp_validator.py +50 -0
  61. lexsync-0.1.1/tests/test_pairs.py +156 -0
  62. lexsync-0.1.1/tests/test_paradigms.py +104 -0
  63. lexsync-0.1.1/tests/test_parity.py +165 -0
  64. lexsync-0.1.1/tests/test_psychopy_export.py +125 -0
  65. lexsync-0.1.1/tests/test_querying.py +268 -0
  66. lexsync-0.1.1/tests/test_readme.py +49 -0
  67. lexsync-0.1.1/tests/test_run_pipeline.py +286 -0
  68. lexsync-0.1.1/tests/test_scripting.py +214 -0
  69. lexsync-0.1.1/tests/test_templates.py +71 -0
  70. lexsync-0.1.1/tests/test_timing.py +114 -0
  71. lexsync-0.1.1/tests/test_trial_timing.py +133 -0
  72. lexsync-0.1.1/tests/test_validation.py +185 -0
@@ -0,0 +1,88 @@
1
+ # --- R ---------------------------------------------------------------------
2
+ .Rproj.user
3
+ .Rhistory
4
+ .RData
5
+ .Ruserdata
6
+ *.Rproj
7
+ R_workflow/..Rcheck/
8
+ R_workflow/*.Rcheck/
9
+ R_workflow/*.tar.gz
10
+ *.Rcheck/
11
+ /lexsync_*.tar.gz
12
+ R_workflow/src/*.o
13
+ R_workflow/src/*.so
14
+ R_workflow/src/*.dll
15
+ renv/library/
16
+ R_workflow/renv/library/
17
+ # `R CMD build` and devtools::build_vignettes() write these into the package
18
+ # directory. They are rendered copies of vignettes/, so committing them would
19
+ # publish a second, silently stale copy of every article.
20
+ R_workflow/doc/
21
+ R_workflow/Meta/
22
+ R_workflow/inst/doc/
23
+
24
+ # --- Python ----------------------------------------------------------------
25
+ __pycache__/
26
+ *.py[cod]
27
+ *.egg-info/
28
+ .eggs/
29
+ build/
30
+ dist/
31
+ .venv/
32
+ venv/
33
+ python_workflow/.venv/
34
+ .pytest_cache/
35
+ .mypy_cache/
36
+ .ruff_cache/
37
+
38
+ # --- Corpora (large raw downloads are fetched on demand) -------------------
39
+ corpora/raw/*
40
+ !corpora/raw/.gitkeep
41
+
42
+ # --- Quarto render intermediates -------------------------------------------
43
+ # The manuscript itself now lives in the private-lexsync repository; this rule
44
+ # stays because the vignettes and the docs sites can still leave a .quarto cache.
45
+ /.quarto/
46
+
47
+ # --- Documentation sites (generated; the docs workflow rebuilds and deploys) -
48
+ R_workflow/docs/
49
+ python_workflow/site/
50
+ /site/
51
+
52
+ # --- session build/check temporaries ---------------------------------------
53
+ /.rcheck_tmp/
54
+ /.regen_R.log
55
+ /.pkgdown_build.log
56
+ /.audit_findings.txt
57
+
58
+ # --- Credentials -----------------------------------------------------------
59
+ # Publishing to PyPI gives lexsync a credential of its own for the first time.
60
+ # Twine reads an upload token from .pypirc in plaintext. It looks in the home
61
+ # directory by default, but --config-file will take one from anywhere, and a copy
62
+ # made for a single upload is the kind that gets left behind. Nothing else listed
63
+ # here is expected to exist. Those patterns are defensive: the repository is
64
+ # public, and an .Renviron or a .env is the ordinary way an R or Python secret
65
+ # reaches a working tree by accident. A commit that never happens needs no
66
+ # history rewrite.
67
+ .pypirc
68
+ .env
69
+ .env.*
70
+ .Renviron
71
+ *.pem
72
+ *.p12
73
+ *.pfx
74
+ *.key
75
+ id_rsa*
76
+ id_ed25519*
77
+
78
+ # --- Editor and local tool state -------------------------------------------
79
+ # .claude/launch.json is deliberately tracked: it is how anyone launches the two
80
+ # demo apps. Only the per-user settings file is local.
81
+ .vscode/
82
+ .idea/
83
+ *.swp
84
+ .claude/settings.local.json
85
+
86
+ # --- OS --------------------------------------------------------------------
87
+ .DS_Store
88
+ Thumbs.db
lexsync-0.1.1/LICENSE ADDED
@@ -0,0 +1,33 @@
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.
22
+
23
+ ----------------------------------------------------------------------------
24
+ The MIT License above covers the lexsync source code. The lexical corpora that
25
+ the package bundles or fetches are NOT covered by it. Three of the data files
26
+ shipped inside the package, lexsync/data/en_example.csv, es_example.csv and
27
+ zh_example.csv, are wordfreq derivatives distributed under CC BY-SA 4.0. Their
28
+ terms are set out in full in LICENSE.note, which ships beside this file. The
29
+ repository keeps the fuller record, with the retrieval date and checksum of
30
+ every derived file, at
31
+
32
+ https://github.com/pablobernabeu/lexsync/blob/main/LICENSE-DATA
33
+ https://github.com/pablobernabeu/lexsync/blob/main/corpora/ATTRIBUTION.md
@@ -0,0 +1,108 @@
1
+ Licensing note for the lexsync package
2
+ ======================================
3
+
4
+ The MIT licence in the LICENSE file covers the source code of this package only.
5
+ Three of the data files shipped inside the package are third-party derivatives
6
+ carrying their own terms, which are set out here.
7
+
8
+
9
+ Bundled corpus derivatives
10
+ --------------------------
11
+
12
+ lexsync/data/en_example.csv
13
+ lexsync/data/es_example.csv
14
+ lexsync/data/zh_example.csv
15
+
16
+ These small example lexica are derived from the wordfreq package (Speer, 2022,
17
+ https://doi.org/10.5281/zenodo.7199437). wordfreq distributes its code and its
18
+ data under different terms. The code is under the Apache License 2.0, and the
19
+ data files, which are what these three derivatives come from, are
20
+ redistributable under
21
+
22
+ Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
23
+ https://creativecommons.org/licenses/by-sa/4.0/
24
+
25
+ The three files above are therefore distributed under CC BY-SA 4.0 rather than
26
+ under the MIT licence. Anyone redistributing them, or an adaptation of them,
27
+ must give appropriate credit to the corpus authors, indicate that changes were
28
+ made, and place any adaptation under the same licence. Everything else in the
29
+ package, including the other files under lexsync/data, is MIT.
30
+
31
+ Two further notices belong with these three files, because CC BY-SA 4.0 asks
32
+ that they be kept with the material. The copyright notice carried by wordfreq's
33
+ own licence file is 'Copyright 2022 Robyn Speer', and it is retained here. As
34
+ section 5 of CC BY-SA 4.0 sets out, the licensor offers the material as-is and
35
+ as-available and makes no representations or warranties of any kind concerning
36
+ it, whether express, implied, statutory or other.
37
+
38
+ A note on wordfreq's licence history: wordfreq was released under the MIT
39
+ licence up to version 3.0.2 and relicensed to Apache 2.0 at 3.0.3. lexsync
40
+ requires wordfreq>=3.0,<4, which spans that change, so an installation may
41
+ carry either. The data terms above are unaffected.
42
+
43
+
44
+ What lexsync changed
45
+ --------------------
46
+
47
+ The frequencies are wordfreq's own Zipf values, carried through unaltered. What
48
+ lexsync added is a standardised column layout, shared by every corpus the
49
+ package reads, and two orthographic-neighbourhood variables computed here from
50
+ the word list itself: Coltheart's N, the count of same-length neighbours
51
+ reachable by a single letter substitution, and OLD20, the mean Levenshtein
52
+ distance to the twenty nearest words. Each row names its origin in the 'source'
53
+ column.
54
+
55
+
56
+ Credit for SUBTLEX
57
+ ------------------
58
+
59
+ wordfreq's frequencies blend up to eight domains of text, among them Wikipedia,
60
+ OPUS OpenSubtitles, NewsCrawl, Google Books Ngrams, OSCAR, Twitter and Reddit.
61
+ The subtitles domain draws in part on the SUBTLEX word lists, which wordfreq
62
+ carries by permission on two conditions that pass through to anything derived
63
+ from it: work derived from wordfreq must credit the SUBTLEX authors, and it must
64
+ remain clear that SUBTLEX is freely available data. Both are honoured here. The
65
+ lists are freely available, and their authors are credited as follows.
66
+
67
+ Brysbaert, M., & New, B. (2009). SUBTLEX-US. Behavior Research Methods,
68
+ 41(4), 977-990. https://doi.org/10.3758/BRM.41.4.977
69
+
70
+ van Heuven, W. J. B., Mandera, P., Keuleers, E., & Brysbaert, M. (2014).
71
+ SUBTLEX-UK. Quarterly Journal of Experimental Psychology, 67(6), 1176-1190.
72
+ https://doi.org/10.1080/17470218.2013.850521
73
+
74
+ Cai, Q., & Brysbaert, M. (2010). SUBTLEX-CH. PLoS ONE, 5(6), e10729.
75
+ https://doi.org/10.1371/journal.pone.0010729
76
+
77
+ Brysbaert, M., Buchmeier, M., Conrad, M., Jacobs, A. M., Bölte, J., & Böhl, A.
78
+ (2011). SUBTLEX-DE. Experimental Psychology, 58(5), 412-424.
79
+ https://doi.org/10.1027/1618-3169/a000123
80
+
81
+ Keuleers, E., Brysbaert, M., & New, B. (2010). SUBTLEX-NL. Behavior Research
82
+ Methods, 42(3), 643-650. https://doi.org/10.3758/BRM.42.3.643
83
+
84
+ SUBTLEX contributes to the blend rather than constituting it. No file bundled
85
+ here is a copy of a SUBTLEX list, and the SUBTLEX resources the corpus registry
86
+ offers are separate corpora a user may fetch directly, not the source of
87
+ anything shipped in this package.
88
+
89
+
90
+ Corpora fetched at run time
91
+ ---------------------------
92
+
93
+ Corpora downloaded on demand through the registry are not redistributed with
94
+ this package. Each carries its own licence and citation, recorded in the
95
+ registry entry and reported by list_corpora(). The optional wordfreq
96
+ connector produces lexica under the same terms as the bundled derivatives,
97
+ since they come from the same source.
98
+
99
+
100
+ The fuller account
101
+ ------------------
102
+
103
+ The repository keeps the complete record, including the provenance caveat that
104
+ travels with the Chinese corpus and the retrieval date and checksum of every
105
+ derived file:
106
+
107
+ https://github.com/pablobernabeu/lexsync/blob/main/LICENSE-DATA
108
+ https://github.com/pablobernabeu/lexsync/blob/main/corpora/ATTRIBUTION.md
lexsync-0.1.1/PKG-INFO ADDED
@@ -0,0 +1,234 @@
1
+ Metadata-Version: 2.5
2
+ Name: lexsync
3
+ Version: 0.1.1
4
+ Summary: Lexical optimisation and hardware-timed experiment generation
5
+ Project-URL: Homepage, https://github.com/pablobernabeu/lexsync
6
+ Project-URL: Repository, https://github.com/pablobernabeu/lexsync
7
+ Project-URL: Documentation, https://pablobernabeu.github.io/lexsync/python/
8
+ Project-URL: Changelog, https://pablobernabeu.github.io/lexsync/python/changelog/
9
+ Project-URL: Issues, https://github.com/pablobernabeu/lexsync/issues
10
+ Project-URL: R twin, https://pablobernabeu.github.io/lexsync/r/
11
+ Author-email: Pablo Bernabeu <pcbernabeu@gmail.com>
12
+ License-Expression: MIT AND CC-BY-SA-4.0
13
+ License-File: LICENSE
14
+ License-File: LICENSE.note
15
+ Keywords: EEG,ERP,FAIR,OpenSesame,PsychoPy,counterbalancing,jsPsych,lexical statistics,pseudoword generation,psycholinguistics,stimulus matching
16
+ Classifier: Development Status :: 3 - Alpha
17
+ Classifier: Intended Audience :: Science/Research
18
+ Classifier: Operating System :: OS Independent
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3 :: Only
21
+ Classifier: Programming Language :: Python :: 3.10
22
+ Classifier: Programming Language :: Python :: 3.11
23
+ Classifier: Programming Language :: Python :: 3.12
24
+ Classifier: Programming Language :: Python :: 3.13
25
+ Classifier: Programming Language :: Python :: 3.14
26
+ Classifier: Topic :: Scientific/Engineering
27
+ Classifier: Topic :: Scientific/Engineering :: Information Analysis
28
+ Classifier: Typing :: Typed
29
+ Requires-Python: >=3.10
30
+ Requires-Dist: numpy>=1.23
31
+ Requires-Dist: pandas>=1.5
32
+ Requires-Dist: pyyaml>=6.0
33
+ Requires-Dist: rapidfuzz>=3.0
34
+ Requires-Dist: scipy>=1.9
35
+ Provides-Extra: corpora
36
+ Requires-Dist: wordfreq<4,>=3.0; extra == 'corpora'
37
+ Provides-Extra: dev
38
+ Requires-Dist: build; extra == 'dev'
39
+ Requires-Dist: pytest>=7.0; extra == 'dev'
40
+ Requires-Dist: streamlit>=1.30; extra == 'dev'
41
+ Requires-Dist: twine; extra == 'dev'
42
+ Provides-Extra: experiment
43
+ Requires-Dist: psychopy>=2024.1; extra == 'experiment'
44
+ Requires-Dist: pyserial>=3.5; extra == 'experiment'
45
+ Description-Content-Type: text/markdown
46
+
47
+ # lexsync (Python)
48
+
49
+ <!-- badges: start -->
50
+ [![PyPI](https://img.shields.io/pypi/v/lexsync)](https://pypi.org/project/lexsync/)
51
+ [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22906962.svg)](https://doi.org/10.5281/zenodo.22906962)
52
+ [![python-tests](https://github.com/pablobernabeu/lexsync/actions/workflows/python-tests.yaml/badge.svg)](https://github.com/pablobernabeu/lexsync/actions/workflows/python-tests.yaml)
53
+ [![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
54
+ [![Code: MIT](https://img.shields.io/badge/code-MIT-blue.svg)](https://opensource.org/license/MIT)
55
+ [![Data: CC BY-SA 4.0](https://img.shields.io/badge/data-CC_BY--SA_4.0-blue.svg)](https://creativecommons.org/licenses/by-sa/4.0/)
56
+ <!-- badges: end -->
57
+
58
+ Lexical optimisation and hardware-timed experiment generation.
59
+
60
+ lexsync selects stimuli matched in parallel across several lexical dimensions
61
+ (length, frequency, orthographic neighbourhood density and OLD20),
62
+ counterbalances them across conditions and lists, and generates the 'PsychoPy',
63
+ 'OpenSesame' and 'jsPsych' scripts that present them. The two laboratory targets
64
+ carry hardware triggers injected at stimulus onset for EEG/ERP synchronisation,
65
+ and the browser target is a single shareable HTML file.
66
+
67
+ This is the feature-parity twin of [the R
68
+ package](https://pablobernabeu.github.io/lexsync/r/) of the same name, which
69
+ offers the same workflow in R. The two engines select byte-identical stimuli
70
+ under the deterministic matching methods, and are built from one repository and
71
+ released under one version.
72
+
73
+ Documentation, including the guides and the full API reference, is at
74
+ <https://pablobernabeu.github.io/lexsync/python/>.
75
+
76
+ ## Install
77
+
78
+ The package is on [PyPI](https://pypi.org/project/lexsync/):
79
+
80
+ ```bash
81
+ pip install lexsync
82
+ ```
83
+
84
+ The `corpora` extra adds the 'wordfreq' connector, which reaches roughly forty
85
+ languages through a single dependency, and the `experiment` extra adds
86
+ 'PsychoPy' and 'pyserial'. Note that the `experiment` extra is needed only to run
87
+ a generated experiment on hardware, never to generate one. PsychoPy currently
88
+ supports Python 3.10 to 3.12, so on a newer interpreter that extra stops with a
89
+ message naming psychopy, while the rest of the package installs on any supported
90
+ version. [Getting
91
+ started](https://pablobernabeu.github.io/lexsync/python/getting-started/)
92
+ explains why and suggests an interpreter for hardware work. An extra goes in
93
+ brackets after the package name:
94
+
95
+ ```bash
96
+ pip install "lexsync[corpora]"
97
+ pip install "lexsync[experiment]"
98
+ ```
99
+
100
+ The development version installs from the repository, where the Python package
101
+ sits in the `python_workflow/` subdirectory:
102
+
103
+ ```bash
104
+ pip install "git+https://github.com/pablobernabeu/lexsync.git#subdirectory=python_workflow"
105
+ ```
106
+
107
+ ## Quick start
108
+
109
+ The package bundles a 3000-word slice of an English lexicon and a copy of the
110
+ global schema, so the example below runs straight after installation, from any
111
+ working directory, with no corpus to download and nothing to configure. It
112
+ contrasts high- with low-frequency words while equating them, item by item, on
113
+ length, orthographic neighbourhood density and OLD20.
114
+
115
+ ```python
116
+ from importlib.resources import files
117
+
118
+ import yaml
119
+
120
+ import lexsync
121
+
122
+ data = files("lexsync") / "data"
123
+ schema = yaml.safe_load((data / "schema.yaml").read_text(encoding="utf-8"))
124
+
125
+ design = {
126
+ "name": "quick_start",
127
+ "language": "english",
128
+ "n_per_condition": 60,
129
+ "pool_filters": {"length": [3, 8], "frequency": [3.8, 7.0]},
130
+ "conditions": [
131
+ {"name": "high_frequency", "define_by": {"frequency": [5.2, 7.0]}},
132
+ {"name": "low_frequency", "define_by": {"frequency": [3.8, 4.4]}},
133
+ ],
134
+ "match_on": ["length", "n_density", "old20"],
135
+ "counterbalance": {"lists": 1},
136
+ }
137
+
138
+ lexicon = lexsync.load_lexicon(str(data / "en_example.csv"), schema, language="english")
139
+ pool = lexsync.build_pool(lexicon, design["pool_filters"])
140
+ stimuli = lexsync.match_stimuli(pool, design, schema)
141
+
142
+ report = lexsync.match_report(
143
+ stimuli, ["length", "frequency", "n_density", "old20"], schema
144
+ )
145
+ print(report["comparisons"].to_string(index=False))
146
+ ```
147
+
148
+ The report is the point of the exercise, because it measures what the matching
149
+ achieved. Frequency, the manipulation, separates the conditions by nearly six
150
+ standard deviations, while each control dimension passes a two one-sided tests
151
+ procedure against a bound of *d* = 0.5, so it is shown to be equivalent and not
152
+ merely to have escaped a significance test. The [Matching and designs
153
+ guide](https://pablobernabeu.github.io/lexsync/python/matching-and-designs/)
154
+ reads the report column by column.
155
+
156
+ ## Use
157
+
158
+ The example below builds a matched stimulus set from a design file and writes
159
+ the experiment scripts for it. It reads the schema, the derived corpus and the
160
+ design from the repository, so clone [the
161
+ repository](https://github.com/pablobernabeu/lexsync) and run it from the root
162
+ of the clone:
163
+
164
+ ```bash
165
+ git clone https://github.com/pablobernabeu/lexsync.git
166
+ cd lexsync
167
+ ```
168
+
169
+ ```python
170
+ import yaml, lexsync
171
+
172
+ schema = yaml.safe_load(open("config/schema.yaml"))
173
+ lex = lexsync.load_lexicon("corpora/derived/en.csv", schema, "english")
174
+
175
+ design = yaml.safe_load(open("config/design_en_freqcontrast.yaml"))
176
+ pool = lexsync.build_pool(lex, design["pool_filters"])
177
+ stim = lexsync.match_stimuli(pool, design, schema)
178
+ # Not optional: this assigns the counterbalancing lists and draws the trial
179
+ # order. Exporting without it writes every trial of one condition and then every
180
+ # trial of the next, with no `trial` column and no `list` column.
181
+ stim = lexsync.counterbalance(stim, design, schema)
182
+
183
+ report = lexsync.match_report(stim, ["length", "frequency", "n_density", "old20"], schema)
184
+ lexsync.export_experiments(
185
+ lexsync.scripting.assign_triggers(stim), design, schema, "output/experiments"
186
+ )
187
+ ```
188
+
189
+ The same operations are available from the command line, which runs a whole
190
+ design end to end (again from the root of the clone), lists the registered
191
+ corpora and derives a new lexicon:
192
+
193
+ ```bash
194
+ lexsync run config/design_en_freqcontrast.yaml
195
+ lexsync corpora list
196
+ lexsync fetch fr # build a French lexicon via wordfreq
197
+ ```
198
+
199
+ ## Citation
200
+
201
+ Cite the software. The authoritative record is
202
+ [`CITATION.cff`](https://github.com/pablobernabeu/lexsync/blob/main/CITATION.cff)
203
+ at the root of the repository, which GitHub renders into several formats through
204
+ its 'Cite this repository' button. The [About
205
+ page](https://pablobernabeu.github.io/lexsync/python/about/) carries a formatted
206
+ reference for this package, which gives its version and the concept DOI of the
207
+ Zenodo archive, [10.5281/zenodo.22906962](https://doi.org/10.5281/zenodo.22906962). The first DOI in
208
+ `CITATION.cff` is the one CRAN assigned to the R package, so it does not
209
+ identify the Python package. A manuscript describing lexsync is in preparation.
210
+
211
+ Cite the corpus as well as the software. The corpora are third-party work with
212
+ their own terms, and each is credited, with its licence and retrieval date, in
213
+ [`corpora/ATTRIBUTION.md`](https://github.com/pablobernabeu/lexsync/blob/main/corpora/ATTRIBUTION.md).
214
+
215
+ ## Licence
216
+
217
+ MIT for the code. The bundled corpus derivatives are not covered by it. The
218
+ three example lexica, installed as `lexsync/data/en_example.csv`,
219
+ `lexsync/data/es_example.csv` and `lexsync/data/zh_example.csv`, are derived from
220
+ 'wordfreq' and are released under CC BY-SA 4.0, which asks anyone who
221
+ redistributes them to credit the corpus authors, say that changes were made and
222
+ keep the same terms on any adaptation. `LICENSE.note` states this inside the
223
+ distribution itself, alongside `LICENSE`, so the terms travel with the installed
224
+ package. The repository keeps the fuller record, including the retrieval date
225
+ and checksum of every derived file, in
226
+ [`LICENSE-DATA`](https://github.com/pablobernabeu/lexsync/blob/main/LICENSE-DATA).
227
+
228
+ ## Contributing
229
+
230
+ Issues and pull requests are welcome, on the [issue
231
+ tracker](https://github.com/pablobernabeu/lexsync/issues) of the repository that
232
+ holds both twins. A report that includes the design YAML and the run log is one
233
+ someone can act on, since between them they pin the inputs and every step that
234
+ ran.
@@ -0,0 +1,188 @@
1
+ # lexsync (Python)
2
+
3
+ <!-- badges: start -->
4
+ [![PyPI](https://img.shields.io/pypi/v/lexsync)](https://pypi.org/project/lexsync/)
5
+ [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22906962.svg)](https://doi.org/10.5281/zenodo.22906962)
6
+ [![python-tests](https://github.com/pablobernabeu/lexsync/actions/workflows/python-tests.yaml/badge.svg)](https://github.com/pablobernabeu/lexsync/actions/workflows/python-tests.yaml)
7
+ [![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
8
+ [![Code: MIT](https://img.shields.io/badge/code-MIT-blue.svg)](https://opensource.org/license/MIT)
9
+ [![Data: CC BY-SA 4.0](https://img.shields.io/badge/data-CC_BY--SA_4.0-blue.svg)](https://creativecommons.org/licenses/by-sa/4.0/)
10
+ <!-- badges: end -->
11
+
12
+ Lexical optimisation and hardware-timed experiment generation.
13
+
14
+ lexsync selects stimuli matched in parallel across several lexical dimensions
15
+ (length, frequency, orthographic neighbourhood density and OLD20),
16
+ counterbalances them across conditions and lists, and generates the 'PsychoPy',
17
+ 'OpenSesame' and 'jsPsych' scripts that present them. The two laboratory targets
18
+ carry hardware triggers injected at stimulus onset for EEG/ERP synchronisation,
19
+ and the browser target is a single shareable HTML file.
20
+
21
+ This is the feature-parity twin of [the R
22
+ package](https://pablobernabeu.github.io/lexsync/r/) of the same name, which
23
+ offers the same workflow in R. The two engines select byte-identical stimuli
24
+ under the deterministic matching methods, and are built from one repository and
25
+ released under one version.
26
+
27
+ Documentation, including the guides and the full API reference, is at
28
+ <https://pablobernabeu.github.io/lexsync/python/>.
29
+
30
+ ## Install
31
+
32
+ The package is on [PyPI](https://pypi.org/project/lexsync/):
33
+
34
+ ```bash
35
+ pip install lexsync
36
+ ```
37
+
38
+ The `corpora` extra adds the 'wordfreq' connector, which reaches roughly forty
39
+ languages through a single dependency, and the `experiment` extra adds
40
+ 'PsychoPy' and 'pyserial'. Note that the `experiment` extra is needed only to run
41
+ a generated experiment on hardware, never to generate one. PsychoPy currently
42
+ supports Python 3.10 to 3.12, so on a newer interpreter that extra stops with a
43
+ message naming psychopy, while the rest of the package installs on any supported
44
+ version. [Getting
45
+ started](https://pablobernabeu.github.io/lexsync/python/getting-started/)
46
+ explains why and suggests an interpreter for hardware work. An extra goes in
47
+ brackets after the package name:
48
+
49
+ ```bash
50
+ pip install "lexsync[corpora]"
51
+ pip install "lexsync[experiment]"
52
+ ```
53
+
54
+ The development version installs from the repository, where the Python package
55
+ sits in the `python_workflow/` subdirectory:
56
+
57
+ ```bash
58
+ pip install "git+https://github.com/pablobernabeu/lexsync.git#subdirectory=python_workflow"
59
+ ```
60
+
61
+ ## Quick start
62
+
63
+ The package bundles a 3000-word slice of an English lexicon and a copy of the
64
+ global schema, so the example below runs straight after installation, from any
65
+ working directory, with no corpus to download and nothing to configure. It
66
+ contrasts high- with low-frequency words while equating them, item by item, on
67
+ length, orthographic neighbourhood density and OLD20.
68
+
69
+ ```python
70
+ from importlib.resources import files
71
+
72
+ import yaml
73
+
74
+ import lexsync
75
+
76
+ data = files("lexsync") / "data"
77
+ schema = yaml.safe_load((data / "schema.yaml").read_text(encoding="utf-8"))
78
+
79
+ design = {
80
+ "name": "quick_start",
81
+ "language": "english",
82
+ "n_per_condition": 60,
83
+ "pool_filters": {"length": [3, 8], "frequency": [3.8, 7.0]},
84
+ "conditions": [
85
+ {"name": "high_frequency", "define_by": {"frequency": [5.2, 7.0]}},
86
+ {"name": "low_frequency", "define_by": {"frequency": [3.8, 4.4]}},
87
+ ],
88
+ "match_on": ["length", "n_density", "old20"],
89
+ "counterbalance": {"lists": 1},
90
+ }
91
+
92
+ lexicon = lexsync.load_lexicon(str(data / "en_example.csv"), schema, language="english")
93
+ pool = lexsync.build_pool(lexicon, design["pool_filters"])
94
+ stimuli = lexsync.match_stimuli(pool, design, schema)
95
+
96
+ report = lexsync.match_report(
97
+ stimuli, ["length", "frequency", "n_density", "old20"], schema
98
+ )
99
+ print(report["comparisons"].to_string(index=False))
100
+ ```
101
+
102
+ The report is the point of the exercise, because it measures what the matching
103
+ achieved. Frequency, the manipulation, separates the conditions by nearly six
104
+ standard deviations, while each control dimension passes a two one-sided tests
105
+ procedure against a bound of *d* = 0.5, so it is shown to be equivalent and not
106
+ merely to have escaped a significance test. The [Matching and designs
107
+ guide](https://pablobernabeu.github.io/lexsync/python/matching-and-designs/)
108
+ reads the report column by column.
109
+
110
+ ## Use
111
+
112
+ The example below builds a matched stimulus set from a design file and writes
113
+ the experiment scripts for it. It reads the schema, the derived corpus and the
114
+ design from the repository, so clone [the
115
+ repository](https://github.com/pablobernabeu/lexsync) and run it from the root
116
+ of the clone:
117
+
118
+ ```bash
119
+ git clone https://github.com/pablobernabeu/lexsync.git
120
+ cd lexsync
121
+ ```
122
+
123
+ ```python
124
+ import yaml, lexsync
125
+
126
+ schema = yaml.safe_load(open("config/schema.yaml"))
127
+ lex = lexsync.load_lexicon("corpora/derived/en.csv", schema, "english")
128
+
129
+ design = yaml.safe_load(open("config/design_en_freqcontrast.yaml"))
130
+ pool = lexsync.build_pool(lex, design["pool_filters"])
131
+ stim = lexsync.match_stimuli(pool, design, schema)
132
+ # Not optional: this assigns the counterbalancing lists and draws the trial
133
+ # order. Exporting without it writes every trial of one condition and then every
134
+ # trial of the next, with no `trial` column and no `list` column.
135
+ stim = lexsync.counterbalance(stim, design, schema)
136
+
137
+ report = lexsync.match_report(stim, ["length", "frequency", "n_density", "old20"], schema)
138
+ lexsync.export_experiments(
139
+ lexsync.scripting.assign_triggers(stim), design, schema, "output/experiments"
140
+ )
141
+ ```
142
+
143
+ The same operations are available from the command line, which runs a whole
144
+ design end to end (again from the root of the clone), lists the registered
145
+ corpora and derives a new lexicon:
146
+
147
+ ```bash
148
+ lexsync run config/design_en_freqcontrast.yaml
149
+ lexsync corpora list
150
+ lexsync fetch fr # build a French lexicon via wordfreq
151
+ ```
152
+
153
+ ## Citation
154
+
155
+ Cite the software. The authoritative record is
156
+ [`CITATION.cff`](https://github.com/pablobernabeu/lexsync/blob/main/CITATION.cff)
157
+ at the root of the repository, which GitHub renders into several formats through
158
+ its 'Cite this repository' button. The [About
159
+ page](https://pablobernabeu.github.io/lexsync/python/about/) carries a formatted
160
+ reference for this package, which gives its version and the concept DOI of the
161
+ Zenodo archive, [10.5281/zenodo.22906962](https://doi.org/10.5281/zenodo.22906962). The first DOI in
162
+ `CITATION.cff` is the one CRAN assigned to the R package, so it does not
163
+ identify the Python package. A manuscript describing lexsync is in preparation.
164
+
165
+ Cite the corpus as well as the software. The corpora are third-party work with
166
+ their own terms, and each is credited, with its licence and retrieval date, in
167
+ [`corpora/ATTRIBUTION.md`](https://github.com/pablobernabeu/lexsync/blob/main/corpora/ATTRIBUTION.md).
168
+
169
+ ## Licence
170
+
171
+ MIT for the code. The bundled corpus derivatives are not covered by it. The
172
+ three example lexica, installed as `lexsync/data/en_example.csv`,
173
+ `lexsync/data/es_example.csv` and `lexsync/data/zh_example.csv`, are derived from
174
+ 'wordfreq' and are released under CC BY-SA 4.0, which asks anyone who
175
+ redistributes them to credit the corpus authors, say that changes were made and
176
+ keep the same terms on any adaptation. `LICENSE.note` states this inside the
177
+ distribution itself, alongside `LICENSE`, so the terms travel with the installed
178
+ package. The repository keeps the fuller record, including the retrieval date
179
+ and checksum of every derived file, in
180
+ [`LICENSE-DATA`](https://github.com/pablobernabeu/lexsync/blob/main/LICENSE-DATA).
181
+
182
+ ## Contributing
183
+
184
+ Issues and pull requests are welcome, on the [issue
185
+ tracker](https://github.com/pablobernabeu/lexsync/issues) of the repository that
186
+ holds both twins. A report that includes the design YAML and the run log is one
187
+ someone can act on, since between them they pin the inputs and every step that
188
+ ran.