read_econdata: read_econdata
In byrongibby/econdatar: Automation of time series uploads and downloads
View source: R/read_econdata.R
read_econdata R Documentation
read_econdata
Description
Returns the data set for the given dataflow - agencyid:id(version) and data provider - agencyid:id, as a list, or as tidy data.table's. Available data sets can be looked up from the data registry (http://www.econdata.co.za/FusionRegistry). Tidying can be done directly within read_econdata(), or ex-post using econdata_tidy().
Usage
read_econdata(id, ..., tidy = FALSE)
econdata_tidy(x, ...)
Arguments
id
Data identifier.
x
A raw API return object to be tidied. Can also be done directly in read_econdata() by setting tidy = TRUE. See tidy below for tidying options.
...
Further Optional arguments:
agencyid Agency responsible for the data definition.
version Version of the data definition.
provideragencyid Agency responsible for making the data available.
providerid Provider of the data.
file character. File name for retrieving JSON data from disk.
username character. EconData username.
password character. EconData password.
tidy
logical. Return data and metadata in tidy data.table's (see Value), by passing the result through econdata_tidy. If TRUE, read_econdata()/econdata_tidy() admit the following additional arguments:
wide logical, default: TRUE. Returns data in a column-based format, with "label" and "source.code" attributes to columns and an overall "metadata" attribute to the table, otherwise a long-format is returned. See Value.
codelabel logical, default: FALSE. If wide = TRUE, setting codelabel = TRUE will add the source identifier at the beginning of the "label", in addition to being attached as a "source.code" attribute.
combine logical, default: FALSE. If wide = FALSE, setting combine = TRUE will combine all data and metadata into a single long table, whereas the default FALSE will return data and metadata in separate tables, for more efficient storage.
origmeta logical, default: FALSE. If wide = FALSE, setting origmeta = TRUE will combine all metadata fields attached to the series in the dataset as they are. The default is to construct a standardized set of metadata variables, and then drop those not observed. See also allmeta.
allmeta logical, default: FALSE. If wide = FALSE, setting allmeta = TRUE always returns the full set of metadata fields, regardless of whether they are recorded for the given dataset. It is also possible that there are series with zero observations in a dataset. Such series are dropped in tidy output, but if combine = FALSE, allmeta = TRUE retains their metadata in the metadata table.
release logical, default: FALSE. TRUE allows you to apply econdata_tidy() to objects returned by read_release().
Details
Specifying the full dataflow and data provider details (as opposed to only using the data id) allows more fine-grained control over the data set being queried. This is not necessary if there is only a single definition of the data and a single provider, which is typically the case.
An EconData account (http://app.econdata.co.za) is required to use this function. The user must provide their credentials either through the function arguments, or by setting the ECONDATA_CREDENTIALS environment variable using the syntax: "username;password", e.g. Sys.setenv(ECONDATA_CREDENTIALS="username;password"). If credentials are not supplied by the aforementioned methods a GUI dialog will prompt the user for credentials.
Value
If tidy = FALSE, a list of data frames is returned, where the names of the list are the EconData series codes, and each data frame has a single column named 'OBS_VALUE' containing the data, with corresponding dates attached as rownames. Each data frame further has a "metadata" attribute providing information about the series. The entire list of data frames also has a "metadata" attribute, providing information about the dataset. If multiple datasets (or versions of a dataset if version is left empty) are being queried, a list of such lists is returned.
If tidy = TRUE and wide = TRUE (the default), a single data.table is returned where the first column is the date, and the remaining columns are series named by their EconData codes. Each series has two attributes: "label" provides a variable label combining important metadata from the "metadata" attribute in the non-tidy format, and "source.code" gives the series code assigned by the original data provider. The table has the same dataset-level "metadata" attribute as the list of data frames if tidy = FALSE. If multiple datasets (or versions of a dataset if version is left empty) are being queried, a list of such data.table's is returned.
If tidy = TRUE and wide = FALSE and compact = FALSE (the default), a named list of two data.table's is returned. The first, "data", has columns 'code', 'date' and 'value' providing the data in a long format. The second, "metadata", provides dataset and series-level matadata, with one row for each series. If compact = TRUE, these two datasets are combined, where all repetitive content is converted to factors for more efficient storage. If multiple datasets (or versions of a dataset if version is left empty) are being queried, compact = FALSE gives a nested list, whereas compact = TRUE binds everything together to a single long frame. In general, if wide = FALSE, no attributes are attached to the tables or columns in the tables.
See Also
write_econdata
Examples
## Not run:
# library(econdatar)
# Sys.setenv(ECONDATA_CREDENTIALS="username;password")
# Ids see: https://www.econdata.co.za/FusionRegistry/data/datastructure.html
# Electricity Generated
ELECTRICITY <- read_econdata(id = "ELECTRICITY")
ELECTRICITY_WIDE <- econdata_tidy(ELECTRICITY) # Or: read_econdata("ELECTRICITY", tidy = TRUE)
ELECTRICITY_LONG <- econdata_tidy(ELECTRICITY, wide = FALSE)
# Same as econdata_tidy(ELECTRICITY, wide = FALSE, combine = TRUE):
with(ELECTRICITY_LONG, metadata[data, on = "code"])
# CPI Analytical Series: Different Revisions
CPI_ANL <- read_econdata(id = "CPI_ANL_SERIES")
CPI_ANL_WIDE <- econdata_tidy(CPI_ANL)
CPI_ANL_LONG <- econdata_tidy(CPI_ANL, wide = FALSE, combine = TRUE)
CPI_ANL_ALLMETA <- econdata_tidy(CPI_ANL, wide = FALSE, allmeta = TRUE) # v2.0 has some 0-obs series
# Can query a specific version by adding e.g. agencyid = "ECONDATA" and version = "2.0" to the call
## End(Not run)
byrongibby/econdatar documentation built on March 18, 2023, 9:30 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
View source: R/read_econdata.R
| read_econdata | R Documentation |
read_econdata
Description
Returns the data set for the given dataflow - agencyid:id(version) and data provider - agencyid:id, as a list, or as tidy data.table's. Available data sets can be looked up from the data registry (http://www.econdata.co.za/FusionRegistry). Tidying can be done directly within read_econdata(), or ex-post using econdata_tidy().
Usage
read_econdata(id, ..., tidy = FALSE) econdata_tidy(x, ...)
Arguments
id |
Data identifier. | |||||||||||||||||||||||||||||||||
x |
A raw API return object to be tidied. Can also be done directly in | |||||||||||||||||||||||||||||||||
... |
Further Optional arguments:
| |||||||||||||||||||||||||||||||||
tidy |
logical. Return data and metadata in tidy data.table's (see Value), by passing the result through
|
Details
Specifying the full dataflow and data provider details (as opposed to only using the data id) allows more fine-grained control over the data set being queried. This is not necessary if there is only a single definition of the data and a single provider, which is typically the case.
An EconData account (http://app.econdata.co.za) is required to use this function. The user must provide their credentials either through the function arguments, or by setting the ECONDATA_CREDENTIALS environment variable using the syntax: "username;password", e.g. Sys.setenv(ECONDATA_CREDENTIALS="username;password"). If credentials are not supplied by the aforementioned methods a GUI dialog will prompt the user for credentials.
Value
If tidy = FALSE, a list of data frames is returned, where the names of the list are the EconData series codes, and each data frame has a single column named 'OBS_VALUE' containing the data, with corresponding dates attached as rownames. Each data frame further has a "metadata" attribute providing information about the series. The entire list of data frames also has a "metadata" attribute, providing information about the dataset. If multiple datasets (or versions of a dataset if version is left empty) are being queried, a list of such lists is returned.
If tidy = TRUE and wide = TRUE (the default), a single data.table is returned where the first column is the date, and the remaining columns are series named by their EconData codes. Each series has two attributes: "label" provides a variable label combining important metadata from the "metadata" attribute in the non-tidy format, and "source.code" gives the series code assigned by the original data provider. The table has the same dataset-level "metadata" attribute as the list of data frames if tidy = FALSE. If multiple datasets (or versions of a dataset if version is left empty) are being queried, a list of such data.table's is returned.
If tidy = TRUE and wide = FALSE and compact = FALSE (the default), a named list of two data.table's is returned. The first, "data", has columns 'code', 'date' and 'value' providing the data in a long format. The second, "metadata", provides dataset and series-level matadata, with one row for each series. If compact = TRUE, these two datasets are combined, where all repetitive content is converted to factors for more efficient storage. If multiple datasets (or versions of a dataset if version is left empty) are being queried, compact = FALSE gives a nested list, whereas compact = TRUE binds everything together to a single long frame. In general, if wide = FALSE, no attributes are attached to the tables or columns in the tables.
See Also
write_econdata
Examples
## Not run:
# library(econdatar)
# Sys.setenv(ECONDATA_CREDENTIALS="username;password")
# Ids see: https://www.econdata.co.za/FusionRegistry/data/datastructure.html
# Electricity Generated
ELECTRICITY <- read_econdata(id = "ELECTRICITY")
ELECTRICITY_WIDE <- econdata_tidy(ELECTRICITY) # Or: read_econdata("ELECTRICITY", tidy = TRUE)
ELECTRICITY_LONG <- econdata_tidy(ELECTRICITY, wide = FALSE)
# Same as econdata_tidy(ELECTRICITY, wide = FALSE, combine = TRUE):
with(ELECTRICITY_LONG, metadata[data, on = "code"])
# CPI Analytical Series: Different Revisions
CPI_ANL <- read_econdata(id = "CPI_ANL_SERIES")
CPI_ANL_WIDE <- econdata_tidy(CPI_ANL)
CPI_ANL_LONG <- econdata_tidy(CPI_ANL, wide = FALSE, combine = TRUE)
CPI_ANL_ALLMETA <- econdata_tidy(CPI_ANL, wide = FALSE, allmeta = TRUE) # v2.0 has some 0-obs series
# Can query a specific version by adding e.g. agencyid = "ECONDATA" and version = "2.0" to the call
## End(Not run)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.