Package 'contactsurveys'

Directory for persistent storage of contact surveys

Description

Returns a platform-specific directory for persistent storage of downloaded survey files, powered by tools::R_user_dir(). You can override this by setting the environment variable CONTACTSURVEYS_HOME.

Usage

contactsurveys_dir()

Details

By default, download_survey() and list_surveys() use tempdir() so files do not persist across R sessions. To enable persistent caching, pass contactsurveys_dir() as the directory argument, e.g. download_survey(survey, directory = contactsurveys_dir()).

Value

the active contactsurveys directory.

Examples

contactsurveys_dir()

## Override with an environment variable:
Sys.setenv(CONTACTSURVEYS_HOME = tempdir())
contactsurveys_dir()
## Unset
Sys.unsetenv("CONTACTSURVEYS_HOME")

---

Delete files in contactsurveys directory

Description

Delete files in contactsurveys directory

Usage

delete_contactsurveys_files(dir = contactsurveys_dir())

delete_contactsurveys_dir(dir = contactsurveys_dir())

Arguments

dir	directory to list files to delete from

Value

nothing, deletes files.

Examples

delete_contactsurveys_files()

---

Delete files for a given survey

Description

For when you want to delete files associated with a given survey.

Usage

delete_survey(survey)

Arguments

survey

Survey, as used in download_survey().

Value

nothing, deleted files

See Also

delete_contactsurveys_dir() delete_contactsurveys_files()

Examples

peru_doi <- "https://doi.org/10.5281/zenodo.1095664"
delete_survey(peru_doi)

---

Download a survey from its Zenodo repository

Description

Downloads survey data. Uses a caching mechanism via the default argument for directory.

Usage

download_survey(
  survey,
  directory = tempdir(),
  verbose = TRUE,
  overwrite = FALSE,
  timeout = 3600,
  rate = purrr::rate_backoff(pause_base = 5, max_times = 4)
)

Arguments

survey	A DOI of a survey, (see list_surveys()). If a HTML link is given, the DOI will be isolated and used.
directory	Directory of where to save survey files. Defaults to tempdir(), so files do not persist across R sessions. For persistent caching, pass contactsurveys_dir(), which uses tools::R_user_dir() and appends the survey URL/DOI basename as a subdirectory. E.g., if you provide "10.5281/zenodo.1095664" in the survey argument, it will save the surveys into a directory zenodo.1095664 under contactsurveys_dir(). You can also set an environment variable, CONTACTSURVEYS_HOME, see Sys.setenv() or Renviron for more detail.
verbose	Whether downloads should be echoed to output. Default TRUE.
overwrite	If files should be overwritten if they already exist. Default FALSE
timeout	A numeric value specifying timeout in seconds. Default 3600 seconds.
rate	a purrr rate object, to facilitate downloading if the download fails. Defaults to an exponential backoff of 5 seconds (up to 4 attempts: 1 initial + 3 retries) changed by specifying your own rate object, see ?purrr::rate_backoff() for details.

Value

a vector of filenames, where the surveys were downloaded

See Also

list_surveys()

Examples

list_surveys()
peru_survey <- download_survey("https://doi.org/10.5281/zenodo.1095664")

---

Get citation from a DOI

Description

This is a wrapper around zen4R::get_citation() with a couple of smaller changes. Firstly, it silences output from zen4R::get_citation(), secondly the default citation style is "apa".

Usage

get_citation(
  doi,
  style = c("bibtex", "apa", "harvard-cite-them-right", "modern-language-association",
    "vancouver", "chicago-fullnote-bibliography", "ieee"),
  verbose = TRUE
)

Arguments

doi	A string, the Zenodo DOI or concept DOI.
style	A string, the citation style. Default is "bibtex". Possible values are: "bibtex", "harvard-cite-them-right", "apa", "modern-language-association", "vancouver", "chicago-fullnote-bibliography", or "ieee".
verbose	logical. Should messages during citation fetching print to the screen? Default is TRUE.

Value

A character string containing the citation in the requested style. For "bibtex" style, returns an object of class "csbib".

Examples

polymod_doi <- "https://doi.org/10.5281/zenodo.3874557"
get_citation(polymod_doi)

---

Checks if a character string is a DOI

Description

Checks if a character string is a DOI

Usage

is_doi(x)

Arguments

x	Character vector; the string or strings to check

Value

Logical; TRUE if x is a DOI, FALSE otherwise

Author(s)

Sebastian Funk

---

List all surveys available for download

Description

List all surveys available for download

Usage

list_surveys(
  directory = tempdir(),
  overwrite = FALSE,
  verbose = TRUE,
  rate = purrr::rate_backoff(pause_base = 5, max_times = 4)
)

Arguments

directory	Directory to save the cached survey list. Defaults to tempdir(), so the cached list does not persist across R sessions. For persistent caching, pass contactsurveys_dir().
overwrite	If files should be overwritten if they already exist. Default FALSE
verbose	Whether downloads should be echoed to output. Default TRUE.
rate	a purrr rate object, to facilitate downloading if the download fails. Defaults to an exponential backoff of 5 seconds (up to 4 attempts: 1 initial + 3 retries) changed by specifying your own rate object, see ?purrr::rate_backoff() for details.

Value

data.table with columns: date_added, title, creator, url

Examples

list_surveys()

---

List files in contactsurveys cache

Description

It can be handy to see which files are available, sometimes to return to a clean slate and delete them via the ⁠delete_contactsurveys_*()⁠ functions.

Usage

ls_contactsurveys(dir = contactsurveys_dir())

Arguments

dir	Directory to list. Default is contactsurveys_dir().

Value

Character vector of file paths under dir (absolute paths).

See Also

delete_contactsurveys_files() delete_survey() delete_contactsurveys_dir() download_survey() contactsurveys_dir()

Examples

ls_contactsurveys()

---

Print a csbib citation

Description

Print a csbib citation

Usage

## S3 method for class 'csbib'
print(x, ...)

Arguments

x	A "csbib" object.
...	Additional arguments passed to methods.

Value

Invisibly returns x.

---