Skip to main content

Using the web wizard

The wizard — one click away in the top nav — is a browser-based tool that turns your raw jsPsych data into a Psych-DS compliant project. Everything runs locally: your data never leaves your computer. Prefer the command line? See Using the CLI.

When you open it, pick a starting point:

  • Create new project — start from scratch with your data files (the path below).
  • Open existing project — upload an existing dataset_description.json to keep editing it, or to refresh the metadata after collecting more data.

Project info

Give the dataset a name (required — it becomes the identifier and the downloaded folder name) and a plain-English description. Optional fields — license, funding source, keywords, citation — fill in the recommended Psych-DS metadata.

Starting from an existing project?

You can upload an existing dataset_description.json here to pre-fill every field. When an uploaded value differs from something you've already typed, the wizard shows a before/after comparison so you can choose what to keep.

Data — upload your raw data files

Click Choose folder to pick a directory of data files, or Upload zip to upload a .zip. Each file shows a status indicator once it's processed. Your originals are never modified.

Which file formats can I upload?
  • CSV — kept as-is.
  • JSON array ([ {…}, {…} ]) — the standard jsPsych export.
  • { "trials": [...] } wrapper — e.g. OSF exports; unwrapped automatically.
  • JSON-Lines (.jsonl) — one JSON value per line.

JSON and JSON-Lines are converted to Psych-DS-named CSV (e.g. data/subject-sub01_data.csv) so the validator and the downloaded zip see compliant tables. Your originals are preserved untouched under data/raw/ whenever the staged output is not a byte-for-byte, same-named copy of the upload — converted JSON, re-serialised CSVs, and renamed CSVs alike.

What's a "join key" and when will I be asked for one?

If your files contain nested arrays (e.g. a survey trial holding multiple responses), each nested item has to be matched back to its parent row to store it as a flat CSV. A join key is a column whose values are unique for every row.

The wizard checks whether trial_index uniquely identifies each row; if it doesn't (for example, merged multi-participant files where trial_index resets to 0 per person), a chooser appears. Columns tagged sufficient alone make every row unique by themselves (often participant_id); pick one or more until each row is uniquely identified, then Apply and process files. A Re-configure join keys button stays available if you need to change it later.

Variables

The wizard detects every variable in your data and looks up what each one means from the jsPsych plugin that produced it. Review the list and fill in anything it couldn't identify automatically.

  • Variables with unknown descriptions appear expanded at the top; known ones start collapsed (Expand all / Collapse all toggles them).
  • Each row has a Description field and a Type dropdown — editing either updates the metadata immediately.

Authors

Add the people who contributed to the dataset. Click Add author, type a name, and press Tab to commit it. Expand a row for optional fields: given/family name, author type, and ORCID.

Adding lots of authors at once

Bulk import lets you paste a list of names (one per line, optionally followed by an ORCID) to add many authors at once. Invalid ORCIDs are flagged with a warning.

Review & download

Inspect the generated dataset_description.json in the syntax-highlighted preview, then download your project.

  • Download <project-name>.zip gives a complete Psych-DS project: dataset_description.json, README.md, CHANGES.md, and your data/ folder. (No data files? A Save dataset_description.json button appears instead.)
  • Validate dataset runs the Psych-DS validator in your browser and lists any errors and warnings inline.
About the validation warnings

Missing README / CHANGES warnings are expected in the in-browser check — the downloaded zip includes both files, so they clear when you validate the unzipped folder with the Psych-DS web validator. The {} Preview pill (on every step except Review) opens a live JSON snapshot at any time.

Next: hit a snag? See Troubleshooting. Prefer scripting it? Using the CLI.