Psych-DS

BIDS per i dati psicologici

Requisiti minimi

Un dataset Psych-DS valido richiede:

  1. Una cartella data/ nella radice del progetto, che contiene i file di dati in CSV.
  2. Un file dataset_description.json nella radice, con esattamente questo nome, accanto a data/ e non dentro.
  3. I file di dati nominati a coppie chiave-valore, con suffisso _data.csv.

Il nome dei file

chiave1-valore1_chiave2-valore2_suffisso.estensione Il trattino lega una chiave al suo valore; l’underscore separa le coppie fra loro e dal suffisso finale.

In Psych-DS il suffisso è sempre data e l’estensione sempre .csv, quindi ogni file di dati finisce per _data.csv. Le coppie che stanno prima le scegliete voi: servono a dire di chi e di cosa sono quei dati.

study-stroop_subject-01_data.csv Lo stesso schema, riempito: studio “stroop”, partecipante 01.

Validi

study-stroop_subject-01_data.csv
participant-001_session-1_data.csv
version-alltrials_participant-001_data.csv
study-ZebraQuestionnaire_data.csv

Non validi

participant-summary.csv
  manca il suffisso _data.csv

year2024_data.csv
  manca il trattino fra chiave e valore

participant_001_data.csv
  underscore al posto del trattino

Subject-01_data.csv
  la chiave deve essere minuscola

Il file dei metadati

dataset_description.json usa il vocabolario di schema.org, lo stesso che i motori di ricerca leggono per indicizzare i dataset. Nella versione minima servono tre campi:

{
  "@context": "https://schema.org/",
  "@type": "Dataset",
  "name": "Dataset title",
  "description": "Description, of any length.",
  "variableMeasured": ["participant_id", "trial", "condition", "rt_ms"]
}
Importante

variableMeasured deve elencare esattamente tutti i nomi di colonna che compaiono nei vostri CSV.

È il data dictionary dell’esercizio 1, ma verificabile automaticamente. La documentazione smette di essere un file che si scrive alla fine e diventa qualcosa che non può andare fuori sincrono con i dati.

dataset_description.json come data-dictionary

Nella forma minima variableMeasured è un elenco di nomi. Schema.org permette però di sostituire ogni stringa con un oggetto PropertyValue, e a quel punto il data dictionary vero e proprio entra nei metadati:

"variableMeasured": [
  {
    "@type": "PropertyValue",
    "name": "rt_ms",
    "description": "Reaction time from stimulus onset to response",
    "unitText": "milliseconds",
    "minValue": 200,
    "maxValue": 3000
  },
  {
    "@type": "PropertyValue",
    "name": "condition",
    "description": "Congruency between word and ink colour",
    "value": "congruent | incongruent"
  }
]

Il validator

E’ possibile controllare se si sono seguiti standard caricando la cartella radice del progetto (es. stroop-attention/, non stroop-attention/data ) su: psych-ds.github.io/validator

Errori tipici

Sintomo Causa
“No dataset_description.json found” Il file è dentro data/, oppure avete selezionato la cartella sbagliata, oppure il nome ha una maiuscola o un .txt nascosto in coda
Un file di dati non viene riconosciuto Il nome non segue lo schema chiave-valore, o manca il suffisso _data.csv
“Column not found in variableMeasured” Una colonna dei CSV non è dichiarata nei metadati, oppure è scritta in modo leggermente diverso (spazi, maiuscole, accenti). variableMeasured` deve contenere l’unione dei nomi di colonna di tutti i CSV.
Il JSON non viene letto Virgola di troppo prima di una parentesi graffa

Quando conviene, e quando no

Ha senso

  • Dati sperimentali per singola prova, con molti partecipanti e file simili fra loro
  • Studi multi-sito o longitudinali, dove la struttura si ripete
  • Laboratori che producono molti dataset dello stesso tipo: si scrive uno script di lettura e vale per tutti

Non è la priorità

  • Un dataset unico, piccolo, molto particolare
  • Dati di neuroimaging: usate BIDS, che è lo standard di quel campo
  • Interviste qualitative, materiali eterogenei, video
  • Quando non avete ancora un README e un data dictionary: quelli vengono prima
Priorità

Un dataset con README e data dictionary ben fatti, ma senza standard, è largamente più utile di un dataset formalmente conforme a Psych-DS ma privo di documentazione.

Esempio

Due partecipanti, dodici prove ciascuno, compito Stroop.

stroop-attention/
├── dataset_description.json          obbligatorio, questo nome esatto
├── README.md
├── LICENSE
├── data/                             obbligatoria
│   ├── study-stroop_subject-01_data.csv
│   ├── study-stroop_subject-02_data.csv
│   └── raw/                          export originali, ignorati dal validator
│       └── subject-01_eprime_export.txt
└── analysis/
    └── 01_stroop_effect.R

La cartella data/raw/ serve a conservare gli export originali nei formati prodotti dai software di acquisizione (.txt, .edat3, .sav, .mat): il validator ne ignora il contenuto.

Neuroimaging: BIDS

Se lavorate con MRI, EEG, MEG o fNIRS, lo standard è BIDS: molto più prescrittivo, (validator, BIDS Apps, fMRIPrep). Depositando su OpenNeuro è di fatto obbligatorio.

Schema dei nomi dei file adattato dal sito di BIDS; regole ed esempio di dataset_description.json adattati dalla documentazione di Psych-DS.