Merge pull request #37 from aidanhorn/aidan-PR/docs

Documentation improvements

Author: byrongibby

R/read_dataset.R

@@ -125,6 +125,7 @@ read_dataset <- function(id, tidy = FALSE, ...) {
 }
 
 read_econdata <- function(id, tidy = FALSE, ...) {
+  .Deprecated("read_dataset")
   read_dataset(id = id, tidy = tidy, ...)
 }
 

R/write_dataset.R

@@ -119,6 +119,7 @@ write_dataset <- function(x, method = "stage", ...) {
 }
 
 write_econdata <- function(x, create = FALSE, update = FALSE, stage = TRUE, ...) {
+  .Deprecated("write_dataset")
   if (create || update) {
     stop("Create and update no longer supported, please use 'write_dataset'")
   }

R/write_release.R

@@ -1,4 +1,4 @@
-write_release <- function(id, version, providerid, description, method = "release", ...)  {
+write_release <- function(id, version, description, method = "release", ...)  {
 
 
   # Parameters ----

man/econdatar-package.Rd

@@ -10,11 +10,11 @@
 }
 \details{
 
-This package provides an interface to Codera Analytic's econometric data service (https://codera.co.za) and  the EconData database (https://www.econdata.co.za) in particular.
+This package provides an interface to \href{https://codera.co.za/}{Codera Analytics'} econometric data service and the \href{https://www.econdata.co.za/}{EconData} database in particular.
 
 EconData enables automation of analytical workflows that depend on public domain or third-party data. It is also a leading-edge forecast management system, enabling data and model automation and best practice data and model governance. EconData supports data-sharing across databases and within institutions, codifies modelling process flows and provides user-level access control. EconData makes it easy to securely manage and share model scenarios and forecast vintages.
 
-The EconData Registry provides a central data glossary of data concepts and the information necessary to access and interpret data and associated metadata.
+The EconData Registry provides a central data glossary of data concepts and the information necessary to access and interpret data and associated metadata. The Registry can be queried through this package's \code{\link{read_registry}} function.
 
 Codera also uses EconData to automate models, do research, and create value-added products such as interactive scenario dashboards. These dashboards and forecasts are made available to our clients.
 }
@@ -24,8 +24,8 @@ Maintainer: \packageMaintainer{econdatar}
 }
 \keyword{ package }
 \seealso{
-https://www.econdata.co.za
-https://econdata.co.za
+\href{https://www.econdata.co.za}{https://www.econdata.co.za}
+\href{https://econdata.co.za}{https://econdata.co.za}
 }
 \examples{
 \dontrun{

man/read_database.Rd

@@ -15,9 +15,9 @@ read_database(id, include_series = FALSE, tidy = FALSE, \dots)
 \arguments{
   \item{id}{Data set identifier. May be \code{"all"}}
   \item{include_series}{If \code{TRUE} series (and their metadata) with obervations omitted are included in the return (series are discarded when \emph{tidy} is \code{TRUE}).}
-  \item{x}{A raw API return object to be tidied. Can also be done directly in \code{read_database()} by setting \code{tidy = TRUE}}.
+  \item{x}{A raw API return object to be tidied. Can also be done directly in \code{read_database()} by setting \code{tidy = TRUE}}
 
-\item{\dots}{Further \emph{Optional} arguments:
+\item{\dots}{Further \emph{optional} arguments:
   \tabular{llll}{
     \code{agencyid} \tab\tab character. Defaults to \code{ECONDATA}. Agency responsible for the metadata creation/maintenance. \cr
     \code{version} \tab\tab character. Version(s) of the data (different versions will have different metadata), or \code{"all"} to return all available versions. \cr
@@ -27,7 +27,7 @@ read_database(id, include_series = FALSE, tidy = FALSE, \dots)
 \item{tidy}{logical. Return data and metadata in tidy \emph{data.table}'s (see Value), by passing the result through \code{tidy_data}.}
 }
 \details{
-An EconData account (http://econdata.co.za) is required to use this function. The user must provide an API token that can be found on the \emph{Account} page of the online portal, a GUI dialog will prompt the user for their API token. Credentials can also be supplied by setting the ECONDATA_CREDENTIALS environment variable using the syntax: "client_id;client_secret", e.g. \code{Sys.setenv(ECONDATA_CREDENTIALS="client_id;client_secret")}, when available.
+An \href{https://econdata.co.za/}{EconData} account is required to use this function. The user must provide an API token, which can be found on the \emph{Account} page of the online portal. A GUI dialog will prompt the user for their API token. Credentials can also be supplied by setting the ECONDATA_CREDENTIALS environment variable using the syntax: "client_id;client_secret", e.g. \code{Sys.setenv(ECONDATA_CREDENTIALS="client_id;client_secret")}, when available.
 }
 \value{
 If \code{tidy = FALSE}, an unnamed list of data frames is returned. Each data frame further has a \code{"metadata"} attribute providing information about the data set.

man/read_dataset.Rd

@@ -5,7 +5,7 @@
 read_dataset
 }
 \description{
-Returns the data for the given data set - ECONDATA:id(version), as a list, or as tidy \emph{data.table}'s. Available data sets can be looked up using \code{read_database()} or from the web platform (http://econdata.co.za). Tidying can be done directly within \code{read_dataset()}, or ex-post using \code{tidy_data()}.
+Returns the data for the given data set - ECONDATA:id(version), as a list, or as tidy \emph{data.table}'s. Available data sets can be looked up using \code{read_database()} or from the \href{https://www.econdata.co.za/}{web platform}. Tidying can be done directly within \code{read_dataset()}, or ex-post using \code{tidy_data()}.
 }
 \usage{
 read_dataset(id, tidy = FALSE, \dots)
@@ -15,38 +15,30 @@ read_dataset(id, tidy = FALSE, \dots)
 \arguments{
   \item{id}{Data set identifier.}
   \item{x}{A raw API return object to be tidied. Can also be done directly in \code{read_dataset()} by setting \code{tidy = TRUE}. See \code{tidy} below for tidying options.}
-  \item{wide}{Should the tidied data be returned in \emph{wide} or \emph{long} format.}
+  \item{wide}{Specifies whether the tidied data be returned in \emph{wide} or \emph{long} format.}
 
-\item{\dots}{Further \emph{Optional} arguments:
+\item{\dots}{Further \emph{optional} arguments:
   \tabular{llll}{
     \code{agencyid} \tab\tab character. Defaults to \code{ECONDATA}. Agency responsible for the metadata creation/maintenance. \cr
     \code{version} \tab\tab character. Version(s) of the data (different versions will have different metadata), or 'all' to return all available versions. \cr
-    \code{series_key} \tab\tab character. A character vector specifying a subset of time series (see the web platform (export function) for details). \cr
+    \code{series_key} \tab\tab character. A character vector specifying a subset of time series (see the web platform (export function) for an example). The series key is composed of a few dimensions, separated with full-stops. In the syntax of the argument, include various concept codes \emph{within each dimension}, separated by a + character. The function then downloads the union of all the possible combinations of the concept codes chosen. Please see \href{https://econdata.co.za/fast-econdatar-downloads/}{our blog post}.\cr
     \code{release} \tab\tab character (optionally with format \%Y-\%m-\%dT\%H:\%M:\%S, to be coerced to a date/time). The release description, which will return the data associated with that release (if the given description matches an existsing release); or a date/time which will return the data as it was at the given time; or 'latest' which will return the latest release; or 'unreleased' which will return any unreleased data (useful for data that is updated more often than it is released, e.g. daily data). \cr
     \code{file} \tab\tab character. File name for retrieving data sets stored as JSON data from disk (output of \code{read_dataset()}. \cr
-  }
-}
-
-\item{tidy}{logical. Return data and metadata in tidy \emph{data.table}'s (see Value), by passing the result through \code{tidy_data}. If \code{TRUE}, \code{read_dataset()/tidy_data()} admit the following additional arguments:
+}}
+\item{tidy}{logical. Return data and metadata in tidy \emph{data.table}'s (see Value), by passing the result through \code{tidy_data}. If \code{TRUE}, \code{read_dataset()/tidy_data()} admit the following additional arguments:}
+\item{\dots}{
   \tabular{llll}{
     \code{wide} \tab\tab logical, default: \code{TRUE}. Returns data in a column-based format, with \code{"label"} and \code{"source_identifier"} attributes to columns (when available) and an overall "metadata" attribute to the table, otherwise a long-format is returned. See Value. \cr
-
     \code{codelabel} \tab\tab logical, default: \code{FALSE}. If \code{wide = TRUE}, setting \code{codelabel = TRUE} the data key will be used to generate the \code{"label"}, when available. \cr
-
     \code{combine} \tab\tab logical, default: \code{FALSE}. If \code{wide = FALSE}, setting \code{combine = TRUE} will combine all data and metadata into a single long table, whereas the default \code{FALSE} will return data and metadata in separate tables, for more efficient storage. \cr
-
     \code{origmeta}  \tab\tab logical, default: \code{FALSE}. If \code{wide = FALSE}, setting \code{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 \code{allmeta}. \cr
-
     \code{allmeta} \tab\tab logical, default: \code{FALSE}. If \code{wide = FALSE}, setting \code{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 \code{combine = FALSE}, \code{allmeta = TRUE} retains their metadata in the metadata table. \cr
-
     \code{prettymeta} \tab\tab logical, default: \code{TRUE}. Attempts to make the returned metadata more human readable replacing each code category and enumeration with its name. It is advisable to leave this set to \code{TRUE}, in some cases, where speed is paramount you may want to set this flag to \code{FALSE}. If multiple datasets are being querioed this option is automatically set to \code{FALSE}. \cr
-
-   \code{release} \tab\tab logical, default: \code{FALSE}. \code{TRUE} allows you to apply \code{tidy_data()} to objects returned by \code{read_release()}. All other flags to \code{tidy_data()} are ignored.
-}
-}
+    \code{release} \tab\tab logical, default: \code{FALSE}. \code{TRUE} allows you to apply \code{tidy_data()} to objects returned by \code{read_release()}. All other flags to \code{tidy_data()} are ignored.
+}}
 }
 \details{
-An EconData account (http://econdata.co.za) is required to use this function. The user must provide an API token that can be found on the \emph{Account} page of the online portal, a GUI dialog will prompt the user for their API token. Credentials can also be supplied by setting the ECONDATA_CREDENTIALS environment variable using the syntax: "client_id;client_secret", e.g. \code{Sys.setenv(ECONDATA_CREDENTIALS="client_id;client_secret")}, when available.
+An \href{http://econdata.co.za/}{EconData} account is required to use this function. The user must provide an API token, which can be found on the \emph{Account} page of the online portal; a GUI dialog will prompt the user for their API token. Credentials can also be supplied by setting the ECONDATA_CREDENTIALS environment variable using the syntax: "client_id;client_secret", e.g. \code{Sys.setenv(ECONDATA_CREDENTIALS="client_id;client_secret")}, when available.
 }
 \value{
 If \code{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 \code{"metadata"} attribute providing information about the series. The entire list of data frames also has a \code{"metadata"} attribute, providing information about the dataset. If multiple datasets (or versions of a dataset if \code{version} is specified as 'all') are being queried, a list of such lists is returned.
@@ -83,6 +75,17 @@ CPI_ANL_ALLMETA <- tidy_data(CPI_ANL, wide = FALSE, allmeta = TRUE) # v2.0 has s
 MARKET_RATES <- read_dataset(id = "MARKET_RATES",
                              series_key = "CMJD003.B.A",
                              release = "unreleased")
+
+# library(tibble)
+data_raw <- read_dataset(id = "POPULATION_DATA_REG",
+                         tidy = TRUE,
+                         wide = FALSE,
+                         compact = FALSE)
+str(data_raw)
+print(names(data_raw$data))
+print(names(data_raw$metadata))
+as_tibble(data_raw$data)
+as_tibble(data_raw$metadata) |> view()
 }
 }
 \keyword{ load }

man/read_econdata.Rd

@@ -5,7 +5,9 @@
 read_econdata
 }
 \description{
-Returns the data for the given data set - ECONDATA:id(version), as a list, or as tidy \emph{data.table}'s. Available data sets can be looked up from the web platform (http://www.econdata.co.za). Tidying can be done directly within \code{read_econdata()}, or ex-post using \code{tidy_data()}.
+This function is deprecated, in favour of \code{\link{read_dataset}}. During development, please replace this function with the newer function name.
+
+Returns the data for the given data set - ECONDATA:id(version), as a list, or as tidy \emph{data.table}'s. Available data sets can be looked up from the \href{http://www.econdata.co.za/}{web platform}. Tidying can be done directly within \code{read_econdata()}, or ex-post using \code{tidy_data()}.
 }
 \usage{
 read_econdata(id, tidy = FALSE, \dots)
@@ -16,7 +18,7 @@ tidy_data(x, \dots)
   \item{id}{Data identifier.}
   \item{x}{A raw API return object to be tidied. Can also be done directly in \code{read_econdata()} by setting \code{tidy = TRUE}. See \code{tidy} below for tidying options.}
 
-\item{\dots}{Further \emph{Optional} arguments:
+\item{\dots}{Further \emph{optional} arguments:
   \tabular{llll}{
     \code{agencyid} \tab\tab character. Defaults to \code{ECONDATA}. Agency responsible for the metadata creation/maintenance. \cr
     \code{version} \tab\tab character. Version(s) of the data (different versions will have different metadata), or 'all' to return all available versions. \cr
@@ -26,7 +28,8 @@ tidy_data(x, \dots)
   }
 }
 
-\item{tidy}{logical. Return data and metadata in tidy \emph{data.table}'s (see Value), by passing the result through \code{tidy_data}. If \code{TRUE}, \code{read_econdata()/tidy_data()} admit the following additional arguments:
+\item{tidy}{logical. Return data and metadata in tidy \emph{data.table}'s (see Value), by passing the result through \code{tidy_data}. If \code{TRUE}, \code{read_econdata()/tidy_data()} admit the following additional arguments:}
+\item{\dots}{
   \tabular{llll}{
     \code{wide} \tab\tab logical, default: \code{TRUE}. Returns data in a column-based format, with \code{"label"} and \code{"source_identifier"} attributes to columns (when available) and an overall "metadata" attribute to the table, otherwise a long-format is returned. See Value. \cr
 
@@ -45,7 +48,7 @@ tidy_data(x, \dots)
 }
 }
 \details{
-An EconData account (http://econdata.co.za) is required to use this function. The user must provide an API token that can be found on the \emph{Account} page of the online portal, a GUI dialog will prompt the user for their API token. Credentials can also be supplied by setting the ECONDATA_CREDENTIALS environment variable using the syntax: "client_id;client_secret", e.g. \code{Sys.setenv(ECONDATA_CREDENTIALS="client_id;client_secret")}, when available.
+An \href{http://econdata.co.za/}{EconData} account is required to use this function. The user must provide an API token, which can be found on the \emph{Account} page of the online portal; a GUI dialog will prompt the user for their API token. Credentials can also be supplied by setting the ECONDATA_CREDENTIALS environment variable using the syntax: "client_id;client_secret", e.g. \code{Sys.setenv(ECONDATA_CREDENTIALS="client_id;client_secret")}, when available.
 }
 \value{
 If \code{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 \code{"metadata"} attribute providing information about the series. The entire list of data frames also has a \code{"metadata"} attribute, providing information about the dataset. If multiple datasets (or versions of a dataset if \code{version} is specified as 'all') are being queried, a list of such lists is returned.
@@ -55,6 +58,7 @@ If \code{tidy = TRUE} and \code{wide = TRUE} (the default), a single \emph{data.
 If \code{tidy = TRUE} and \code{wide = FALSE} and \code{compact = FALSE} (the default), a named list of two \emph{data.table}'s is returned. The first, \code{"data"}, has columns 'code', 'date' and 'value' providing the data in a long format. The second, \code{"metadata"}, provides dataset and series-level matadata, with one row for each series. If \code{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 \code{version} is specified as 'all') are being queried, \code{compact = FALSE} gives a nested list, whereas \code{compact = TRUE} binds everything together to a single long frame. In general, if \code{wide = FALSE}, no attributes are attached to the tables or columns in the tables.
 }
 \seealso{
+\code{\line{read_dataset}}
 \code{\link{write_econdata}}
 \code{\link{read_release}}
 }