Things that should be mentioned in this chapter:
rename_with, use with janitor example: “Alternatively, we can also read the data in first and then rename the columns to follow the
snake_caseformat with the
make_clean_names()function from the janitor package. This is a handy approach if you have too many columns and don’t want to write out the names of each, though it might not always result in the exact names you want for your columns, e.g. it won’t shorten column names, it will only convert them to snake case.”
library(tidyverse) #> ── Attaching packages ─────────────────────────────────────── tidyverse 1.3.1 ── #> ✔ ggplot2 3.3.5 ✔ purrr 0.3.4 #> ✔ tibble 3.1.6 ✔ dplyr 1.0.7 #> ✔ tidyr 1.1.4 ✔ stringr 126.96.36.19900 #> ✔ readr 2.1.1 ✔ forcats 0.5.1 #> ── Conflicts ────────────────────────────────────────── tidyverse_conflicts() ── #> ✖ dplyr::filter() masks stats::filter() #> ✖ dplyr::lag() masks stats::lag()
Before we get into the details of how readr reads files from disk, we need to take a little detour to talk about the
These functions take a character vector and return a more specialised vector like a logical, integer, or date:
str(parse_logical(c("TRUE", "FALSE", "NA"))) #> logi [1:3] TRUE FALSE NA str(parse_integer(c("1", "2", "3"))) #> int [1:3] 1 2 3 str(parse_date(c("2010-01-01", "1979-10-14"))) #> Date[1:2], format: "2010-01-01" "1979-10-14"
These functions are useful in their own right, but are also an important building block for readr. Once you’ve learned how the individual parsers work in this section, we’ll circle back and see how they fit together to parse a complete file in the next section.
Like all functions in the tidyverse, the
parse_*() functions are uniform: the first argument is a character vector to parse, and the
na argument specifies which strings should be treated as missing:
If parsing fails, you’ll get a warning:
x <- parse_integer(c("123", "345", "abc", "123.45")) #> Warning: 2 parsing failures. #> row col expected actual #> 3 -- no trailing characters abc #> 4 -- no trailing characters 123.45
And the failures will be missing in the output:
x #>  123 345 NA NA #> attr(,"problems") #> # A tibble: 2 × 4 #> row col expected actual #> <int> <int> <chr> <chr> #> 1 3 NA no trailing characters abc #> 2 4 NA no trailing characters 123.45
If there are many parsing failures, you’ll need to use
problems() to get the complete set.
This returns a tibble, which you can then manipulate with dplyr.
problems(x) #> # A tibble: 2 × 4 #> row col expected actual #> <int> <int> <chr> <chr> #> 1 3 NA no trailing characters abc #> 2 4 NA no trailing characters 123.45
Using parsers is mostly a matter of understanding what’s available and how they deal with different types of input. There are eight particularly important parsers:
parse_double()is a strict numeric parser, and
parse_number()is a flexible numeric parser. These are more complicated than you might expect because different parts of the world write numbers in different ways.
parse_character()seems so simple that it shouldn’t be necessary. But one complication makes it quite important: character encodings.
parse_factor()create factors, the data structure that R uses to represent categorical variables with fixed and known values.
The following sections describe these parsers in more detail.
It seems like it should be straightforward to parse a number, but three problems make it tricky:
People write numbers differently in different parts of the world. For example, some countries use
.in between the integer and fractional parts of a real number, while others use
Numbers are often surrounded by other characters that provide some context, like “$1000” or “10%”.
Numbers often contain “grouping” characters to make them easier to read, like “1,000,000”, and these grouping characters vary around the world.
To address the first problem, readr has the notion of a “locale”, an object that specifies parsing options that differ from place to place.
When parsing numbers, the most important option is the character you use for the decimal mark.
You can override the default value of
. by creating a new locale and setting the
parse_double("1.23") #>  1.23 parse_double("1,23", locale = locale(decimal_mark = ",")) #>  1.23
readr’s default locale is US-centric, because generally R is US-centric (i.e. the documentation of base R is written in American English). An alternative approach would be to try and guess the defaults from your operating system. This is hard to do well, and, more importantly, makes your code fragile: even if it works on your computer, it might fail when you email it to a colleague in another country.
parse_number() addresses the second problem: it ignores non-numeric characters before and after the number.
This is particularly useful for currencies and percentages, but also works to extract numbers embedded in text.
parse_number("$100") #>  100 parse_number("20%") #>  20 parse_number("It cost $123.45") #>  123.45
It seems like
parse_character() should be really simple — it could just return its input.
Unfortunately life isn’t so simple, as there are multiple ways to represent the same string.
To understand what’s going on, we need to dive into the details of how computers represent strings.
In R, we can get at the underlying representation of a string using
charToRaw("Hadley") #>  48 61 64 6c 65 79
Each hexadecimal number represents a byte of information:
48 is H,
61 is a, and so on.
The mapping from hexadecimal number to character is called the encoding, and in this case the encoding is called ASCII.
ASCII does a great job of representing English characters, because it’s the American Standard Code for Information Interchange.
Things get more complicated for languages other than English.
In the early days of computing there were many competing standards for encoding non-English characters, and to correctly interpret a string you needed to know both the values and the encoding.
For example, two common encodings are Latin1 (aka ISO-8859-1, used for Western European languages) and Latin2 (aka ISO-8859-2, used for Eastern European languages).
In Latin1, the byte
b1 is “±”, but in Latin2, it’s “ą”!
Fortunately, today there is one standard that is supported almost everywhere: UTF-8.
UTF-8 can encode just about every character used by humans today, as well as many extra symbols (like emoji!).
readr uses UTF-8 everywhere: it assumes your data is UTF-8 encoded when you read it, and always uses it when writing. This is a good default, but will fail for data produced by older systems that don’t understand UTF-8. If this happens to you, your strings will look weird when you print them. Sometimes just one or two characters might be messed up; other times you’ll get complete gibberish. For example:
x1 <- "El Ni\xf1o was particularly bad this year" x2 <- "\x82\xb1\x82\xf1\x82\xc9\x82\xbf\x82\xcd" x1 #>  "El Ni\xf1o was particularly bad this year" x2 #>  "\x82\xb1\x82\xf1\x82ɂ\xbf\x82\xcd"
To fix the problem you need to specify the encoding in
parse_character(x1, locale = locale(encoding = "Latin1")) #>  "El Niño was particularly bad this year" parse_character(x2, locale = locale(encoding = "Shift-JIS")) #>  "こんにちは"
How do you find the correct encoding?
If you’re lucky, it’ll be included somewhere in the data documentation.
Unfortunately, that’s rarely the case, so readr provides
guess_encoding() to help you figure it out.
It’s not foolproof, and it works better when you have lots of text (unlike here), but it’s a reasonable place to start.
Expect to try a few different encodings before you find the right one.
guess_encoding(charToRaw(x1)) #> # A tibble: 2 × 2 #> encoding confidence #> <chr> <dbl> #> 1 ISO-8859-1 0.46 #> 2 ISO-8859-9 0.23 guess_encoding(charToRaw(x2)) #> # A tibble: 1 × 2 #> encoding confidence #> <chr> <dbl> #> 1 KOI8-R 0.42
The first argument to
guess_encoding() can either be a path to a file, or, as in this case, a raw vector (useful if the strings are already in R).
Encodings are a rich and complex topic, and I’ve only scratched the surface here. If you’d like to learn more I’d recommend reading the detailed explanation at http://kunststube.net/encoding/.
R uses factors to represent categorical variables that have a known set of possible values.
parse_factor() a vector of known
levels to generate a warning whenever an unexpected value is present:
fruit <- c("apple", "banana") parse_factor(c("apple", "banana", "bananana"), levels = fruit) #> Warning: 1 parsing failure. #> row col expected actual #> 3 -- value in level set bananana #>  apple banana <NA> #> attr(,"problems") #> # A tibble: 1 × 4 #> row col expected actual #> <int> <int> <chr> <chr> #> 1 3 NA value in level set bananana #> Levels: apple banana
You pick between three parsers depending on whether you want a date (the number of days since 1970-01-01), a date-time (the number of seconds since midnight 1970-01-01), or a time (the number of seconds since midnight). When called without any additional arguments:
parse_datetime()expects an ISO8601 date-time. ISO8601 is an international standard in which the components of a date are organised from biggest to smallest: year, month, day, hour, minute, second.
parse_datetime("2010-10-01T2010") #>  "2010-10-01 20:10:00 UTC" # If time is omitted, it will be set to midnight parse_datetime("20101010") #>  "2010-10-10 UTC"
This is the most important date/time standard, and if you work with dates and times frequently, I recommend reading https://en.wikipedia.org/wiki/ISO_8601
parse_date()expects a four digit year, a
/, the month, a
/, then the day:
parse_date("2010-10-01") #>  "2010-10-01"
parse_time()expects the hour,
:, minutes, optionally
:and seconds, and an optional am/pm specifier:
Base R doesn’t have a great built in class for time data, so we use the one provided in the hms package.
If these defaults don’t work for your data you can supply your own date-time
format, built up of the following pieces:
%y(2 digits); 00-69 -> 2000-2069, 70-99 -> 1970-1999.
%b(abbreviated name, like “Jan”).
%B(full name, “January”).
%e(optional leading space).
%I0-12, must be used with
%ZTime zone (as name, e.g.
America/Chicago). Beware of abbreviations: if you’re American, note that “EST” is a Canadian time zone that does not have daylight savings time. It is not Eastern Standard Time! We’ll come back to this \[time zones\].
%z(as offset from UTC, e.g.
%.skips one non-digit character.
%*skips any number of non-digits.
The best way to figure out the correct format is to create a few examples in a character vector, and test with one of the parsing functions. For example:
parse_date("01/02/15", "%m/%d/%y") #>  "2015-01-02" parse_date("01/02/15", "%d/%m/%y") #>  "2015-02-01" parse_date("01/02/15", "%y/%m/%d") #>  "2001-02-15"
If you’re using
%B with non-English month names, you’ll need to set the
lang argument to
See the list of built-in languages in
date_names_langs(), or if your language is not already included, create your own with
What are the most important arguments to
What happens if you try and set
grouping_markto the same character? What happens to the default value of
grouping_markwhen you set
decimal_markto “,”? What happens to the default value of
decimal_markwhen you set the
I didn’t discuss the
locale(). What do they do? Construct an example that shows when they might be useful.
If you live outside the US, create a new locale object that encapsulates the settings for the types of file you read most commonly.
What are the most common encodings used in Europe? What are the most common encodings used in Asia? Do some googling to find out.
Generate the correct format string to parse each of the following dates and times:
d1 <- "January 1, 2010" d2 <- "2015-Mar-07" d3 <- "06-Jun-2017" d4 <- c("August 19 (2015)", "July 1 (2015)") d5 <- "12/30/14" # Dec 30, 2014 t1 <- "1705" t2 <- "11:15:10.12 PM"
Now that you’ve learned how to parse an individual vector, it’s time to return to the beginning and explore how readr parses a file. There are two new things that you’ll learn about in this section:
- How readr automatically guesses the type of each column.
- How to override the default specification.
readr uses a heuristic to figure out the type of each column: it reads the first 1000 rows and uses some (moderately conservative) heuristics to figure out the type of each column.
You can emulate this process with a character vector using
guess_parser(), which returns readr’s best guess, and
parse_guess() which uses that guess to parse the column:
guess_parser("2010-10-01") #>  "date" guess_parser("15:01") #>  "time" guess_parser(c("TRUE", "FALSE")) #>  "logical" guess_parser(c("1", "5", "9")) #>  "double" guess_parser(c("12,352,561")) #>  "number" str(parse_guess("2010-10-10")) #> Date[1:1], format: "2010-10-10"
The heuristic tries each of the following types, stopping when it finds a match:
- logical: contains only “F”, “T”, “FALSE”, or “TRUE”.
- integer: contains only numeric characters (and
- double: contains only valid doubles (including numbers like
- number: contains valid doubles with the grouping mark inside.
- time: matches the default
- date: matches the default
- date-time: any ISO8601 date.
If none of these rules apply, then the column will stay as a vector of strings.
These defaults don’t always work for larger files. There are two basic problems:
The first thousand rows might be a special case, and readr guesses a type that is not sufficiently general. For example, you might have a column of doubles that only contains integers in the first 1000 rows.
The column might contain a lot of missing values. If the first 1000 rows contain only
NAs, readr will guess that it’s a logical vector, whereas you probably want to parse it as something more specific.
readr contains a challenging CSV that illustrates both of these problems:
challenge <- read_csv(readr_example("challenge.csv")) #> Rows: 2000 Columns: 2 #> ── Column specification ──────────────────────────────────────────────────────── #> Delimiter: "," #> dbl (1): x #> date (1): y #> #> ℹ Use `spec()` to retrieve the full column specification for this data. #> ℹ Specify the column types or set `show_col_types = FALSE` to quiet this message.
(Note the use of
readr_example() which finds the path to one of the files included with the package)
There are two printed outputs: the column specification generated by looking at the first 1000 rows, and the first five parsing failures.
It’s always a good idea to explicitly pull out the
problems(), so you can explore them in more depth:
problems(challenge) #> # A tibble: 0 × 5 #> # … with 5 variables: row <int>, col <int>, expected <chr>, actual <chr>, #> # file <chr>
A good strategy is to work column by column until there are no problems remaining.
Here we can see that there are a lot of parsing problems with the
If we look at the last few rows, you’ll see that they’re dates stored in a character vector:
tail(challenge) #> # A tibble: 6 × 2 #> x y #> <dbl> <date> #> 1 0.805 2019-11-21 #> 2 0.164 2018-03-29 #> 3 0.472 2014-08-04 #> 4 0.718 2015-08-16 #> 5 0.270 2020-02-04 #> 6 0.608 2019-01-06
That suggests we need to use a date parser instead. To fix the call, start by copying and pasting the column specification into your original call:
challenge <- read_csv( readr_example("challenge.csv"), col_types = cols( x = col_double(), y = col_logical() ) )
Then you can fix the type of the
y column by specifying that
y is a date column:
challenge <- read_csv( readr_example("challenge.csv"), col_types = cols( x = col_double(), y = col_date() ) ) tail(challenge) #> # A tibble: 6 × 2 #> x y #> <dbl> <date> #> 1 0.805 2019-11-21 #> 2 0.164 2018-03-29 #> 3 0.472 2014-08-04 #> 4 0.718 2015-08-16 #> 5 0.270 2020-02-04 #> 6 0.608 2019-01-06
parse_xyz() function has a corresponding
parse_xyz() when the data is in a character vector in R already; you use
col_xyz() when you want to tell readr how to load the data.
I highly recommend always supplying
col_types, building up from the print-out provided by readr.
This ensures that you have a consistent and reproducible data import script.
If you rely on the default guesses and your data changes, readr will continue to read it in.
If you want to be really strict, use
stop_for_problems(): that will throw an error and stop your script if there are any parsing problems.
There are a few other general strategies to help you parse files:
In the previous example, we just got unlucky: if we look at just one more row than the default, we can correctly parse in one shot:
challenge2 <- read_csv(readr_example("challenge.csv"), guess_max = 1001) #> Rows: 2000 Columns: 2 #> ── Column specification ──────────────────────────────────────────────────────── #> Delimiter: "," #> dbl (1): x #> date (1): y #> #> ℹ Use `spec()` to retrieve the full column specification for this data. #> ℹ Specify the column types or set `show_col_types = FALSE` to quiet this message. challenge2 #> # A tibble: 2,000 × 2 #> x y #> <dbl> <date> #> 1 404 NA #> 2 4172 NA #> 3 3004 NA #> 4 787 NA #> 5 37 NA #> 6 2332 NA #> # … with 1,994 more rows
Sometimes it’s easier to diagnose problems if you just read in all the columns as character vectors:
challenge2 <- read_csv(readr_example("challenge.csv"), col_types = cols(.default = col_character()) )
This is particularly useful in conjunction with
type_convert(), which applies the parsing heuristics to the character columns in a data frame.
df <- tribble( ~x, ~y, "1", "1.21", "2", "2.32", "3", "4.56" ) df #> # A tibble: 3 × 2 #> x y #> <chr> <chr> #> 1 1 1.21 #> 2 2 2.32 #> 3 3 4.56 # Note the column types type_convert(df) #> #> ── Column specification ──────────────────────────────────────────────────────── #> cols( #> x = col_double(), #> y = col_double() #> ) #> # A tibble: 3 × 2 #> x y #> <dbl> <dbl> #> 1 1 1.21 #> 2 2 2.32 #> 3 3 4.56
If you’re reading a very large file, you might want to set
n_maxto a smallish number like 10,000 or 100,000. That will accelerate your iterations while you eliminate common problems.
If you’re having major parsing problems, sometimes it’s easier to just read into a character vector of lines with
read_lines(), or even a character vector of length 1 with
read_file(). Then you can use the string parsing skills you’ll learn later to parse more exotic formats.
You are reading the work-in-progress second edition of R for Data Science. This chapter is currently currently a dumping ground for ideas, and we don’t recommend reading it. You can find the polished first edition at https://r4ds.had.co.nz.