Installation¶

One-time setup to get the toolbox running on your own machine. This is the canonical copy of these steps — README.md in the repository keeps only the bare command block and a pointer here, so there is exactly one place this can drift.

Prerequisites¶

A git client to clone the repository — Git for Windows, GitHub Desktop, or an editor's built-in git support all work. (The conda environment created below pulls its own git binary in, so nothing later — the test suite, analysis provenance stamps — depends on whichever client you used to clone, or on it being on your system PATH.)
conda or a conda-compatible installer (e.g. Miniforge). The toolbox is developed and tested against one named environment, ssvep, built from environment.yml.
A machine that can open a desktop window (the GUI needs a display; a headless machine can still run the test suite and offline analysis scripts).

Install¶

Which repository to clone

The URL below is the toolbox's own source repository, which is not yet public ahead of its first release. If you were given a different repository URL — a course or teaching copy — clone that one instead and skip straight to cd; everything after that step is identical.

git clone https://github.com/NeuroCognitiveImagingLab/ssvep-toolbox.git
cd ssvep-toolbox
conda env create -f environment.yml
conda activate ssvep
pip install -e . --no-deps
pytest -q

If the last line runs and finishes without failures, the install is good — that is the whole verification step. Run it from the repository root, with the ssvep environment activated, any time you want to confirm the install still works (after a git pull, for instance).

Why `pip install -e . --no-deps`, exactly like that¶

-e (editable): the package is installed as a link back to this checkout rather than copied into the environment. Some of the toolbox's own path resolution depends on that — for example, the run-manifest reader locates schemas/ relative to the installed package's location, which only resolves correctly when the install is the checkout. A non-editable install (pip install .) breaks that lookup.

--no-deps: environment.yml already resolves every dependency you need — some (numpy, scipy, mne-base, …) as conda packages from conda-forge, the rest (PySide6, pyglet, pylsl, brainflow, …) through its own nested pip: section, which conda still solves and installs as part of creating the environment — resolved together as one consistent set. (It does not pin most versions — only python=3.11 and setuptools<81, the latter because brainflow still imports pkg_resources, which setuptools removed in 81. So the guarantee is internal consistency at solve time, not reproducibility across dates.) Running a plain pip install -e . afterward, without --no-deps, lets pip re-resolve those same packages from PyPI on top of what conda already installed. The two can build the same library differently (a different BLAS backend behind numpy is the one that bites hardest), and a mixed install can import cleanly and then fail the moment it does real work — see Troubleshooting for what that failure looks like when it happens at launch. --no-deps keeps every dependency the one environment.yml already resolved, whichever channel it came from.

If you ever reinstall without --no-deps by mistake, undo it the same way you'd fix any mixed environment: conda env remove -n ssvep and recreate it from environment.yml, then reinstall with the flag. There is no reliable partial fix once pip has overwritten a conda-built package.

Launching¶

Installing gives you three entry points. All three open the same window, on the same starting tab (Build run) — there's one unified app, not separate design/run programs:

ssvep-toolbox    # the desktop launcher: a splash screen, then the window (no console output on Windows)
ssvep-design     # identical to ssvep-toolbox, run from a terminal instead of a shortcut
ssvep-run        # the same window again, plus optional CLI flags (--serial-port, --board)

Run any of them from an activated ssvep shell. For what to do once it opens, see Getting started.

Desktop shortcut (Windows)¶

python scripts/create_desktop_shortcut.py

This writes an SSVEP Toolbox.lnk to the Desktop, pointing at the installed launcher, with the app's own icon (the icon ships committed in the repository; there is no need to regenerate it unless you are changing the icon design itself, via scripts/make_icon.py). Right-click it afterward to Pin to taskbar / Pin to Start if you want it there permanently.

The shortcut runs a console-less process — it cannot print anything, so if it ever fails silently, see Troubleshooting rather than guessing.

What a fresh clone does and doesn't know about you¶

A clone with no further setup runs generically: no institution stamped into recordings, no push destination, no pre-filled operator, mains frequency recorded as unknown rather than assumed. That is deliberate — nothing about installing or running the toolbox requires you to be part of any particular lab — and it is what Getting started is written against.

The first time you launch, the app notices there's no site profile (config/site.local.json) and asks, once, whether to set one up — "Use generic…" is the right answer for this walkthrough and for any machine that isn't a lab deployment; it writes a generic profile so you aren't asked again. If you are setting up a lab deployment (an institution, an ethics approval, a server to push to, an approved operator list), that prompt's "Set up a profile…" is where it starts — see Site profile for what each field does.

If something goes wrong¶

Troubleshooting covers the startup and acquisition failures that have actually happened, what caused each one, and what the toolbox now does about it.