Get a table from a local or remote file

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_dbl object, which can be used as a target table for create_agent() and create_informant(). The ideal option for data access with file_tbl() is using this function as the read_fn parameter in either of the aforementioned create_*() functions. This can be done by using a leading ~ (e.g,. read_fn = ~file_tbl(...)).

In the remote data use case, we can specify a URL starting with http:// or https:// 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 for a repository.

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.

Function ID

1-7

See also

Other Planning and Prep: action_levels(), create_agent(), create_informant(), db_tbl(), scan_data(), tbl_get(), tbl_source(), tbl_store(), validate_rmd()

Examples

# 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"
  )
  
# Now that we have a `tbl` object that
# is a tibble, it can 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(
    read_fn = ~ file_tbl(
      file = system.file(
        "data_files", "small_table.csv",
        package = "pointblank"
      ),
      col_types = "TDdcddlc"
    )
  ) %>%
  col_vals_gt(vars(a), 0)

# All of the file-reading instructions
# are encapsulated in the `read_fn` so
# the agent will always obtain the most
# recent version of the dataset (and the
# logic can be translated to YAML, for
# later use)

# 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-reading function that
# gets the same CSV file from the GitHub
# repository for the pointblank package 
# agent <- 
#   create_agent(
#     read_fn = ~ file_tbl(
#       file = from_github(
#         file = "inst/data_files/small_table.csv",
#         repo = "rich-iannone/pointblank"
#       ),
#       col_types = "TDdcddlc"
#     )
#   ) %>%
#   col_vals_gt(vars(a), 0) %>%
#   interrogate()

# 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)