Add Data and Data Dictionary

Add Data File

You can now download the data set we have prepared for you and put it into your project folder:

data.csv

palmerpenguins: Palmer Archipelago (Antarctica) Penguin Data

The data set is from the package palmerpenguins (v0.1.1) and contains the recorded bill lengths and sex of penguins living on three islands in the Palmer Archipelago, Antarctica. It was made available by Allison Horst, Alison Hill, and Kristen Gorman under the license CC0 1.0. For educational purposes, we added the fictitious column cuteness.

Important 1: Consider Legal Restrictions Before Sharing

Everything you put into the project folder will be shared publicly. For reasons of reproducibility, this should include the data you analyze. Of course, you should only share them to the extent you are allowed to. Besides copyright and similar rights, you need to take into account applicable privacy laws (e.g., the GDPR for European citizens) and contractual obligations (e.g., with your data provider).

Privacy laws and contractual obligations may require you to create an anonymized or synthetic data set¹, in which case you should provide a reference to a repository where the originally measured data can be obtained from. For further information, you can watch the talk “Data anonymity” by Felix Schönbrodt recorded during the LMU Open Science Center Summer School 2023 and have a look at the accompanying slides. Another resource to look at is the presentation “Creating reproducible packages when data are confidential” by Vilhuber (2024).

Let’s take a first look at our data:

dat <- read.csv("data.csv")
str(dat)

R Console

'data.frame':   344 obs. of  9 variables:
 $ species          : int  1 1 1 1 1 1 1 1 1 1 ...
 $ island           : int  3 3 3 3 3 3 3 3 3 3 ...
 $ bill_length_mm   : num  39.1 39.5 40.3 -99 36.7 39.3 38.9 39.2 34.1 42 ...
 $ bill_depth_mm    : num  18.7 17.4 18 -99 19.3 20.6 17.8 19.6 18.1 20.2 ...
 $ flipper_length_mm: int  181 186 195 -99 193 190 181 195 193 190 ...
 $ body_mass_g      : int  3750 3800 3250 -99 3450 3650 3625 4675 3475 4250 ...
 $ sex              : int  2 1 1 -99 1 2 1 2 -99 -99 ...
 $ year             : int  2007 2007 2007 2007 2007 2007 2007 2007 2007 2007 ...
 $ cuteness         : int  2 3 7 3 7 8 7 2 1 10 ...

We can see that the variables species, island, and sex are stored as integers:

• species
  • 1 = Adelie
  • 2 = Chinstrap
  • 3 = Gentoo
• island
  • 1 = Biscoe
  • 2 = Dream
  • 3 = Torgersen
• sex
  • 1 = female
  • 2 = male

Further, missing values are stored as -99. We need to document this information somewhere!

Add a Data Dictionary

Whether or not distributing the data set, it is important to document the meaning (e.g., units) and values of its variables. This is typically done with a data dictionary (also called a codebook).

The recommendation for data dictionaries vary between fields – both in terms of the recommended content (i.e., what exactly should be documented) and the technical implementation (i.e., which file formats should be used).

For the purpose of this exercise, we keep it easy and propose that you manually create a file with the data dictionary (e.g., as a table in .xlsx, .docx, .ods, or as a Markdown table), documenting only the bare minimum.

Tip 1: Creating data dictionaries using R

Our in-depth supplementary material “Generation of Data Dictionaries Using R” explains how you can create a data dictionary with R. This advanced chapter also contains a section on how to create machine-readable data dictionaries.

A bare minimum data dictionary

Most standards for data dictionaries require at least this information for each variable in your data set:

• name: Column name of the variable in the data set
• label: Short title for the variable
• description: Brief description of what the variable measures or represents
• item_text: Exact wording of a question in a survey
• values: A mapping of stored answers to their meanings (especially for categorical variables). For example: 1 = male, 2 = female, 9 = missing
• units: The units of measurement (only for numeric variables). For example: kg, USD, years

Here’s an example from a different data set, with one row for each variable:

name	label	description	item_text	values	units
gender	Gender	self‑identified gender		1 = male, 2 = female, 3 = other, 9 = missing
age	Age	age in years		-99 = Not answered	years
blood_pressure	Blood Pressure (systolic)	systolic blood pressure		-99 = Not answered	mmHg
life_satisfaction	Life Satisfaction	5-point scale	How satisfied are you with your life?	1 = very dissatisfied, 2 = dissatisfied, 3 = neutral, 4 = satisfied, 5 = very satisfied, -99 = not answered

