Type: Package
Title: Evolving Earth System Variables
Version: 0.6.1
Maintainer: Adam T. Kocsis <adam.t.kocsis@gmail.com>
Description: The implemented functions allow the query, download, and import of remotely-stored and version-controlled data items. The inherent meta-database maps data files and import code to programming classes and allows access to these items via files deposited in public repositories. The purpose of the project is to increase reproducibility and establish version tracking of results from (paleo)environmental/ecological research.
License: CC BY 4.0
Collate: global.R attributes.R call.R datasets.R fetching.R info.R utility.R zzz.R
Date: 2023-08-17
BugReports: https://github.com/chronosphere-info/r_client/issues
Encoding: UTF-8
Depends: R (≥ 3.5.0)
Imports: utils, tools
NeedsCompilation: no
RoxygenNote: 7.2.3
Suggests: curl, tinytest
Packaged: 2023-08-17 08:39:52 UTC; root
Author: Adam T. Kocsis ORCID iD [cre, aut], Nussaibah B. Raja ORCID iD [aut], Deutsche Forschungsgemeinschaft [fnd], FAU GeoZentrum Nordbayern [fnd]
Repository: CRAN
Date/Publication: 2023-08-17 12:33:00 UTC

Evolving Earth System Variables

Description

The implemented functions allow the query, download, and import of remotely-stored and version-controlled data items. The inherent meta-database maps data files and import code to programming classes and allows access to these items via files deposited in public repositories. The purpose of the project is to increase reproducibility and establish version tracking of results from (paleo)environmental/ecological research.

This is still a Release Candidate version. As is R, this is free software and comes with ABSOLUTELY NO WARRANTY. Nevertheless, notes about found bugs and suggestions are more than welcome. The chronosphere links to data and code deposited on public servers, which can be inspected using the code and data URLs of the items (codeURL, primaryURL and secondaryURL in the result of datasets(master=TRUE)). By using this package you agree that you take responsibility for the items that you download. Never run fetch() as a superuser or with administrative privileges! Doing this can open up a security hole to be exploited in case the remote servers get hijacked.

Author(s)

Adam T. Kocsis (adam.t.kocsis@gmail.com)

Function to configure the behavior of the chronosphere package.

Description

This function will allow you to set package variables.

Usage

configure(timeout = NULL, remote = NULL, curl = NULL)

Arguments

timeout

Timeout option used with default R download socket. The global default value for this is 500, which can be increased for very large files and a slow internet connection. Has no effect, when curl=TRUE.

remote

Character string which is the URL of the chronos server.

curl

Logical value of the 'curl' package variable.

Details

The following package-wide variables can be set. timeout: Positive integer. Timeout of connections in seconds when the default R sockets are used. The global setting by default is '300'. #' remote: Character string. URL of the chronosphere repositories, the default value is "https://github.com/chronosphere-info/chrono_arch/raw/main/". curl: Logical value. If set to TRUE (default), the curl libraries are used to download files. If set to FALSE (default) the default R sockets are used, which can result in timeout issues that need to be resolved manually.

Value

The function has no return value.

Examples

configure(curl=FALSE)

Download a database extract from chronosphere remote server

Description

The function will download a list of available series from the data repository

Usage

datasets(
  src = NULL,
  datadir = NULL,
  verbose = FALSE,
  master = FALSE,
  greetings = TRUE,
  all = FALSE
)

Arguments

src

character. Source identifier. If this is set to NULL, then a simplified list of availables series will be downloaded, including all unique src and ser combinations. If src is a valid source identifier, then all accessible products (resolutions and versions) of a series are shown.

datadir

character Directory where the downloaded files are kept. Individual entries will be looked up from the directory if this is given, and will be downloaded if they are not found. The default NULL option will download data to a temporary directory that exists only until the R session ends.

verbose

logical Should console feedback during download be displayed?

master

logical When src is NULL, should the function download the master records file?

greetings

logical When the function is invoked without arguments, it displays a message to keep new users informed about different versions and resolutions (even with verbose=FALSE). This argument turns this message off on demand.

all

logical When set to FALSE (default), only those items are shown that are available for the R environment. Set to TRUE to see all items.

Details

The function will download a single .csv file and attach it as a data.frame.

Value

A data.frame class object.

Examples

# available datasets (sources and series) - proper
# index <- datasets()
# all available versions and resolutions in database 'pbdb'
# oneDat <- datasets(src="pbdb")
###################################
# local example INCOMPLETE - does not connect to the internet
ind <- datasets(
  datadir=system.file("extdata", package="chronosphere"))
# one available archive
ind <- datasets(
  src="SOM-zaffos-fragmentation",
  datadir=system.file("extdata", package="chronosphere"))

Fetching data items

Description

Function to download and attach items from the chronosphere archives

Usage

fetch(
  src = NULL,
  ser = NULL,
  ver = NULL,
  res = NULL,
  ext = NULL,
  class = NULL,
  item = NULL,
  datadir = NULL,
  verbose = TRUE,
  call = FALSE,
  call.expr = FALSE,
  attach = TRUE,
  ...
)

Arguments

src

(character) The source of the series.

ser

(character) The series to get.

ver

(character) The version of the product to download. Defaults to NULL, which will download the latest available version.

res

(character or numeric) The resolution string of the data.

ext

(character) File extension of the used data file.

class

(character) Class of the returned object, if not the default.

item

(numeric) The item ID that is to be downloaded. This setting overrides all other identifiers.

datadir

(character) Directory where downloaded files are kept. Individual items will be looked up from the directory if this is given, and will be downloaded if they are not found. The default NULL option will download data to a temporary directory that exists only until the R session ends.

verbose

(logical) Should console feedback during download be displayed?

call

(logical) If set to TRUE the function call is returned instead of the object.

call.expr

(logical) If call is set to TRUE, then should the call be returned as an expression (TRUE) or a message (FALSE)?

attach

(logical) If the item has required packages, should these be attached?

...

Arguments passed to item-specific loading functions.

Details

Use the function datasets to find available series.

Value

An object from a class that matches the 'class' coordinate of the item.

Examples

# An actual download call
# a <- fetch(src="paleomap", ser="dem")
# A locally-present object, in package's directory
a <- fetch(src="SOM-zaffos-fragmentation",
  datadir=system.file("extdata", package="chronosphere"))
# call repetition
fetch(a, call=TRUE)

Documentation page of a series (Remote server under construction)

Description

Documentation page of a series (Remote server under construction)

Usage

info(src, ser = NULL)

Arguments

src

(character) Object downloaded with fetch or the source identifier string.

ser

(character) In case src is character, the series identifier.

Value

The function has no return value.

Retrieve citation of data object

Description

The function prints or returns the citation string of a chosen object/item.

Usage

reference(
  src,
  bibtex = FALSE,
  ser = NULL,
  ver = NULL,
  print = TRUE,
  prefix = ""
)

Arguments

src

(characater) Object downloaded with fetch or the source identifier string.

bibtex

(logical) Should a bibtex be printed/returned?

ser

(character) In case src is character, the series identifier.

ver

(character) In case src is character, the version identifier.

print

(logical) Should the citations be printed to the console, or returned as a character vector.

prefix

(characater) In case the output is printed on the console. Use this to include a prefix before every entry.

Value

By default the function has no return value. If print=FALSE, the function will return a reference character string.

Examples

# A locally-present object, in package's directory
one <- fetch(src="SOM-zaffos-fragmentation",
  datadir=system.file("extdata", package="chronosphere"))
# its reference
reference(one)