Introduction to unheadr

When we work with other people’s data, we often have to struggle through multiple unexpected steps before we get to a flexible, usable structure. Popular ways of structuring and presenting data can place content beyond the reach of code-based routines to tackle repetitive tasks efficiently.

Package functions

The functions in unheadr help us rework data shared by other people, from a human-readable structure to a tidier machine-readable structure on which we can perform common data manipulation tasks.

Data frames and tibbles

Here is how unheadr works with tibble and data frame objects that suffer from common issues such as:

Embedded subheaders are usually grouping variables embedded into another variable, used to show hierarchical data or create small multiples of data.

A simple example would be a coffee shop menu:

The beverage type is embedded in the ‘drinks’ variable. If we can match them with regular expressions, we can move the grouping values into their own variable using untangle2()

Broken values usually happen when we’re pressed for space.

For whatever reason, the entries for the Barcelona 1992 and London 2012 Olympics are broken across two contiguous rows and NAs are used as padding in the other variables.

In this case, we can use unbreak_vals() to ‘unbreak’ the lines in the ‘Games’ variable, matching the strings that start with numbers.

Wrapped columns often happen when we merge cells in spreadsheets or use table formatting in a word processor, resulting in empty or NA values used to pad all the vertical space.

We can unwrap the ‘teams’ values into a single string using unrwap_cols().

This is more or less the opposite to separate_rows() from tidyr.

Broken rows have values of two contiguous rows broken up and padded with empty or NA values.

In this case, we can match any value in any variable along the row that has broken values.


unheadr also includes a function for flattening font and cell formatting in spreadsheet files into character strings in the corresponding cell.

The example file bundled with the unheadr looks like this:

Font formatting and cell highlighting is being used to label an embedded grouping variable (meaningful formatting). The annotate_mf() function flattens the formatting into a character string describing the formatting. The HTML code of the colors used for cell highlighting is also included.

Further reading

The underlying reasoning, background, and possible uses of unheadr are now described in this publication:

Verde Arregoitia, L. D., Cooper, N., D’Elía, G. (2018). Good practices for sharing analysis-ready data in mammalogy and biodiversity research. Hystrix, the Italian Journal of Mammalogy, 29(2), 155-161. Open Access, 10.4404/hystrix-00133-2018.