Skip to content

Commit

Permalink
Preparation for CRAN submission
Browse files Browse the repository at this point in the history
  • Loading branch information
@byrongibby
byrongibby committed Aug 14, 2024
1 parent 3687e37 commit a851ec7
Show file tree
Hide file tree
Showing 12 changed files with 78 additions and 155 deletions.
6 changes: 3 additions & 3 deletions DESCRIPTION
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@ Package: econdatar
Title: Automation of Data Tasks to and from Codera Analytics' Econometric Data Services
Version: 3.1.0
Date: 2024-04-24
Authors@R: c(person("Byron", "Botha", role = c("aut", "cre"), email = "byron@codera.co.za"),
person("Sebastian", "Krantz", role = "ctb"))
Description: Automation of data tasks to and from <https://codera.co.za> econometric data services. Using this package users can download data from <https://www.econdata.co.za> directly into R (in tidy format) after signing up for a free account. <https://www.econdata.co.za> hosts a comprehensive database of South African macroeconomic data.
Authors@R: c(person(given = "Byron", family = "Botha", role = c("aut", "cre"), email = "econdata@codera.co.za"),
person(given = "Sebastian", family = "Krantz", role = "ctb"))
Description: Automation of data tasks to and from <https://codera.co.za> econometric data services. Using this package users can download data from <https://www.econdata.co.za> directly into R (in tidy format) after signing up for a free account. <https://www.econdata.co.za> hosts a comprehensive database of South African macroeconomic data. For support and tutorials please see <https://econdata.co.za>.
Depends: R (>= 4.2.0)
Imports: httr, jose, jsonlite, readODS, collapse, data.table
Suggests: tcltk
Expand Down
20 changes: 11 additions & 9 deletions man/econdatar-package.Rd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,20 +19,22 @@ The EconData Registry provides a central data glossary of data concepts and the
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.
}
\author{
%\packageAuthor{econdatar}
Maintainer: \packageMaintainer{econdatar}
}
%\references{
%~~ Literature or other references for background information ~~
%}
%%~~ Optionally other standard keywords, one per line, from file KEYWORDS in ~~
%%~~ the R documentation directory ~~
\keyword{ package }
\seealso{
https://www.econdata.co.za
https://econdata.co.za
}
%\examples{
%~~ simple examples of the most important functions ~~
%}
\examples{
\donttest{
# library(econdatar)
# Return all data sets (useful for browsing available data)
CATALOGUE <- read_database(id = "all", tidy = TRUE)
# Mining production and sales
MINING <- read_dataset(id = "MINING", tidy = TRUE)
}
}
24 changes: 6 additions & 18 deletions man/read_database.Rd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,35 +21,25 @@ read_database(id, include_series = FALSE, tidy = FALSE, \dots)
\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
\code{username} \tab\tab character. Web username. \cr
\code{password} \tab\tab character. Web password. \cr
}
}