You can download this example data dictionary as an ODS file here.

Depending on the type of data, it may also be necessary to describe sampling procedures (e.g., selection criteria), measurement instruments (e.g., established questionnaires), appropriate weighting, already applied preprocessing steps, or contact information.

Practical Exercise: Add your own data dictionary

Now it’s your turn. Fill in the missing information (denoted by a bold question mark “?”) in the following data dictionary.

Show data dictionary

name	label	description	item_text	values	units
species	Species	Penguin species		1 = Adelie, 2 = Chinstrap, 3 = Gentoo, -99 = missing
island	Island	Island in Palmer Archipelago, Antarctica where individual was observed		1 = Biscoe, 2 = Dream, 3 = Torgersen, -99 = missing
bill_length_mm	Bill length	Length of the bill (beak)		-99 = missing	mm
bill_depth_mm	Bill depth	?		-99 = missing	mm
flipper_length_mm	Flipper length	Length of the flipper		-99 = missing	mm
body_mass_g	?	Body mass		-99 = missing	?
sex	Sex	Sex of the penguin		1 = female, 2 = male, -99 = missing
?	Year	Study year
cuteness	Cuteness	Subjective cuteness rated on 10-point scale	How cute do you think this penguin is?	1 = not at all, ? = extremely

data-dictionary.ods

Then save the data dictionary in the same folder as the actual data set file.

Tip 2: Data dictionary for penguins data set (Solution)

name	label	description	item_text	values	units
species	Species	Penguin species		1 = Adelie, 2 = Chinstrap, 3 = Gentoo, -99 = missing
island	Island	Island in Palmer Archipelago, Antarctica where individual was observed		1 = Biscoe, 2 = Dream, 3 = Torgersen, -99 = missing
bill_length_mm	Bill length	Length of the bill (beak)		-99 = missing	mm
bill_depth_mm	Bill depth	Depth of the bill (beak)		-99 = missing	mm
flipper_length_mm	Flipper length	Length of the flipper		-99 = missing	mm
body_mass_g	Mass	Body mass		-99 = missing	g
sex	Sex	Sex of the penguin		1 = female, 2 = male, -99 = missing
year	Year	Study year
cuteness	Cuteness	Subjective cuteness rated on 10-point scale	How cute do you think this penguin is?	1 = not at all, 10 = extremely

You can download the solution here.

Practical Exercise: Add Data Citation and Attribution

All data relied upon should be cited in the manuscript to allow for precise identification and access. Please add an appropriate citation for the data set to the manuscript where it says “cite data here”.

Tip 3: Citing the Data Set (Hint)

You can find an appropriate BibTeX entry on the palmerpenguins package website.

Tip 4: Citing the Data Set (Solution)

Copy the following BibTeX entry to the file Bibliography.bib:

Bibliography.bib

@Manual{horst2020,
  title = {palmerpenguins: Palmer Archipelago (Antarctica) Penguin Data},
  author = {Allison Horst and Alison Hill and Kristen Gorman},
  year = {2022},
  note = {R package version 0.1.1},
  url = {https://allisonhorst.github.io/palmerpenguins/},
}

Then, find the line in the manuscript that says “cite data here” and replace it with a sentence such as the following:

Manuscript.qmd

The analyzed data are by @horst2020.

Render the document to check that the citation is displayed properly.

Terminal

quarto render Manuscript.qmd

While citation happens in the manuscript for reasons of academic integrity and reproducibility, to comply with any licenses you also may need to provide attribution within your project folder. Even though the data file we use here does not require attribution, we recommend adding a short paragraph to LICENSE.txt:

LICENSE.txt

The penguins data stored in "data.csv" by Allison Horst, Alison Hill, and Kristen Gorman available from <https://allisonhorst.github.io/palmerpenguins/> are licensed under CC0 1.0: <https://creativecommons.org/publicdomain/zero/1.0/>

Wrap up

Congrats! You documented your data set and cited it correctly.

To finalize this step, you can go through the commit routine:

Terminal

git status
git add .
git commit -m "Add data"

References

Vilhuber, L. (2024, October 14). Creating reproducible packages when data are confidential. https://labordynamicsinstitute.github.io/reproducibility-confidential/; Zenodo. https://doi.org/10.5281/zenodo.13927702

Footnotes

1. For example, using Amnesia, ARX, sdcTools, Synthpop, OpenDP, or Greenmask.