Data Management

Tiptl;dr

Read this book by Chrystal Lewis from cover to cover (Lewis, 2024), and check out here fabulous blog posts.

Data management is the least glamorous part of the research workflow and probably one of the most foundational. The decisions made about how to structure, name, and document data before and during collection determine how smoothly everything downstream goes, as well as the degree to which FAIR principles are satisfied. Retrofitting good data management onto a badly organised dataset is painful. Starting with it costs very little. And it is something that my team and I could very much improve upon.

This is another big topic, one that fills an entire book (Lewis, 2024). Here, I just highlight five aspects that do not cost too much time or effort, but really add value in our experience.

  1. A data management plan.
  2. A project-level README file.
  3. Data dictionaries.
  4. A style guide.
  5. Open file formats.

And once you set these up for one project, many of the basic features generalise to other similar projects. This means that you can benefit form efficiency savings since they do not need to be created from scratch for every project.

The data management plan

Data management plans typically consist of a short document (< 5 pages), which is written before the data are collected, and that details the key aspects of how the data will be managed. Use the data management plan to focus your team’s efforts on setting up a roadmap to achieving FAIR data. And keep it in the project repository so that team members can see it and others can see it once the project is made public. Data management plans are becoming more common as funders and ethical committees seek assurance that the data will be managed safely and efficiently.

A project-level README file

As already mentioned in the Infrastructure section, each project has a README file at the root directory. A README file outlines details of the repository, such as folder and file structures, as well as requirements for using the data and code. When anyone lands on a project folder, including future you, then they would immediately be directed to the README file to be oriented to what the repository contains. In our experience, the information in a README file is typically already known and written down somewhere, such as in a lab notes document. Therefore, routinely writing a README file just encourages the team to write these notes in a more consistent way and in one place. In our experience, if baked on from the start of a project, it does not create “extra work”, it just forces you to work more consistently.

Data dictionaries

A data dictionary is a standardised way of reporting features of all variables in a dataset. Every person who has worked with behavioural data has at some point encountered a dataset where it is unclear which way round the coding goes. A data dictionary makes that unambiguous. To make this concrete, consider a typical reaction time dataset with five variables. First, we simulate the data and take a look at the first few rows.

Table 7.1: First six rows of a simulated reaction time dataset.
subj item condition rt acc
01 01 congruent 475 1
01 01 incongruent 738 1
01 02 congruent 645 1
01 02 incongruent 669 0
01 03 congruent 530 1
01 03 incongruent 577 1

The dataset has 200 rows (10 participants × 10 items × 2 conditions) and 5 variables. Notice that subj and item are zero-padded strings rather than integers. This is a small but important choice that ensures correct alphabetical sorting and avoids accidental arithmetic on ID variables.

Now here is the corresponding data dictionary. Every variable is documented with its name, a plain-language label, type and format, allowable values, units where applicable, and whether it is a primary collected variable or derived from other variables.

Table 7.2: Data dictionary for the simulated reaction time dataset.
Variable Label Type Format Allowable values Origin
subj Participant identifier character zero-padded string (e.g. '01') 01 – 10 primary
item Stimulus item identifier character zero-padded string (e.g. '01') 01 – 10 primary
condition Trial condition character string congruent, incongruent primary
rt Reaction time numeric milliseconds (ms) positive numeric primary
acc Response accuracy integer binary 0 = incorrect, 1 = correct primary

A few things worth noting about this dictionary:

  • The subj and item columns are documented as character strings, not integers, which reflects how they are actually stored.
  • The acc column documents the coding explicitly (0 = incorrect, 1 = correct).

The dictionary itself should be stored as a plain CSV file alongside the data. That way it is machine-readable, version-controlled, and readable by anyone without specialist software.

A style guide

Adopting a style guide within a lab aids in standardisation within and across projects. A style guide simply means consistent and standardised way of doing things, such as naming folder and files. For example, Lewis (2024) suggests being consistent in the following processes:

  1. Directory structures.
  2. File naming.
  3. Variable naming.
  4. Assigning variable values.
  5. Writing code.

Although this seems a bit fussy, it makes your data science life so much easier. And like any other standardisation procedure, it makes it so much easier for collaborators, lab members and anyone else to quickly get on board with your data science workflow.

Open data formats

Data should be stored in open (non-proprietary) file formats, such as CSV for tabular data, so that they can be accessed by any software.