\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 their credentials either through the function arguments, or by setting the ECONDATA_CREDENTIALS environment variable using the syntax: "username;password", e.g. \code{Sys.setenv(ECONDATA_CREDENTIALS="username;password")}. If credentials are not supplied by the aforementioned methods a GUI dialog will prompt the user for credentials.
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.
}
\value{
%% ~Describe the value returned
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.
If \code{tidy = TRUE} a single \emph{data.table} is returned with columns for \code{"agencyid"}, \code{"id"}, \code{"version"}, \code{"name"}, and \code{"description"}.
%% \item{comp1 }{Description of 'comp1'}
%% \item{comp2 }{Description of 'comp2'}
%% ...
}
\seealso{
%% ~~objects to See Also as \code{\link{help}}, ~~~
\code{\link{write_database}}
}
\examples{
\dontrun{
\donttest{
# library(econdatar)
# Sys.setenv(ECONDATA_CREDENTIALS="username;password")
# Mining production and sales
MINING <- read_database(id = "MINING")
Expand All @@ -61,11 +51,9 @@ MINING <- read_database(id = "MINING", versions = "all")
MINING <- read_database(id = "MINING", include_series = TRUE)
# Return all data sets (useful for browsing available data)
MINING <- read_database(id = "all")
tidy_data(MINING)
CATALOGUE <- read_database(id = "all")
tidy_data(CATALOGUE)
}
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{ load }% use one of RShowDoc("KEYWORDS")
\keyword{ download }% __ONLY ONE__ keyword per line
\keyword{ load }
\keyword{ download }
21 changes: 4 additions & 17 deletions man/read_dataset.Rd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,6 @@ read_dataset(id, tidy = FALSE, \dots)
\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{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
\code{username} \tab\tab character. Web username. \cr
\code{password} \tab\tab character. Web password. \cr
}
}
Expand All @@ -48,31 +46,22 @@ read_dataset(id, tidy = FALSE, \dots)
}
}
\details{
An EconData account (http://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. \code{Sys.setenv(ECONDATA_CREDENTIALS="username;password")}. If credentials are not supplied by the aforementioned methods a GUI dialog will prompt the user for credentials.
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.
}
\value{
%% ~Describe the value returned
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.

If \code{tidy = TRUE} and \code{wide = TRUE} (the default), a single \emph{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: \code{"label"} provides a variable label combining important metadata from the \code{"metadata"} attribute in the non-tidy format, and \code{"source.code"} gives the series code assigned by the original data provider. The table has the same dataset-level \code{"metadata"} attribute as the list of data frames if \code{tidy = FALSE}. If multiple datasets (or versions of a dataset if \code{version} is specified as 'all') are being queried, a list of such \emph{data.table}'s is returned.
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.

%% \item{comp1 }{Description of 'comp1'}
%% \item{comp2 }{Description of 'comp2'}
%% ...
}

\seealso{
%% ~~objects to See Also as \code{\link{help}}, ~~~
\code{\link{write_dataset}}
\code{\link{read_release}}
}
\examples{
\dontrun{
\donttest{
# library(econdatar)
# Sys.setenv(ECONDATA_CREDENTIALS="username;password")
# for ids/versions see: https://www.econdata.co.za/app

# Electricity Generated
ELECTRICITY <- read_dataset(id = "ELECTRICITY")
Expand All @@ -96,7 +85,5 @@ MARKET_RATES <- read_dataset(id = "MARKET_RATES",
release = "unreleased")
}
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{ load }% use one of RShowDoc("KEYWORDS")
\keyword{ download }% __ONLY ONE__ keyword per line
\keyword{ load }
\keyword{ download }
21 changes: 4 additions & 17 deletions man/read_econdata.Rd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,6 @@ tidy_data(x, \dots)
\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{release} \tab\tab character (optionally with format \%Y-\%m-\%dT\%H:\%M:\%S, that will 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 that moment; 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, usually daily data). \cr
\code{file} \tab\tab character. File name for retrieving JSON data from disk. \cr
\code{username} \tab\tab character. Web username. \cr
\code{password} \tab\tab character. Web password. \cr
}
}
Expand All @@ -47,31 +45,22 @@ tidy_data(x, \dots)
}
}
\details{
An EconData account (http://www.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. \code{Sys.setenv(ECONDATA_CREDENTIALS="username;password")}. If credentials are not supplied by the aforementioned methods a GUI dialog will prompt the user for credentials.
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.
}
\value{
%% ~Describe the value returned
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.

If \code{tidy = TRUE} and \code{wide = TRUE} (the default), a single \emph{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: \code{"label"} provides a variable label combining important metadata from the \code{"metadata"} attribute in the non-tidy format, and \code{"source.code"} gives the series code assigned by the original data provider. The table has the same dataset-level \code{"metadata"} attribute as the list of data frames if \code{tidy = FALSE}. If multiple datasets (or versions of a dataset if \code{version} is specified as 'all') are being queried, a list of such \emph{data.table}'s is returned.
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.

%% \item{comp1 }{Description of 'comp1'}
%% \item{comp2 }{Description of 'comp2'}
%% ...
}

\seealso{
%% ~~objects to See Also as \code{\link{help}}, ~~~
\code{\link{write_econdata}}
\code{\link{read_release}}
}
\examples{
\dontrun{
\donttest{
# library(econdatar)
# Sys.setenv(ECONDATA_CREDENTIALS="username;password")
# for ids/versions see: https://www.econdata.co.za/app

# Electricity Generated
ELECTRICITY <- read_econdata(id = "ELECTRICITY")
Expand All @@ -95,7 +84,5 @@ MARKET_RATES <- read_econdata(id = "MARKET_RATES",
release = "unreleased")
}
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{ load }% use one of RShowDoc("KEYWORDS")
\keyword{ download }% __ONLY ONE__ keyword per line
\keyword{ load }
\keyword{ download }
20 changes: 4 additions & 16 deletions man/read_registry.Rd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,40 +21,28 @@ read_registry(structure, tidy = FALSE, \dots)
\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{file} \tab\tab character. File name for retrieving structures stored as JSON data from disk (output of \code{read_registry()}). \cr
\code{username} \tab\tab character. Web username. \cr
\code{password} \tab\tab character. Web password. \cr
}
}

\item{tidy}{logical. Return data and metadata in tidy \emph{data.table}'s (see Value), by passing the result through \code{tidy_data}. Currently not used.
}
}
\details{
An EconData account (http://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. \code{Sys.setenv(ECONDATA_CREDENTIALS="username;password")}. If credentials are not supplied by the aforementioned methods a GUI dialog will prompt the user for credentials.
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.
}
\value{
%% ~Describe the value returned
If \code{tidy = FALSE}, a list detailing at a minimum the structure's agencyid, id, version, name, and description, as well as a data.frame with rows containing the data of any child structures.

%% \item{comp1 }{Description of 'comp1'}
%% \item{comp2 }{Description of 'comp2'}
%% ...
}

\seealso{
%% ~~objects to See Also as \code{\link{help}}, ~~~
\code{\link{write_registry}}
}
\examples{
\dontrun{
\donttest{
# library(econdatar)
# Sys.setenv(ECONDATA_CREDENTIALS="username;password")

# Frequency codelist
CL_FREQ <- read_registry("codelist", id = "CL_FREQ")
}
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{ load }% use one of RShowDoc("KEYWORDS")
\keyword{ download }% __ONLY ONE__ keyword per line
\keyword{ load }
\keyword{ download }
Loading

0 comments on commit a851ec7

Please sign in to comment.