--- title: "Getting Started" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Getting Started} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` ```{r setup} library(virionData) library(frictionless) library(kableExtra) library(glue) library(stringr) ``` The **virionData** package is meant to facilitate access to the virion dataset on Zenodo and nudge users towards best practices for data use. ## Make a new deposit object The virionData package contains a [class of object](https://r6.r-lib.org/articles/Introduction.html#basics) called a deposit. The deposit object contains attributes related to the Zenodo deposit, allows you to establish a working version of the data, and contains methods for accessing versioned data. ```{r new virion} virion <- deposit$new() # see the latest version of virion virion$get_latest_version() # see a table of all versions, their publication dates, and doi's virion$get_summary_df() |> head() ``` ## Set the working version After you make a new deposit object, you will likely want to set the data version. Here you can supply a specific Zenodo id OR simply use "latest" to get the latest version of the data. Setting the working version will add some additional metadata to your virion object and enable you to start working with data. `virion$working_files` will be added to the object, allowing you to specify the files you'd like to work with. ```{r set working version} # get the latest version of the data virion$set_working_version(zenodo_id = "latest") # Get a specific version of the data. # It is usually a good idea to explicitly provide the version id. virion$set_working_version(zenodo_id = "20517628", print_bibtex = FALSE, print_citation = FALSE) # after you've set the working version, you can get the working citation or working bibtex. virion$get_working_citation() # you can also see the files contained in that version of virion # the file_key field is used throughout the package to access the files. virion$get_working_files() ``` ## Start working with data Here you have two options. One is to download a persistent copy of the data to your machine and the other is to load the data from Zenodo without storing a persistent copy. *Note* Starting in May 2026, taxonomic data is split from the main `virion.csv.gz` file and can be joined based on TaxHashID. `load_*_csv` assumes you are trying to load the data from the current working version. ```{r get the data} # if the csv is not already downloaded, it will be downloaded first virion_data <- virion$load_local_csv_file(file_key = "virion.csv.gz", refresh = TRUE) # loading a remote csv creates a temporary file that will be deleted when # the R session ends. virion_data_remote <- virion$load_remote_csv_file(file_key = "virion.csv.gz") # While files for a particular version of virion on Zenodo are unlikely to change, # you can re-download cached files by using the the refresh parameter. virion_data_remote <- virion$load_remote_csv_file(file_key = "virion.csv.gz", refresh = TRUE) ``` ## What do the fields mean? The `datapackage.json` describes the contents of the files, including field level descriptions. The `get_data_dictionary` method creates a table of field names, types, and descriptions for each csv file. ```{r data-dictionary, results='asis'} data_dictionary <- virion$get_data_dictionary(refresh = FALSE) data_dictionary$virion_csv |> dplyr::mutate(description = stringr::str_wrap(description)) |> kableExtra::kbl() |> kableExtra::kable_material(full_width = FALSE) |> kableExtra::column_spec(3, width = "30em") ``` ## Citation information You can get the citation text or bibtex for the working version. ```{r citation} virion$get_working_citation() |> stringr::str_wrap() |> cat() ``` ```{r bibtex} virion$get_working_bibtex() |> cat() ``` ## Working version deposit metadata If you want to access the full deposit metadata for the current working version, maybe to dig into the persistent identifier graph or pull out the code version used to make the data, you can do that by looking at the `working_json` field. ```{r working_version_metadata} ## get the working json working_json <- virion$get_working_json() ## When was the version last modified? working_json$modified ## What version of the `virion` codebase was used to make this version of virion? working_json$metadata$related_identifiers |> dplyr::filter(resource_type == "software") |> dplyr::pull(identifier) |> (\(val) glue::glue("https://doi.org/{val}"))() ``` ## Functional programming approach This approach uses package environment variables, making working with multiple versions slightly more complicated. Users also need to be aware of when the working version will and won't be changed, and when that will impact the way functions work. Changes set in the R6 object will not be propogated ### Check available versions of the dataset ```{r list deposits} list_deposit_versions() deposit_summary() |> head() ``` ## Get latest version of the data ```{r get data} # get data - by default this is the latest version of the data. get_versioned_data(version = "15692263", dir_path = "outputs") # list files fs::dir_ls("outputs/15692263") ``` ## Read the data Now that you have the data locally, you can read it! The virion files are comma delimited with period decimal markers. ```{r read data, eval=FALSE} virion <- vroom::vroom(file = "outputs/15692263/virion.csv.gz") ``` ## Cite the data Citing data makes increases reproducibility and incentivizes data sharing. ```{r citation-functional, results='markup'} # by default the citation will be generated for the current working version. # this is set when we run `get_versioned_data` get_version_citation(style = "modern-language-association") ``` ```{r citation-specific, results='markup'} # we can cite a specific version by providing a zenodo id get_version_citation(zenodo_id = "15643004",style = "apa") ``` ```{r bibtex export} # sometimes you want a bibtex entry item export_deposit_bibtex("15643004") ``` ### What about the data sources? The data sources used to create Virion are referenced directly in the deposit metadata. These can be accessed by retrieving the deposit metadata. ```{r data sources, results='asis'} metadata_json_text <- export_deposit_metadata(zenodo_id = "15692263",format = "json",verbose = FALSE) metadata_list <- jsonlite::fromJSON(metadata_json_text,) related_identifiers <- metadata_list$metadata$related_identifiers required_items_filter <- related_identifiers$relation_type$id == "requires" required_items <- related_identifiers[required_items_filter,] required_items$resource_type <- required_items$resource_type$id required_items$relation_type <- "requires" required_items |> kableExtra::kable() |> kableExtra::kable_material() ``` ## What do the fields in VIRION mean? Great question! The datapackage.json file contains field descriptions. It is fairly human readable but we can take a closer look using some built in functions. For a deeper dive, check out the [frictionless](https://docs.ropensci.org/frictionless/) package. ```{r frictionless} # this function wraps frictionless functions and extracts dict_list <- get_data_dictionary(datapackage_json = "outputs/15692263/datapackage.json") dict_list$detection_csv ``` Use `purrr::map` to make a full data dictionary for a given deposit. ```{r frictionless tables, results='asis'} html_tables <- purrr::map(dict_list, function(x){ html_tables <- kableExtra::kable(x = x) |> kableExtra::kable_material() }) list_items <- names(dict_list) tables <- sprintf("

%s


%s",list_items,html_tables) |> paste(collapse = "
") cat(tables) ```