Not every design has to be written as code. The repository carries a
Shiny front-end over this package which drives the whole workflow
through a browser tab, from choosing a paradigm to downloading the
stimuli, the realised-control report and the materials datasheet. It is
a front-end and nothing more. Every number it shows comes from the
installed lexsync package, never from a re-implementation,
and the design it assembles is an ordinary YAML file that you can save,
share and run from a script afterwards.
This article describes the app without running it, since the app needs a live server, so the code below is shown but not evaluated.
Launching it
The app is not part of the package. It lives in the repository, under
apps/r_shiny, beside the corpora and the example item
tables that it reads, so launch it from a clone. The interface needs
shiny, bslib and DT, and the download button needs zip. All four are
listed in the package’s Suggests.
install.packages(c("shiny", "bslib", "DT", "zip"))
shiny::runApp("apps/r_shiny", port = 8502)Run that from the root of the clone. The app looks for
corpora/derived/ in the working directory and then in the
two directories above it, and it finds the example item tables under
items/ the same way, so a launch from somewhere else leaves
it with no lexicon to offer. It opens at
http://127.0.0.1:8502.
The repository also carries a launcher for the terminal, which takes an optional port and is what a container or a headless session should use.
The launcher fixes the host and the port and never opens a browser itself. A server started with an auto-launched browser or an unbound port can exit the moment it is backgrounded, which is the usual reason an app appears not to stay up in an automated environment.
The sidebar
Whatever the paradigm, the same few fields sit in the sidebar.
‘Paradigm’ chooses between a factorial word contrast drawn from a
corpus, lexical decision with generated pseudowords, priming and
self-paced reading, the last two reading prepared items from a table.
‘Design name’ and ‘Language label’ become the slug that every written
file is named after, exactly as in a design file, so
my_design plus english gives
my_design_english_stimuli_R.csv and its companions.
‘Stimulus font’ overrides the presentation font, which matters for a
non-Latin script, and it reaches the design only when it differs from
the Courier New default, leaving the schema in charge
otherwise.
Under those the sidebar prints the version of lexsync that is running, with the reminder that the app runs the installed package. If that line disagrees with the version you expect, the app is reading a different install.
Describing the design
The main panel changes with the paradigm, since a corpus-matched contrast and a prepared item table need different things.
A factorial word contrast
‘Lexicon’ lists the derived corpora the clone holds under
corpora/derived/, which are English, Spanish, a Spanish
lexicon carrying grammatical gender, and Mandarin Chinese. Two sliders
then narrow the lexicon to the candidate pool the design will consider
at all, one for length in letters or characters and one for frequency in
Zipf. They are the design’s pool_filters, and they are a
step that matters, because matching never re-reads them.
The conditions are an editable table. Each row names a condition and
carves it out of the pool, either by a numeric window through the
dimension, lower and upper
columns or by a set of comma-separated values through
categories, which is what a categorical column such as the
gender of the Spanish lexicon needs. The optional
dimension2, lower2 and upper2
columns add a second factor to the same row, so one row can define a
full cell of a 2 × 2. Three presets fill the table in one click, a high
versus low frequency contrast, a dense versus sparse neighbourhood
contrast and a 2 × 2 of frequency by neighbourhood, and every cell stays
editable afterwards, so a preset is only a starting point.
Below the table sit the choices that govern the match itself. ‘Items
per condition’ sets how many stimuli each condition should hold.
‘Matching method’ offers the four the engine implements,
standardised_euclidean, joint,
mahalanobis and optimal. ‘Resampled disjoint
sets’ draws several matched sets that share no item, which is what lets
items be treated as a random factor, and zero switches it off. ‘Match
on’ picks the dimensions to equate across conditions, from length,
frequency, neighbourhood N, OLD20, syllable count and bigram frequency.
‘Counterbalancing lists’ sets how many lists the items are rotated
across.
The advanced panel underneath holds one tolerance window per matched dimension, the half-width in standard deviations of the band a candidate must fall inside. It is closed by default because the schema already carries a sensible default for every dimension, and a zero there leaves that default alone, where you might expect it to pin the window to nothing. Reproducing the exact window of a published study is the usual reason to touch the panel at all, and the panel itself gives the worked example that Matching, dimensions and designs discusses, a frequency k of 0.111 for a band of the mean plus or minus a ninth of a standard deviation.
Lexical decision
A lexical-decision design takes the same lexicon and pool filters and
then asks only for the number of items per condition, words and
pseudowords being equal in number, and for the generator.
letter_substitution, the engine default, changes as few
single letters as it can while keeping every bigram attested.
subsyllabic swaps whole onset, nucleus and coda
constituents in the manner of Wuggy (Keuleers & Brysbaert, 2010).
Both are deterministic, so the pseudowords are the same ones the package
would generate from a script.
Priming and self-paced reading
These two paradigms read prepared items instead of selecting any, so
no corpus and no matching are involved. The app uses the bundled example
table for the paradigm, items/priming_pairs_en.csv or
items/spr_sentences_en.csv, and asks only how many
counterbalancing lists to build.
Running it
‘Run design’ assembles the design, writes it to a
design.yaml in a temporary directory with the lexicon and
item paths resolved to absolute ones, and hands it to
run_pipeline() with the schema that ships inside the
package. Two conditions are checked first, that a lexicon has been
chosen where the paradigm needs one and that a factorial design defines
at least two conditions, and anything the pipeline itself refuses comes
back as the error the pipeline raised, in its own words. A successful
run reports how many rows were selected and opens the results.
Reading the results
The results arrive as six tabs, which between them cover what was selected, whether it is any good, what it will present and how to reproduce it.
‘Stimuli’ is the selected set as a table, the same one the run wrote to disk.
‘Realised control’ is the part that decides whether the set is usable. It reports Cohen’s d against the anchor condition for each controlled dimension, with its 90% confidence interval, the variance ratio and the verdict of the two one-sided tests procedure, then draws the absolute standardised mean difference per dimension as a bar chart with a dashed line at 0.5 standard deviations. Manipulated dimensions stand well above that line and matched ones sit near zero, so the chart shows immediately whether the matching worked. The per-condition descriptive statistics follow underneath. A design drawn from an item table produces no corpus-matching report, and the tab says as much where an empty table would otherwise sit.
‘Datasheet’ renders the materials datasheet for the run, carrying the provenance of the corpus, the checksums, the realised control and the pre-registration skeleton.
‘Experiment scripts’ offers one download per generated experiment,
the PsychoPy script, the OpenSesame .osexp and the jsPsych
HTML that runs in a browser, all three compiled from the same trial
description.
‘Reproducible code’ is what stops a session in the app from being a
dead end. It shows the design configuration as YAML, with
repository-relative paths such as corpora/derived/en.csv
rather than the temporary ones the run used, followed by the one-line R,
Python and command-line calls that reproduce the same operation. Saving
the YAML under the name the panel gives it and running any of those
three lines repeats the run outside the app.
‘Download’ packages the design and every artefact the run wrote, the stimuli, the reports, the datasheet, the run log and the three experiments, into a single archive named after the design.
What you leave with
A session in the app ends with the same artefacts a scripted run produces, which is why it was built as a front-end over the package and not as a tool of its own. The design YAML is portable across both engines, so a set assembled here can be reproduced by a collaborator working in Python, byte for byte under the deterministic matching methods. Reproducibility, parity and the materials datasheet covers what that guarantee promises and where it stops, and Matching, dimensions and designs reads the realised-control report column by column.