R: Get a table from a local or remote file

file_tbl {pointblank}

R Documentation

Get a table from a local or remote file

Description

If your target table is in a file, stored either locally or remotely, the file_tbl() function can make it possible to access it in a single function call. Compatible file types for this function are: CSV (.csv), TSV (.tsv), RDA (.rda), and RDS (.rds) files. This function generates an in-memory tbl_df object, which can be used as a target table for create_agent() and create_informant(). Another great option is supplying a table-prep formula involving file_tbl() to tbl_store() so that you have access to tables based on flat files though single names via a table store.

In the remote data use case, we can specify a URL starting with ⁠http://⁠, ⁠https://⁠, etc., and ending with the file containing the data table. If data files are available in a GitHub repository then we can use the from_github() function to specify the name and location of the table data in a repository.

Usage

file_tbl(file, type = NULL, ..., keep = FALSE, verify = TRUE)

Arguments

`file`	The complete file path leading to a compatible data table either in the user system or at a `⁠http://⁠`, `⁠https://⁠`, `⁠ftp://⁠`, or `⁠ftps://⁠` URL. For a file hosted in a GitHub repository, a call to the `from_github()` function can be used here.
`type`	The file type. This is normally inferred by file extension and is by default `NULL` to indicate that the extension will dictate the type of file reading that is performed internally. However, if there is no extension (and valid extensions are `.csv`, `.tsv`, `.rda`, and `.rds`), we can provide the type as either of `csv`, `tsv`, `rda`, or `rds`.
`...`	Options passed to readr's `read_csv()` or `read_tsv()` function. Both functions have the same arguments and one or the other will be used internally based on the file extension or an explicit value given to `type`.
`keep`	In the case of a downloaded file, should it be stored in the working directory (`keep = TRUE`) or should it be downloaded to a temporary directory? By default, this is `FALSE`.
`verify`	If `TRUE` (the default) then a verification of the data object having the `data.frame` class will be carried out.

Value

A tbl_df object.

Examples

Producing tables from CSV files

A local CSV file can be obtained as a tbl object by supplying a path to the file and some CSV reading options (the ones used by readr::read_csv()) to the file_tbl() function. For this example we could obtain a path to a CSV file in the pointblank package with system.file().

csv_path <- 
  system.file(
    "data_files", "small_table.csv",
    package = "pointblank"
  )

Then use that path in file_tbl() with the option to specify the column types in that CSV.

tbl <- 
  file_tbl(
    file = csv_path,
    col_types = "TDdcddlc"
  )

tbl

## # A tibble: 13 × 8
##    date_time           date           a b           c      d e     f    
##    <dttm>              <date>     <dbl> <chr>   <dbl>  <dbl> <lgl> <chr>
##  1 2016-01-04 11:00:00 2016-01-04     2 1-bcd-…     3  3423. TRUE  high 
##  2 2016-01-04 00:32:00 2016-01-04     3 5-egh-…     8 10000. TRUE  low  
##  3 2016-01-05 13:32:00 2016-01-05     6 8-kdg-…     3  2343. TRUE  high 
##  4 2016-01-06 17:23:00 2016-01-06     2 5-jdo-…    NA  3892. FALSE mid  
##  5 2016-01-09 12:36:00 2016-01-09     8 3-ldm-…     7   284. TRUE  low  
##  6 2016-01-11 06:15:00 2016-01-11     4 2-dhe-…     4  3291. TRUE  mid  
##  7 2016-01-15 18:46:00 2016-01-15     7 1-knw-…     3   843. TRUE  high 
##  8 2016-01-17 11:27:00 2016-01-17     4 5-boe-…     2  1036. FALSE low  
##  9 2016-01-20 04:30:00 2016-01-20     3 5-bce-…     9   838. FALSE high 
## 10 2016-01-20 04:30:00 2016-01-20     3 5-bce-…     9   838. FALSE high 
## 11 2016-01-26 20:07:00 2016-01-26     4 2-dmx-…     7   834. TRUE  low  
## 12 2016-01-28 02:51:00 2016-01-28     2 7-dmx-…     8   108. FALSE low  
## 13 2016-01-30 11:23:00 2016-01-30     1 3-dka-…    NA  2230. TRUE  high

Now that we have a 'tbl' object that is a tibble it could be introduced to create_agent() for validation.

agent <- create_agent(tbl = tbl)

A different strategy is to provide the data-reading function call directly to create_agent():

agent <- 
  create_agent(
    tbl = ~ file_tbl(
      file = system.file(
        "data_files", "small_table.csv",
        package = "pointblank"
      ),
      col_types = "TDdcddlc"
    )
  ) %>%
  col_vals_gt(columns = a, value = 0)

