M DESCRIPTION => DESCRIPTION +9 -9
@@ 2,20 2,20 @@ Package: SNBdata
Type: Package
Title: Download Data from the Swiss National Bank (SNB)
Version: 0.2.0
-Date: 2023-10-11
+Date: 2023-12-11
Maintainer: Enrico Schumann <es@enricoschumann.net>
Authors@R: person("Enrico", "Schumann",
role = c("aut", "cre"),
email = "es@enricoschumann.net",
comment = c(ORCID = "0000-0001-7601-6576"))
-Description: Functions for downloading data (tables and
- datasets) from the Swiss National Bank (SNB;
- <https://www.snb.ch/>), the Swiss central bank. The
- package is lightweight and comes with few dependencies;
- suggested packages are used only if data is to be
- transformed into particular data structures, for instance
- into 'zoo' objects. Downloaded data can optionally be
- cached, to avoid repeated downloads of the same files.
+Description: Functions for downloading data (tables and datasets)
+ from the Swiss National Bank (SNB; <https://www.snb.ch/en>),
+ the Swiss central bank. The package is lightweight and
+ comes with few dependencies; suggested packages are used
+ only if data is to be transformed into particular data
+ structures, for instance into 'zoo' objects. Downloaded
+ data can optionally be cached, to avoid repeated downloads
+ of the same files.
Suggests: jsonlite, zoo
License: GPL-3
URL: http://enricoschumann.net/R/packages/SNBdata/ ,
M NEWS => NEWS +7 -9
@@ 1,20 1,18 @@
-v0.2.0 (2023-10-10; not released yet)
+v0.2.0 (2023-12-11)
o New functions "fetch_data", "fetch_last_update" and
- "fetch_info", which replace the previous functions
- that worked for only tables or datasets.
+ "fetch_info", which replace the previous functions that
+ worked for only tables or datasets.
- o Retrieved data get an attribute "dimensions", which
- includes the available information about
- identifiers/ code lists. (If package "jsonlite" is
- available, that information is readably arranged.)
+ o Retrieved data gain an attribute "info", which includes
+ the available information about identifiers/code lists.
+ If package "jsonlite" is available, that information is
+ readably arranged.
o Experimental: "fetch_data" gains an argument
"time.series". If TRUE, tables and datasets are
transformed into time-series.
- o ....
-
v0.1.0 (2023-08-31)
o Initial version: Allows to download tables from the
M R/functions.R => R/functions.R +2 -2
@@ 25,6 25,7 @@ fetch_data <- function(id,
dest.dir = dest.dir,
name.sep = name.sep,
method = method)
+ info <- unlist(info)
if (!is.null(dest.dir)) {
filename <- paste0(format(Sys.Date(), "%Y%m%d"),
@@ 158,8 159,7 @@ fetch_data <- function(id,
result <- NA
}
-
- attr(result, "dimensions") <- unlist(info)
+ attr(result, "info") <- info
result
}
M README.md => README.md +44 -3
@@ 1,7 1,7 @@
# SNBdata
Functions for downloading data from the Swiss National Bank
-(SNB; <https://data.snb.ch/>), the Swiss central bank. The
+(SNB; <https://data.snb.ch>), the Swiss central bank. The
package is lightweight and comes with few dependencies;
suggested packages are used only if data is to be
transformed into particular data structures, for instance
@@ 10,11 10,52 @@ cached, to avoid repeated downloads of the same files.
## Installation
-To install the package from a running R session, type:
+To install the development version of the package from a
+running R session, type:
install.packages('SNBdata',
repos = c('http://enricoschumann.net/R',
getOption('repos')))
-or clone/build the repository's latest version.
+or clone/build the git repository's latest version.
+
+
+## Examples
+
+(Examples require an internet connection.)
+
+Start by setting the directory for storing the files.
+This is only an example: Much better is to use a permanent
+storage-location, such as '~/Downloads/SNBdata'
+
+ data.dir <- tempdir()
+
+Now fetch data:
+
+ rates <- fetch_data("rendoblim",
+ type = "table",
+ dest.dir = data.dir,
+ language = "en")
+
+Have data transformed into time-series:
+
+ rates <- fetch_data("rendoblim",
+ type = "table",
+ dest.dir = data.dir,
+ language = "en",
+ time.series = TRUE)
+
+Information about identifiers/codes:
+
+ if (!is.null(rates)) ## check: if download failed, results
+ ## are NULL
+ attr(rates, "info")
+
+Another example:
+
+ stock.markets <- fetch_data("capchstocki",
+ type = "table",
+ dest.dir = data.dir,
+ time.series = TRUE)
+ ## e.g.: stock.markets[, "GDR"] ## total return index
M man/SNBdata.Rd => man/SNBdata.Rd +34 -30
@@ 8,13 8,13 @@
\title{
Download Data from the Swiss National Bank (SNB)
}
-\description{
+\description{%
- Download datasets from the Swiss National Bank (SNB)
- and convert to data-frames.
+ Download data (\sQuote{tables} and \sQuote{datasets}) from the
+ Swiss National Bank (\acronym{SNB}) and convert to data-frames.
}
-\usage{
+\usage{%
fetch_data(id,
type = "table", dest.dir = NULL,
return.class = NULL, verbose = TRUE,
@@ 37,7 37,7 @@ fetch_info(id,
}
\arguments{
\item{dest.dir}{%
- file path: where to store the files?
+ file path: where to store the downloaded files? See Details.
}
\item{id}{%
string: identifier of the table/dataset
@@ 52,11 52,13 @@ fetch_info(id,
logical: print messages, e.g. about download progress?
}
\item{return.class}{%
+
\code{NULL} or character: not yet implemented (but in
future versions, \code{\link[zoo]{zoo}} will be supported)
+
}
\item{language}{%
- string: \code{en}, \code{fr}, or \code{de}
+ string: \code{en}, \code{fr} or \code{de}
}
\item{\dots}{%
passed on to \code{\link{read.table}}
@@ 70,50 72,55 @@ fetch_info(id,
}
\item{na.drop}{%
logical. If \code{TRUE}, rows with no finite values at all
- are dropped. Only used if \code{timeseries} is
+ are dropped. Only used if \code{time.series} is
\code{TRUE}.
}
}
-\details{
+\details{%
- The Swiss National Bank (SNB) provides data as either
+ The Swiss National Bank (\acronym{SNB}) provides data as either
so-called tables or datasets. \code{fetch_table} can handle
both, but the \code{type} argument must be specified.
\code{fetch_table} downloads data, which typically are in
- CSV format, from the SNBs's website and stores them, with a
- date prefix, in directory \code{dest.dir}. If the latter is
- \code{NULL}, a temporary directory is used (through
- \code{\link{tempdir}}); but much better is to use a
- more-persistant storage location. If a file with today's
- date exists in \code{dest.dir}, that file is read, and
- nothing is downloaded.
+ \acronym{csv} format, from the \acronym{SNB}'s website and
+ stores them, with a date prefix, in directory \code{dest.dir}.
+ If the latter is \code{NULL}, a temporary directory is used
+ (through \code{\link{tempdir}}); but much better is to use a
+ more-persistent storage location. If a file with today's date
+ exists in \code{dest.dir}, that file is read, and nothing is
+ downloaded.
+
+ For downloading, function \code{\link{download.file}} is used.
+ See \code{\link{download.file}} for options; in particular, see
+ the hints about \code{timeout} when downloading large files.
When argument \code{time.series} is \code{TRUE},
\code{fetch_table} will rearrange the data into time-series.
This requires columns named \dQuote{\code{Date}} and
- \dQuote{\code{Value}} in the particular dataset/table. If
- the \dQuote{\code{Date}} column has a \code{YYYY-MM-DD}
- pattern, it will will be transformed with
- \code{\link{as.Date}}.
+ \dQuote{\code{Value}} in the particular dataset/table. If the
+ \dQuote{\code{Date}} column has a \code{YYYY-MM-DD} pattern,
+ it will will be transformed with \code{\link{as.Date}}.
+
}
-\value{
+\value{%
+
typically a \code{\link{data.frame}},
potentially with attributes additional attributes:
\describe{
- \item{\code{dimensions}}{%
- information about identifiers used by the SNB
+ \item{\code{info}}{%
+ information about identifiers used by the \acronym{SNB}
}
\item{\code{columns}}{%
- if \code{timeseries} is \code{TRUE}, the names of
- the columns used for grouping the rows
+ if \code{time.series} is \code{TRUE}, the names of the
+ columns used for grouping the rows
}
}
Should the download fail, the function returns
\code{\link{NULL}} invisibly.
}
\references{
- \url{https://data.snb.ch/en/}
+ \url{https://data.snb.ch/en}
for \code{help} on the \acronym{API},
see\url{https://data.snb.ch/en/help#data_api}
@@ 122,9 129,6 @@ fetch_info(id,
\author{
Enrico Schumann
}
-%% \seealso{
-%% package
-%% }
\examples{
\donttest{
## (Internet connection required)
@@ 148,7 152,7 @@ rates <- fetch_data("rendoblim",
if (!is.null(rates)) ## check: if download failed, results
## are NULL
- attr(rates, "dimensions")
+ attr(rates, "info")
stock.markets <- fetch_data("capchstocki",