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.
- lexsync-0.1.1/.gitignore +88 -0
- lexsync-0.1.1/LICENSE +33 -0
- lexsync-0.1.1/LICENSE.note +108 -0
- lexsync-0.1.1/PKG-INFO +234 -0
- lexsync-0.1.1/README.md +188 -0
- lexsync-0.1.1/pyproject.toml +192 -0
- lexsync-0.1.1/src/lexsync/__init__.py +53 -0
- lexsync-0.1.1/src/lexsync/__main__.py +5 -0
- lexsync-0.1.1/src/lexsync/blocks.py +149 -0
- lexsync-0.1.1/src/lexsync/cli.py +85 -0
- lexsync-0.1.1/src/lexsync/corpora.py +331 -0
- lexsync-0.1.1/src/lexsync/counterbalancing.py +399 -0
- lexsync-0.1.1/src/lexsync/data/en_example.csv +3001 -0
- lexsync-0.1.1/src/lexsync/data/es_example.csv +3001 -0
- lexsync-0.1.1/src/lexsync/data/registry.yaml +149 -0
- lexsync-0.1.1/src/lexsync/data/schema.yaml +193 -0
- lexsync-0.1.1/src/lexsync/data/zh_example.csv +3001 -0
- lexsync-0.1.1/src/lexsync/datasheet.py +752 -0
- lexsync-0.1.1/src/lexsync/generation.py +280 -0
- lexsync-0.1.1/src/lexsync/io_utils.py +609 -0
- lexsync-0.1.1/src/lexsync/logging.py +88 -0
- lexsync-0.1.1/src/lexsync/matching.py +614 -0
- lexsync-0.1.1/src/lexsync/pairs.py +177 -0
- lexsync-0.1.1/src/lexsync/paradigms.py +163 -0
- lexsync-0.1.1/src/lexsync/py.typed +0 -0
- lexsync-0.1.1/src/lexsync/querying.py +481 -0
- lexsync-0.1.1/src/lexsync/run_pipeline.py +425 -0
- lexsync-0.1.1/src/lexsync/scripting.py +845 -0
- lexsync-0.1.1/src/lexsync/templates/jspsych/experiment_template.html +223 -0
- lexsync-0.1.1/src/lexsync/templates/opensesame/README.md +36 -0
- lexsync-0.1.1/src/lexsync/templates/opensesame/inline_send_triggers.py +18 -0
- lexsync-0.1.1/src/lexsync/templates/opensesame/inline_trigger_setup.py +53 -0
- lexsync-0.1.1/src/lexsync/templates/psychopy/mock_port.py +23 -0
- lexsync-0.1.1/src/lexsync/templates/psychopy/trial_runner_template.py +300 -0
- lexsync-0.1.1/src/lexsync/validation.py +267 -0
- lexsync-0.1.1/tests/conftest.py +34 -0
- lexsync-0.1.1/tests/helper_repo.py +58 -0
- lexsync-0.1.1/tests/test_apps.py +194 -0
- lexsync-0.1.1/tests/test_balance.py +155 -0
- lexsync-0.1.1/tests/test_blocks.py +227 -0
- lexsync-0.1.1/tests/test_byte_parity.py +110 -0
- lexsync-0.1.1/tests/test_categorisation.py +140 -0
- lexsync-0.1.1/tests/test_cli.py +76 -0
- lexsync-0.1.1/tests/test_config.py +51 -0
- lexsync-0.1.1/tests/test_corpora.py +491 -0
- lexsync-0.1.1/tests/test_counterbalancing.py +81 -0
- lexsync-0.1.1/tests/test_datasheet.py +435 -0
- lexsync-0.1.1/tests/test_dimensions.py +98 -0
- lexsync-0.1.1/tests/test_es_gender_build.py +63 -0
- lexsync-0.1.1/tests/test_exact_reductions.py +287 -0
- lexsync-0.1.1/tests/test_generation_subsyllabic.py +49 -0
- lexsync-0.1.1/tests/test_hash_primitive.py +80 -0
- lexsync-0.1.1/tests/test_init.py +45 -0
- lexsync-0.1.1/tests/test_injection.py +198 -0
- lexsync-0.1.1/tests/test_io_utils.py +104 -0
- lexsync-0.1.1/tests/test_jspsych_export.py +62 -0
- lexsync-0.1.1/tests/test_matching.py +501 -0
- lexsync-0.1.1/tests/test_metadata.py +209 -0
- lexsync-0.1.1/tests/test_norms.py +173 -0
- lexsync-0.1.1/tests/test_osexp_validator.py +50 -0
- lexsync-0.1.1/tests/test_pairs.py +156 -0
- lexsync-0.1.1/tests/test_paradigms.py +104 -0
- lexsync-0.1.1/tests/test_parity.py +165 -0
- lexsync-0.1.1/tests/test_psychopy_export.py +125 -0
- lexsync-0.1.1/tests/test_querying.py +268 -0
- lexsync-0.1.1/tests/test_readme.py +49 -0
- lexsync-0.1.1/tests/test_run_pipeline.py +286 -0
- lexsync-0.1.1/tests/test_scripting.py +214 -0
- lexsync-0.1.1/tests/test_templates.py +71 -0
- lexsync-0.1.1/tests/test_timing.py +114 -0
- lexsync-0.1.1/tests/test_trial_timing.py +133 -0
- lexsync-0.1.1/tests/test_validation.py +185 -0
lexsync-0.1.1/.gitignore
ADDED
|
@@ -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
|
+
[](https://pypi.org/project/lexsync/)
|
|
51
|
+
[](https://doi.org/10.5281/zenodo.22906962)
|
|
52
|
+
[](https://github.com/pablobernabeu/lexsync/actions/workflows/python-tests.yaml)
|
|
53
|
+
[](https://lifecycle.r-lib.org/articles/stages.html#experimental)
|
|
54
|
+
[](https://opensource.org/license/MIT)
|
|
55
|
+
[](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.
|
lexsync-0.1.1/README.md
ADDED
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
# lexsync (Python)
|
|
2
|
+
|
|
3
|
+
<!-- badges: start -->
|
|
4
|
+
[](https://pypi.org/project/lexsync/)
|
|
5
|
+
[](https://doi.org/10.5281/zenodo.22906962)
|
|
6
|
+
[](https://github.com/pablobernabeu/lexsync/actions/workflows/python-tests.yaml)
|
|
7
|
+
[](https://lifecycle.r-lib.org/articles/stages.html#experimental)
|
|
8
|
+
[](https://opensource.org/license/MIT)
|
|
9
|
+
[](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.
|