README e Data dictionary

Parole chiave: nomi file cartelle naming spazi accenti convenzione rinominare; formato CSV xlsx Excel sav SPSS mat proprietario aperto TXT JSON; struttura raw grezzi scripts output alberatura; README leggimi documentare documentazione; data dictionary codebook colonne variabili unità codifica significato.

Dati, nomi e formati

No

Dati definitivi (2).xlsx
analisi finale.R
questionarioEtà.csv

Sì

gonogo_data.csv
02_analysis_gonogo.R
demographics.csv

Regole generali

• Niente spazi, accenti o caratteri speciali nei nomi di file e di variabile: rompono gli script, i link e i trasferimenti fra sistemi operativi.
• Numeri con lo zero davanti (01_, 02_): altrimenti 10_ viene prima di 2_.
• Il nome dice cosa contiene.
• Se serve una versione, usate _v1, _v2, o meglio ancora usate git.
• Usare separatori e maiuscole in modo sistematico e significativo, non a caso: questo_e_snake_case, questoInveceECamelCase. Scegliete una convenzione e tenetela.

Regole tradotte e adattate dal sito di BIDS e dal corso di Research Data Management di DataLad.

In che formato salvarli

Un formato proprietario (.xlsx, .mat) si apre solo con il programma che l’ha creato: bisogna averlo, spesso a pagamento. Un formato aperto e testuale (.csv, .tsv, .txt, .json) si apre con qualunque strumento e si legge anche a occhio.

No

• dati.xlsx (Excel)
• codebook.docx

Sì

• dati.csv
• dati_dictionary.csv, codebook.txt
• README.txt o README.md

L’export originale dello strumento si tiene in data/raw/ come sola lettura; accanto si salva la versione in formato aperto.

Struttura

progetto/
├── README.md                       cosa c'è qui dentro e come si usa
├── LICENSE                         a quali condizioni
├── data/
│   ├── raw/                        dati grezzi: SOLA LETTURA, mai modificati
│   └── processed/
│       ├── gonogo_data.csv         i dati puliti, prodotti dagli script
│       └── gonogo_dictionary.csv   una riga per ogni colonna di gonogo_data.csv
├── scripts/
│   ├── 01_cleaning.R
│   └── 02_analysis.R
├── materials/                      stimoli, questionari, protocolli
├── output/
│   ├── figures/
│   └── tables/
└── docs/                           preregistrazione, preprint, ...

README

È il file che risponde alle domande che una persona si fa prima di poter usare qualunque altra cosa ci sia nella cartella.

Sta nella root del progetto/cartella ed è in Markdown o .txt.

Sezione	Risponde a
Titolo e autori (con ORCID)	Di chi è questo lavoro, e a chi scrivo se qualcosa non torna
Di cosa si tratta	Che studio è, quando sono stati raccolti i dati
Contenuto dei file	Cosa c’è nella cartella, file per file
Come leggere i dati	Cosa mi serve per accedere ai dati?
Come riprodurre	In che ordine girano gli script, con che software, cosa producono
Licenza	A quali condizioni si può riusare, e cosa vale per cosa
Come citare	C’è una citazione per il progetto?/un DOI?
Materiali collegati	DOI dell’articolo, della preregistrazione, del codice

Data dictionary

Il README descrive il progetto. Il data dictionary descrive ogni singola colonna dei vostri dati: una riga per variabile, in un file a parte (<nome-dataset>_dictionary.csv). Per esempio:

Colonna	Cosa ci va	Esempio
variable_name	Il nome esatto della colonna, carattere per carattere	rt
label	Che cosa misura	Tempo di reazione
type	integer, numeric, string, categorical, date, boolean	numeric
unit	Unità di misura. Vuoto se non ne ha	milliseconds
allowed_values	Intervallo o elenco dei valori possibili	200-2000
coding	Il significato di ogni codice, per le categoriali	1 = Psicologia; 2 = Economia
missing_values	Come sono rappresentati	cella vuota o NA?
source	Da dove viene il dato: strumento, questionario, calcolo	PsychoPy
notes	Decisioni prese, anomalie, avvertenze	…