diff --git a/DESCRIPTION b/DESCRIPTION index 993750e..34e9178 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -14,18 +14,18 @@ Authors@R: c( email = "thosjleeper@gmail.com", comment = c(ORCID = "0000-0003-4097-6326") ), - person( - "Philip", "Durbin", - role = c("aut"), - email = "philipdurbin@gmail.com", - comment = c(ORCID = "0000-0002-9528-9470") - ), person( "Shiro", "Kuriwaki", role = c("aut"), email = "shirokuriwaki@gmail.com", comment = c(ORCID = "0000-0002-5687-2647") ), + person( + "Philip", "Durbin", + role = c("aut"), + email = "philipdurbin@gmail.com", + comment = c(ORCID = "0000-0002-9528-9470") + ), person( "Sebastian", "Karcher", role=c("aut"), @@ -53,9 +53,9 @@ Suggests: testthat, UNF, yaml -Description: Provides access to Dataverse version 4 APIs , - enabling data search, retrieval, and deposit. For Dataverse versions <= 4.0, - use the deprecated 'dvn' package . +Description: Provides access to Dataverse APIs (versions 4-5), + enabling data search, retrieval, and deposit. For Dataverse versions <= 3.0, + use the archived 'dvn' package . License: GPL-2 LazyData: true URL: https://github.com/iqss/dataverse-client-r diff --git a/R/get_dataframe.R b/R/get_dataframe.R index cacc3a5..c6350be 100644 --- a/R/get_dataframe.R +++ b/R/get_dataframe.R @@ -1,7 +1,9 @@ -#' Get file from dataverse and convert it into a dataframe or tibble +#' Download dataverse file as a dataframe #' -#' `get_dataframe_by_id`, if you know the numeric ID of the dataset, or instead -#' `get_dataframe_by_name` if you know the filename and doi. The dataset +#' Use `get_dataframe_by_name` if you know the name of the datafile and the DOI +#' of the dataset. Use `get_dataframe_by_doi` if you know the DOI of the datafile +#' itself. Use `get_dataframe_by_id` if you know the numeric ID of the +#' datafile. #' #' @rdname get_dataframe #' @@ -9,9 +11,9 @@ #' `"roster-bulls-1996.tab"`. #' @param .f The function to used for reading in the raw dataset. This user #' must choose the appropriate function: for example if the target is a .rds -#' file, then `.f` should be `readRDS` or `readr::read_`rds`. +#' file, then `.f` should be `readRDS` or `readr::read_rds`. #' @param original A logical, defaulting to TRUE. Whether to read the ingested, -#' archival version of the dataset if one exists. The archival versions are tab-delimited +#' archival version of the datafile if one exists. The archival versions are tab-delimited #' `.tab` files so if `original = FALSE`, `.f` is set to `readr::read_tsv`. #' If functions to read the original version is available, then `original = TRUE` #' with a specified `.f` is better. @@ -20,15 +22,15 @@ #' #' @examples #' # Retrieve data.frame from dataverse DOI and file name -#' df_from_rds_ingested <- +#' df_tab <- #' get_dataframe_by_name( #' filename = "roster-bulls-1996.tab", #' dataset = "doi:10.70122/FK2/HXJVJU", #' server = "demo.dataverse.org" #' ) #' -#' # Retrieve the same data.frame from dataverse + file DOI -#' df_from_rds_ingested_by_doi <- +#' # Retrieve the same file from file DOI +#' df_tab <- #' get_dataframe_by_doi( #' filedoi = "10.70122/FK2/HXJVJU/SA3Z2V", #' server = "demo.dataverse.org" @@ -45,11 +47,10 @@ #' server = "demo.dataverse.org" #' ) #' -#' #' # To use the original file version, or for non-ingested data, #' # please specify `original = TRUE` and specify a function in .f. #' -#' # A data.frame is still returned, but the +# Rds files are not ingested so original = TRUE and .f is required. #' if (requireNamespace("readr", quietly = TRUE)) { #' df_from_rds_original <- #' get_dataframe_by_name( @@ -61,8 +62,9 @@ #' ) #' } #' +#' # Get Stata file as original #' if (requireNamespace("haven", quietly = TRUE)) { -#' df_from_stata_original <- +#' df_stata_original <- #' get_dataframe_by_name( #' filename = "nlsw88.tab", #' dataset = "doi:10.70122/FK2/PPIAXE", @@ -71,6 +73,15 @@ #' .f = haven::read_dta #' ) #' } +#' +#' # Stata file as ingested file (less information than original) +#' df_stata_ingested <- +#' get_dataframe_by_name( +#' filename = "nlsw88.tab", +#' dataset = "doi:10.70122/FK2/PPIAXE", +#' server = "demo.dataverse.org" +#' ) +#' #' } #' #' @export diff --git a/R/get_file.R b/R/get_file.R index 7964f42..9754af9 100644 --- a/R/get_file.R +++ b/R/get_file.R @@ -1,20 +1,21 @@ #' @rdname files #' -#' @title Download File +#' @title Download dataverse file as a raw binary #' -#' @description Download Dataverse File(s). `get_file` is a general wrapper, -#' and can take either dataverse objects, file IDs, or a filename and dataverse. +#' @description Download Dataverse File(s). `get_file_*` +#' functions return a raw binary file, which cannot be readily analyzed in R. +#' To use the objects as dataframes, see the `get_dataset_*` functions at +#' \link{get_dataset} instead. +#' +#' @details This function provides access to data files from a Dataverse entry. +#' `get_file` is a general wrapper, +#' and can take either dataverse objects, file IDs, or a filename and dataverse. +#' Internally, all functions download each file by `get_file_by_id`. #' `get_file_by_name` is a shorthand for running `get_file` by #' specifying a file name (`filename`) and dataset (`dataset`). #' `get_file_by_doi` obtains a file by its file DOI, bypassing the #' `dataset` argument. #' -#' Internally, all functions download each file by `get_file_by_id`. `get_file_*` -#' functions return a raw binary file, which cannot be readily analyzed in R. -#' To use the objects as dataframes, see the `get_dataset_*` functions at \link{get_dataset} -#' -#' @details This function provides access to data files from a Dataverse entry. -#' #' @param file An integer specifying a file identifier; or a vector of integers #' specifying file identifiers; or, if used with the prefix \code{"doi:"}, a #' character with the file-specific DOI; or, if used without the prefix, a diff --git a/README.Rmd b/README.Rmd index 5585215..847ea41 100644 --- a/README.Rmd +++ b/README.Rmd @@ -1,5 +1,5 @@ --- -title: "R Client for Dataverse 4 Repositories" +title: "R Client for Dataverse Repositories" output: github_document --- @@ -13,7 +13,7 @@ Sys.setenv("DATAVERSE_SERVER" = "dataverse.harvard.edu") [![Dataverse Project logo](https://dataverse.org/files/dataverseorg/files/dataverse_project_logo-hp.png)](https://dataverse.org) -The **dataverse** package provides access to [Dataverse 4](https://dataverse.org/) APIs, enabling data search, retrieval, and deposit, thus allowing R users to integrate public data sharing into the reproducible research workflow. **dataverse** is the next-generation iteration of [the **dvn** package](https://cran.r-project.org/package=dvn), which works with Dataverse 3 ("Dataverse Network") applications. **dataverse** includes numerous improvements for data search, retrieval, and deposit, including use of the (currently in development) **sword** package for data deposit and the **UNF** package for data fingerprinting. +The **dataverse** package provides access to [Dataverse](https://dataverse.org/) APIs (versions 4-5), enabling data search, retrieval, and deposit, thus allowing R users to integrate public data sharing into the reproducible research workflow. **dataverse** is the next-generation iteration of [the **dvn** package](https://cran.r-project.org/package=dvn), which works with Dataverse 3 ("Dataverse Network") applications. **dataverse** includes numerous improvements for data search, retrieval, and deposit, including use of the (currently in development) **sword** package for data deposit and the **UNF** package for data fingerprinting. ### Getting Started @@ -32,7 +32,7 @@ library("dataverse") #### Keys -Some features of the Dataverse 4 API are public and require no authentication. This means in many cases you can search for and retrieve data without a Dataverse account for that a specific Dataverse installation. But, other features require a Dataverse account for the specific server installation of the Dataverse software, and an API key linked to that account. Instructions for obtaining an account and setting up an API key are available in the [Dataverse User Guide](https://guides.dataverse.org/en/latest/user/account.html). (Note: if your key is compromised, it can be regenerated to preserve security.) Once you have an API key, this should be stored as an environment variable called `DATAVERSE_KEY`. It can be set within R using: +Some features of the Dataverse API are public and require no authentication. This means in many cases you can search for and retrieve data without a Dataverse account for that a specific Dataverse installation. But, other features require a Dataverse account for the specific server installation of the Dataverse software, and an API key linked to that account. Instructions for obtaining an account and setting up an API key are available in the [Dataverse User Guide](https://guides.dataverse.org/en/latest/user/account.html). (Note: if your key is compromised, it can be regenerated to preserve security.) Once you have an API key, this should be stored as an environment variable called `DATAVERSE_KEY`. It can be set within R using: ``` r Sys.setenv("DATAVERSE_KEY" = "examplekey12345") diff --git a/README.md b/README.md index 2b75961..bef59be 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -R Client for Dataverse 4 Repositories +R Client for Dataverse Repositories ================ [![CRAN @@ -12,10 +12,10 @@ Status](https://travis-ci.org/IQSS/dataverse-client-r.png?branch=master)](https: logo](https://dataverse.org/files/dataverseorg/files/dataverse_project_logo-hp.png)](https://dataverse.org) The **dataverse** package provides access to -[Dataverse 4](https://dataverse.org/) APIs, enabling data search, -retrieval, and deposit, thus allowing R users to integrate public data -sharing into the reproducible research workflow. **dataverse** is the -next-generation iteration of [the **dvn** +[Dataverse](https://dataverse.org/) APIs (versions 4-5), enabling data +search, retrieval, and deposit, thus allowing R users to integrate +public data sharing into the reproducible research workflow. +**dataverse** is the next-generation iteration of [the **dvn** package](https://cran.r-project.org/package=dvn), which works with Dataverse 3 (“Dataverse Network”) applications. **dataverse** includes numerous improvements for data search, retrieval, and deposit, including @@ -34,7 +34,7 @@ library("dataverse") #### Keys -Some features of the Dataverse 4 API are public and require no +Some features of the Dataverse API are public and require no authentication. This means in many cases you can search for and retrieve data without a Dataverse account for that a specific Dataverse installation. But, other features require a Dataverse account for the @@ -257,13 +257,12 @@ subsequent pages, specify `start`. ### Data Archiving -Dataverse provides two - basically unrelated - workflows for managing -(adding, documenting, and publishing) datasets. The first is built on -[SWORD v2.0](http://swordapp.org/sword-v2/). This means that to create a -new dataset listing, you will have to first initialize a dataset entry with -some metadata, add one or more files to the dataset, and then publish -it. This looks something like the following: - +Dataverse provides two - basically unrelated - workflows for managing +(adding, documenting, and publishing) datasets. The first is built on +[SWORD v2.0](http://swordapp.org/sword-v2/). This means that to create a +new dataset listing, you will have to first initialize a dataset entry +with some metadata, add one or more files to the dataset, and then +publish it. This looks something like the following: ``` r # retrieve your service document diff --git a/man/files.Rd b/man/files.Rd index 7137ad5..6eb2c6a 100644 --- a/man/files.Rd +++ b/man/files.Rd @@ -5,7 +5,7 @@ \alias{get_file_by_name} \alias{get_file_by_id} \alias{get_file_by_doi} -\title{Download File} +\title{Download dataverse file as a raw binary} \usage{ get_file( file, @@ -107,19 +107,20 @@ function. To load datasets into the R environment dataframe, see \link{get_dataframe_by_name}. } \description{ -Download Dataverse File(s). \code{get_file} is a general wrapper, +Download Dataverse File(s). \verb{get_file_*} +functions return a raw binary file, which cannot be readily analyzed in R. +To use the objects as dataframes, see the \verb{get_dataset_*} functions at +\link{get_dataset} instead. +} +\details{ +This function provides access to data files from a Dataverse entry. +\code{get_file} is a general wrapper, and can take either dataverse objects, file IDs, or a filename and dataverse. +Internally, all functions download each file by \code{get_file_by_id}. \code{get_file_by_name} is a shorthand for running \code{get_file} by specifying a file name (\code{filename}) and dataset (\code{dataset}). \code{get_file_by_doi} obtains a file by its file DOI, bypassing the \code{dataset} argument. - -Internally, all functions download each file by \code{get_file_by_id}. \verb{get_file_*} -functions return a raw binary file, which cannot be readily analyzed in R. -To use the objects as dataframes, see the \verb{get_dataset_*} functions at \link{get_dataset} -} -\details{ -This function provides access to data files from a Dataverse entry. } \examples{ \dontrun{ diff --git a/man/get_dataframe.Rd b/man/get_dataframe.Rd index 842fd00..f60ec63 100644 --- a/man/get_dataframe.Rd +++ b/man/get_dataframe.Rd @@ -4,7 +4,7 @@ \alias{get_dataframe_by_name} \alias{get_dataframe_by_id} \alias{get_dataframe_by_doi} -\title{Get file from dataverse and convert it into a dataframe or tibble} +\title{Download dataverse file as a dataframe} \usage{ get_dataframe_by_name( filename, @@ -28,10 +28,10 @@ for example \code{"doi:10.70122/FK2/HXJVJU"}. Alternatively, an object of class \item{.f}{The function to used for reading in the raw dataset. This user must choose the appropriate function: for example if the target is a .rds -file, then \code{.f} should be \code{readRDS} or \code{readr::read_}rds`.} +file, then \code{.f} should be \code{readRDS} or \code{readr::read_rds}.} \item{original}{A logical, defaulting to TRUE. Whether to read the ingested, -archival version of the dataset if one exists. The archival versions are tab-delimited +archival version of the datafile if one exists. The archival versions are tab-delimited \code{.tab} files so if \code{original = FALSE}, \code{.f} is set to \code{readr::read_tsv}. If functions to read the original version is available, then \code{original = TRUE} with a specified \code{.f} is better.} @@ -68,20 +68,22 @@ or globally using \code{Sys.setenv("DATAVERSE_SERVER" = "dataverse.example.com") \code{"10.70122/FK2/PPIAXE/MHDB0O"} or \code{"doi:10.70122/FK2/PPIAXE/MHDB0O"}} } \description{ -\code{get_dataframe_by_id}, if you know the numeric ID of the dataset, or instead -\code{get_dataframe_by_name} if you know the filename and doi. The dataset +Use \code{get_dataframe_by_name} if you know the name of the datafile and the DOI +of the dataset. Use \code{get_dataframe_by_doi} if you know the DOI of the datafile +itself. Use \code{get_dataframe_by_id} if you know the numeric ID of the +datafile. } \examples{ # Retrieve data.frame from dataverse DOI and file name -df_from_rds_ingested <- +df_tab <- get_dataframe_by_name( filename = "roster-bulls-1996.tab", dataset = "doi:10.70122/FK2/HXJVJU", server = "demo.dataverse.org" ) -# Retrieve the same data.frame from dataverse + file DOI -df_from_rds_ingested_by_doi <- +# Retrieve the same file from file DOI +df_tab <- get_dataframe_by_doi( filedoi = "10.70122/FK2/HXJVJU/SA3Z2V", server = "demo.dataverse.org" @@ -98,11 +100,9 @@ df_from_stata_ingested <- server = "demo.dataverse.org" ) - # To use the original file version, or for non-ingested data, # please specify `original = TRUE` and specify a function in .f. -# A data.frame is still returned, but the if (requireNamespace("readr", quietly = TRUE)) { df_from_rds_original <- get_dataframe_by_name( @@ -114,8 +114,9 @@ if (requireNamespace("readr", quietly = TRUE)) { ) } +# Get Stata file as original if (requireNamespace("haven", quietly = TRUE)) { - df_from_stata_original <- + df_stata_original <- get_dataframe_by_name( filename = "nlsw88.tab", dataset = "doi:10.70122/FK2/PPIAXE", @@ -124,6 +125,15 @@ if (requireNamespace("haven", quietly = TRUE)) { .f = haven::read_dta ) } + +# Stata file as ingested file (less information than original) +df_stata_ingested <- + get_dataframe_by_name( + filename = "nlsw88.tab", + dataset = "doi:10.70122/FK2/PPIAXE", + server = "demo.dataverse.org" + ) + } }