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.

At any point, the {} Preview button in the corner shows the metadata file as it stands so far.

Project info

Give the dataset a name (required — it identifies the dataset and names the folder you download) and a plain-English description of what it contains. The optional fields — license, funder, keywords, citation — cover the rest of the metadata Psych-DS recommends.

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.

Upload your data

Click Choose folder to pick the folder holding your data files, or Upload .zip if they're in an archive. Then click Process files — each file gets a ✓, a — (skipped), or a ✗ (couldn't be read) as it goes.

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 CSV and given a Psych-DS name (e.g. data/subject-sub01_data.csv).

Your original files are never modified. Whenever a file has to change on the way in — a JSON file converted to CSV, or a CSV renamed or rewritten — the untouched original is also saved under data/raw/ in the download.

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

Some trials store a whole list inside a single row — a survey trial holding several responses, for example. Those lists get pulled out into their own CSV tables, and each extracted row needs a way to point back to the trial it came from. A join key is the column (or combination of columns) that does this: its values must be different for every row.

The wizard tries trial_index first. If that isn't enough — most often because you merged several participants into one file, and trial_index starts over at 0 for each of them — it asks you to pick. Columns marked sufficient alone (often participant_id) are enough by themselves; tick columns until every row is unique, then choose Apply and process files. You can revisit the choice later with Change join keys.

Variables

The wizard finds 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.

  • Anything it couldn't describe is grouped under Missing descriptions at the top, with a running count of how many you've filled in. Everything else sits under Other variables.
  • Click a variable to open it. It has a Description box and a Type dropdown; both save as you type.
  • Filling these in is optional.

Authors

Add the people who contributed to the dataset — optional, and you can come back to it later. Type a name, then click away from the box to save it; use + Add another author for the next one. Open Optional fields on a card to add an ORCID, and the rarely-needed given name, family name, and author type.

Adding lots of authors at once

+ Add multiple authors at once lets you paste a list — one name per line, with an optional ORCID after a comma. Any ORCID that isn't in the 0000-0001-2345-6789 format is skipped, and the wizard tells you which names it affected.

Review & download

Read through the generated dataset_description.json, go back to any step to change something, then download.

  • Download <project-name>.zip gives you a complete Psych-DS project: dataset_description.json, README.md, CHANGES.md, and your data/ folder. (If you didn't upload any data, you get a Save dataset_description.json button instead.)
  • Validate dataset checks the result against Psych-DS right there in your browser and lists any errors and warnings. It needs an internet connection to fetch the standard's schema.
Errors and warnings

Errors have to be fixed — the dataset isn't Psych-DS compliant until they are. Each one names the rule it broke and the files or columns at fault.

Warnings never make validation fail. They point at recommended metadata or files you haven't added — an optional field, a missing README.md — so treat them as a checklist rather than a problem.

The check covers exactly what you're about to download, README.md and CHANGES.md included, so there's no need to validate the project again afterwards.

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