googlesheets: gs_read – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

gs_read

Read data

Description

This function reads data from a worksheet and returns a data frame. It wraps up the most common usage of other, lower-level functions for data consumption and transformation, but you can call always call them directly for finer control.

Usage

gs_read(ss, ws = 1, range = NULL, literal = TRUE, ..., verbose = TRUE)

Arguments

`ss`	a registered Google spreadsheet, i.e. a `googlesheet` object
`ws`	positive integer or character string specifying index or title, respectively, of the worksheet
`range`	a cell range, as described in `cell-specification`
`literal`	logical, indicating whether to work only with literal values returned by the API or to consult alternate cell contents
`...`	Optional arguments to control data download, parsing, and reshaping; for most purposes, the defaults should be fine. Anything that is not listed here will be silently ignored. `progress` Logical. Whether to display download progress if in an interactive session. `col_types` Seize control of type conversion for variables. Passed straight through to `readr::read_csv` or `readr::type_convert`. Follow those links or read the `vignette("column-types")` for details. `locale, trim_ws, na` Specify locale, the fate of leading or trailing whitespace, or a character vector of strings that should become missing values. Passed straight through to `readr::read_csv` or `readr::type_convert`. `comment, skip, n_max` Specify a string used to identify comments, request to skip lines before reading data, or specify the maximum number of data rows to read. `col_names` Either `TRUE`, `FALSE` or a character vector of column names. If `TRUE`, the first row of the data rectangle will be used for names. If `FALSE`, column names will be X1, X2, etc. If a character vector, it will be used as column names. If the sheet contains column names and you just don't like them, specify `skip = 1` so they don't show up in your data. `check.names` Logical. Whether to run column names through `make.names` with `unique = TRUE`, just like `read.table` does. By default, `googlesheets` implements the `readr` data ingest philosophy, which leaves column names "as is", with one exception: data frames returned by `googlesheets` will have a name for each variable, even if we have to create one.
`verbose`	logical; do you want informative messages?

Details

If the range argument is not specified and literal = TRUE, all data will be read via gs_read_csv. Don't worry – no intermediate *.csv files are written! We just request the data from the Sheets API via the exportcsv link.

If the range argument is specified or if literal = FALSE, data will be read for the targetted cells via gs_read_cellfeed, then reshaped and type converted with gs_reshape_cellfeed. See gs_reshape_cellfeed for details.

Value

a data.frame or, if dplyr is loaded, a tbl_df

Examples

## Not run: 
gap_ss <- gs_gap()
oceania_csv <- gs_read(gap_ss, ws = "Oceania")
str(oceania_csv)
oceania_csv

gs_read(gap_ss, ws = "Europe", n_max = 4, col_types = c("cccccc"))

gs_read(gap_ss, ws = "Oceania", range = "A1:C4")
gs_read(gap_ss, ws = "Oceania", range = "R1C1:R4C3")
gs_read(gap_ss, ws = "Oceania", range = "R2C1:R4C3", col_names = FALSE)
gs_read(gap_ss, ws = "Oceania", range = "R2C5:R4C6",
        col_names = c("thing_one", "thing_two"))
gs_read(gap_ss, ws = "Oceania", range = cell_limits(c(1, 3), c(1, 4)),
        col_names = FALSE)
gs_read(gap_ss, ws = "Oceania", range = cell_rows(1:5))
gs_read(gap_ss, ws = "Oceania", range = cell_cols(4:6))
gs_read(gap_ss, ws = "Oceania", range = cell_cols("A:D"))

ff_ss <- gs_ff() # register example sheet with formulas and formatted nums
gs_read(ff_ss)                  # almost all vars are character
gs_read(ff_ss, literal = FALSE) # more vars are properly numeric

## End(Not run)

googlesheets

Manage Google Spreadsheets from R

v0.3.0

MIT + file LICENSE

Authors

Jennifer Bryan [aut, cre], Joanna Zhao [aut]

Initial release