lexsync (R)

CRAN status R-CMD-check Lifecycle: experimental License: MIT DOI 10.32614/CRAN.package.lexsync

lexsync builds psycholinguistic stimulus sets and the experiments that present them. Given a word-frequency corpus in any of dozens of languages and a short design file, it selects items matched in parallel across several lexical dimensions, counterbalances them across conditions and lists, and writes the experiment that runs them on ‘PsychoPy’, ‘OpenSesame’ or in the browser through ‘jsPsych’. The two laboratory targets carry electroencephalography triggers bound to the buffer flip on which the stimulus appears. A trial is described declaratively, as a sequence of events. Factorial word contrasts, lexical decision with generated pseudowords, priming, self-paced reading and cued categorisation therefore all come from the same engine and the same configuration file, as do the practice and filler blocks that run but are not analysed.

This is the feature-parity twin of the Python package of the same name. The two are built from one repository and released under one version, and their engines select byte-identical stimuli under the deterministic matching methods.

Installation

lexsync is on CRAN:

install.packages("lexsync")

The development version comes from this repository, where the package sits in the R_workflow/ subdirectory:

# install.packages("remotes")
remotes::install_github("pablobernabeu/lexsync", subdir = "R_workflow")

Quick start

A design names the conditions, the dimensions to match and the number of items, alongside the filters that narrow the lexicon to a candidate pool. The example below runs a high- against low-frequency contrast on the English lexicon bundled with the package, so it needs no download and no corpus of your own.

library(lexsync)

schema <- yaml::read_yaml(
  system.file("extdata", "schema.yaml", package = "lexsync")
)
lex <- load_lexicon(
  system.file("extdata", "en_example.csv", package = "lexsync"),
  schema, language = "english"
)

design <- list(
  name = "quick_start", language = "english", n_per_condition = 60,
  pool_filters = list(length = c(3, 8), frequency = c(3.8, 7.0)),
  conditions = list(
    list(name = "high_frequency", define_by = list(frequency = c(5.2, 7.0))),
    list(name = "low_frequency",  define_by = list(frequency = c(3.8, 4.4)))
  ),
  match_on = list("length", "n_density", "old20"),
  counterbalance = list(lists = 1)
)

pool <- build_pool(lex, design$pool_filters)
stim <- match_stimuli(pool, design, schema)

# What the match actually achieved, as effect sizes with confidence intervals
# and a complementary equivalence test.
match_report(stim, c("length", "frequency", "n_density", "old20"), schema)

Showing equivalence needs enough items. At the default bound and alpha, no dimension that varies can pass with fewer than 23 items per condition.

The Get started vignette works through the same example with its output, and the other articles each cover one part in depth: matching and designs, experiments and triggers and reproducibility and parity.

Apps and demonstrations

Two browser front-ends in the repository’s apps/ directory let a researcher assemble a design without writing code, run the pipeline and read the matched stimuli, the realised-control report and the materials datasheet. A Shiny app wraps this package and a Streamlit app wraps the Python twin. Each exports the design configuration and the code that reproduces the run. Both call their engine directly and so need a local install. The app walks through the Shiny one control by control, and apps/README.md covers launching either of them.

Every worked design in the repository is also published beside the documentation as a browser experiment. All 22 are listed at the demos index, and a design with several counterbalancing versions has a link for each. The lexical-decision demonstration is a single HTML file written by the same pipeline as the ‘PsychoPy’ and ‘OpenSesame’ scripts. It is self-contained apart from the ‘jsPsych’ library, which it loads from a CDN.

Citation

citation("lexsync")

The DOI that CRAN assigned to the package is https://doi.org/10.32614/CRAN.package.lexsync, and it covers every version. The 0.1.0 release on CRAN was built before the DOI existed, so the reference it prints gives the repository’s address and no DOI. Version 0.1.1 and later print the DOI.

The repository also holds a CITATION.cff, which GitHub uses for its ‘Cite this repository’ button. It describes both packages, so it gives the concept DOI of the Zenodo archive that holds every GitHub release of both. It also lists each package’s identifiers, the DOI above among them. A manuscript describing lexsync is in preparation.

Cite the corpus as well as the software. The corpora are third-party work with their own terms, and each is credited, with its licence and retrieval date, in corpora/ATTRIBUTION.md.

Licence

MIT. The bundled corpus derivatives are released under CC BY-SA 4.0 instead, as recorded in LICENSE-DATA.

Contributing

Issues and pull requests are welcome, on the issue tracker of the repository that holds both twins. A report that includes the design YAML and the run log can be acted on, because together they record the inputs and every step that ran.