All of the file-reading instructions are encapsulated in the tbl expression (with the leading ~) so the agent will always obtain the most recent version of the table (and the logic can be translated to YAML, for later use).

Producing tables from files on GitHub

A CSV can be obtained from a public GitHub repo by using the from_github() helper function. Let's create an agent a supply a table-prep formula that gets the same CSV file from the GitHub repository for the pointblank package.

agent <- 
  create_agent(
    tbl = ~ file_tbl(
      file = from_github(
        file = "inst/data_files/small_table.csv",
        repo = "rstudio/pointblank"
      ),
      col_types = "TDdcddlc"
    ),
    tbl_name = "small_table",
    label = "`file_tbl()` example.",
  ) %>%
  col_vals_gt(columns = a, value = 0) %>%
  interrogate()

agent

This image was generated from the first code example in the `file_tbl()` help file.

This interrogated the data that was obtained from the remote source file, and, there's nothing to clean up (by default, the downloaded file goes into a system temp directory).

File access, table creation, and prep via the table store

Using table-prep formulas in a centralized table store can make it easier to work with tables from disparate sources. Here's how to generate a table store with two named entries for table preparations involving the tbl_store() and file_tbl() functions.

store <-
  tbl_store(
    small_table_file ~ file_tbl(
      file = system.file(
        "data_files", "small_table.csv",
        package = "pointblank"
      ),
      col_types = "TDdcddlc"
    ),
    small_high_file ~ {{ small_table_file }} %>%
      dplyr::filter(f == "high")
  )

Now it's easy to access either of these tables via tbl_get(). We can reference the table in the store by its name (given to the left of the ~).

tbl_get(tbl = "small_table_file", store = store)

## # A tibble: 13 × 8
##    date_time           date           a b           c      d e     f    
##    <dttm>              <date>     <dbl> <chr>   <dbl>  <dbl> <lgl> <chr>
##  1 2016-01-04 11:00:00 2016-01-04     2 1-bcd-…     3  3423. TRUE  high 
##  2 2016-01-04 00:32:00 2016-01-04     3 5-egh-…     8 10000. TRUE  low  
##  3 2016-01-05 13:32:00 2016-01-05     6 8-kdg-…     3  2343. TRUE  high 
##  4 2016-01-06 17:23:00 2016-01-06     2 5-jdo-…    NA  3892. FALSE mid  
##  5 2016-01-09 12:36:00 2016-01-09     8 3-ldm-…     7   284. TRUE  low  
##  6 2016-01-11 06:15:00 2016-01-11     4 2-dhe-…     4  3291. TRUE  mid  
##  7 2016-01-15 18:46:00 2016-01-15     7 1-knw-…     3   843. TRUE  high 
##  8 2016-01-17 11:27:00 2016-01-17     4 5-boe-…     2  1036. FALSE low  
##  9 2016-01-20 04:30:00 2016-01-20     3 5-bce-…     9   838. FALSE high 
## 10 2016-01-20 04:30:00 2016-01-20     3 5-bce-…     9   838. FALSE high 
## 11 2016-01-26 20:07:00 2016-01-26     4 2-dmx-…     7   834. TRUE  low  
## 12 2016-01-28 02:51:00 2016-01-28     2 7-dmx-…     8   108. FALSE low  
## 13 2016-01-30 11:23:00 2016-01-30     1 3-dka-…    NA  2230. TRUE  high

The second table in the table store is a mutated version of the first. It's just as easily obtainable via tbl_get():

tbl_get(tbl = "small_high_file", store = store)

## # A tibble: 6 × 8
##   date_time           date           a b             c     d e     f    
##   <dttm>              <date>     <dbl> <chr>     <dbl> <dbl> <lgl> <chr>
## 1 2016-01-04 11:00:00 2016-01-04     2 1-bcd-345     3 3423. TRUE  high 
## 2 2016-01-05 13:32:00 2016-01-05     6 8-kdg-938     3 2343. TRUE  high 
## 3 2016-01-15 18:46:00 2016-01-15     7 1-knw-093     3  843. TRUE  high 
## 4 2016-01-20 04:30:00 2016-01-20     3 5-bce-642     9  838. FALSE high 
## 5 2016-01-20 04:30:00 2016-01-20     3 5-bce-642     9  838. FALSE high 
## 6 2016-01-30 11:23:00 2016-01-30     1 3-dka-303    NA 2230. TRUE  high

The table-prep formulas in the store object could also be used in functions with a tbl argument (like create_agent() and create_informant()). This is accomplished most easily with the tbl_source() function.

agent <- 
  create_agent(
    tbl = ~ tbl_source(
      tbl = "small_table_file",
      store = store
    )
  )

informant <- 
  create_informant(
    tbl = ~ tbl_source(
      tbl = "small_high_file",
      store = store
    )
  )

Function ID

1-7