DOCSEARCHbyAlgolia
Submit Docs

readr

repository·main·Indexed 21 days ago

https://github.com/tidyverse/readr

A fast and friendly tool for reading rectangular data from delimited files (such as CSV, TSV, and fixed-width files) into R. It provides informative parsing reports, explicit column type specifications via the col_types argument, and specialized functions like read_csv(), read_tsv(), and read_delim(). Starting with version 2.0.0, readr uses a new parsing engine based on vroom::vroom(), while providing with_edition(1, ...) for legacy compatibility.

Tokens
1.4K
Snippets
5
Records
8
Agent score
27%

What's inside readr

  1. Access first edition parsing in readr 2.0.0+

    main

    Starting with version 2.0.0, readr uses a new parsing engine (the second edition) which calls vroom::vroom() by default. If you need to use the original (first edition) parsing engine for legacy compatibility, you can use with_edition(1, ...) for specific calls or local_edition(1) to set it locally.

    # Example of using the first edition engine
with_edition(1, read_csv("data.csv"))

  2. Install readr

    main

    You can install readr as part of the full tidyverse suite, as a standalone package from CRAN, or the development version from GitHub using pak.

    # Install the whole tidyverse
install.packages("tidyverse")

# Install just readr
install.packages("readr")

# Install the development version from GitHub
# install.packages("pak")
pak::pak("tidyverse/readr")
    # The easiest way to get readr is to install the whole tidyverse:
install.packages("tidyverse")

# Alternatively, install just readr:
install.packages("readr")

# Or you can install the development version from GitHub:
# install.packages("pak")
pak::pak("tidyverse/readr")

  3. Load readr into your session

    main

    Since readr is a core tidyverse package, you can load it along with other tidyverse tools using library(tidyverse), or load it individually using library(readr).

    library(tidyverse)

# Or load readr individually
library(readr)

  4. Define column types using column specifications

    main

    While readr automatically guesses column types during data exploration, it is best practice to provide an explicit column specification as your project matures.

    Workflow for providing explicit types:

    1. Load the data using a read_*() function (e.g., read_csv()).
    2. Use the spec() function on the resulting object to retrieve the guessed column specification.
    3. Copy the output of spec(), tweak the types (e.g., changing col_double() to col_integer() or col_factor()), and pass it to the col_types argument in your read_*() call.
    # 1. Load and guess types
chickens <- read_csv(readr_example("chickens.csv"))

# 2. Retrieve the specification
chickens_spec <- spec(chickens)

# 3. Use the specification with explicit types
chickens <- read_csv(
  readr_example("chickens.csv"),
  col_types = cols(
    chicken   = col_character(),
    sex       = col_factor(levels = c("rooster", "hen")),
    eggs_laid = col_integer(),
    motto     = col_character()
  )
)

  5. Resolve unused argument errors in `write_delim` and `write_csv`

    main

    When using functions that wrap readr writing utilities (like write_sheet in params or write_byperson in suddengains), ensure you are not passing arguments that are no longer supported by the underlying readr functions.

    Common errors include:

    • unused argument (quote_escape = "double") when calling write_delim().
    • unused argument (path = path) when calling write_csv() (ensure the argument name matches the readr signature, which is typically file rather than path in some contexts, or check for argument mismilians in wrappers).

  6. Fix defunct `quoted_na` argument in `read_csv()`

    main

    In readr edition 2, the quoted_na argument in read_csv() is defunct. If you are using a package or code that relies on this argument, you must either:

    1. Use with_edition(1, ...) to wrap the call in the legacy edition 1 environment.
    2. Use local_edition(1) to set the edition locally.

    This is a common breaking change for packages like MIMSunit that attempt to pass quoted_na = TRUE to read_csv().

    # Example of fixing a defunct call
readr::read_csv(file = filepath, quoted_na = TRUE, col_types = coltypes)

# Fix using with_edition
readr::with_edition(1, function() {
  readr::read_csv(file = filepath, quoted_na = TRUE, col_types = coltypes)
})

  7. Handle missing `read_table2` export error

    main

    Several packages (e.g., eyelinker, readit, rubias, skater) are failing because they attempt to call read_table2, which is no longer exported by the readr namespace.

    If you are a developer of a package encountering Error: object ‘read_table2’ is not exported by 'namespace:readr' or Missing or unexported object: ‘readr::read_table2’, you must update your code to use a currently exported function from readr instead of the defunct read_table2.

  8. Read delimited files with read_*() functions

    main

    To read rectangular datasets, readr provides specialized functions for different file formats. These functions parse lines into individual fields and return a tibble.

    Supported formats:

    • read_csv(): comma-separated values (CSV)
    • read_tsv(): tab-separated values (TSV)
    • read_csv2(): semicolon-separated values with , as the decimal mark
    • read_delim(): delimited files (CSV and TSV are important special cases)
    • read_fwf(): fixed-width files
    • read_table(): whitespace-separated files
    • read_log(): web log files