Core Concepts
A handful of terms show up everywhere in PsyCloud — in Studio, in the SDKs, and in the data you export. This page is the canonical glossary and mental model.
The building blocks
| Term | What it is |
|---|---|
| Study | The whole experiment — an ordered set of phases. |
| Phase | A stage of the study: instructions, a practice block, the main task, a debrief. Static phases show one screen once; trial phases generate many trials. |
| Factor | A variable that defines conditions (e.g. congruency = congruent / incongruent). |
| Trial | One generated unit of a trial phase — one presentation of that phase's screen. |
| Screen | The reusable template shown for each trial: an ordered sequence of steps and components. |
| Step | One timed segment of a screen — a fixation, a stimulus, a response window, feedback. |
| Component | A thing on screen: text, image, shape, or a response collector (keypress, slider, button…). |
| Binding | The connection that fills a component property from trial data — e.g. trial.word → a text's content. |
| Bundle | The compiled, runnable artifact (design + screens + bindings + assets). The shared format across Studio and the SDKs. |
| Release | An immutable, versioned bundle published for participants to run. |
| Run | A deployment of a release tied to a recruitment target. |
| Session | One participant's data for a run. |
| Event | A single recorded action within a trial (stimulus shown, key pressed, …) in the telemetry stream. |
How trials are made
Trial phases don't store a fixed list of trials — they generate them from a design. You define factors, then a pipeline of steps transforms them into concrete trial rows:
Cross the factors into conditions → sample or repeat to reach a trial count → derive computed columns → shuffle into a randomized order.
The resulting rows are exactly the data that gets bound into the screen. (Studio shows this as
the Trial Design tab; in code it's the factors() → cross() →
derive() → shuffle() chain.)
Authoring and the run lifecycle
You author a study (in Studio or code), preview it against the runtime, launch it (validate → publish a release → host a run → recruit), then monitor sessions and export data. The same lifecycle applies no matter how you authored.
Authoring and previewing work entirely offline against a local draft. Publishing a release, hosting runs, recruiting, and exporting collected data require a connection to the PsyCloud backend.
Reproducibility
Randomization in PsyCloud is deterministic: it uses stable, explicit seeds and clear allocation policies, so a study can be reproduced and a participant's sequence can be reconstructed. Counterbalancing is declared explicitly rather than left to chance.