-
Notifications
You must be signed in to change notification settings - Fork 15
Quick start guide
This guide will get you up and running with the basic functionality of ISRaD. It will explain several methods for obtaining and working with the ISRaD data, and describe how to seamlessly fold your own data into the existing database framework. Detailed descriptions of all software functions and data elements may be found in the ISRaD User Guide.
In order to use ISRaD, it is important to understand what the database consists of:
ISRaD begins with a collection of data extracted from a large number of published studies and unpublished contributions. Extracted data are standardized to a common template and stored as a Microsoft Excel spreadsheet (.xlsx), with one spreadsheet file per publication/contribution.
ISRaD also consists of compilation software--written in the R programming language--that checks Excel spreadsheets for consistency, collates them into the full database as an object in the R language, and outputs the R object into a single large Excel spreadsheet or comma-separated values (.csv) file.
Thus, each versioned release of ISRaD comprises the individual data template files, the collated data file(s), and the software that created the latter from the former. These elements are hosted in a repository on github.com.
Depending on your goals, there are multuple ways of obtaining and working with software and data from ISRaD. However, there are two questions that can determine your needs:
If you simply want to use the data that is already part of ISRaD, you will not need to run the ISRaD compilation software. Instead, you may simply access the data that has already been compiled, and is now hosted on the github repository (Scenarios 1 and 2 below). If you have additional data that is not already part of ISRaD, and you would like to combine it with the existing ISRaD database, then you will need to run the compilation software yourself using (Scenarios 3 and 4 below).
If you prefer to work with the data in a programming environment other than R, you can chose either the Excel spreadsheet or the CSV file as the medium for transferring your data (Scenarios 1 and 3 below). If R is your programming language of choice, then you can interact directly with the R object that is built by the compilation software (Scenarios 2 and 4 below).
In this case, you only need the compiled Excel spreadsheet ISRaD_list.xlsx or the comma-separated file ISRaD_flat.csv from the github repository in the ISRaD/ISRaD_Data/database/ directory. You can either clone the entire github repository, which contains both files, or you can simply download just those files from the github web interface. Note that the comma-separated file has been flattened across the ISRaD data hierarchy, so the file size can be quite large, compared to the Excel spreadsheet that lists different levels of the hierarchy separately.
In this case, you do not need to clone the repository using git, or download anything from the web interface. Instead, you can pull the R objects directly from github within R using the following:
install.packages("devtools")
library(devtools)
install_github("International-Soil-Radiocarbon-Database/ISRaD")
library(ISRaD)
The ISRaD_data object will be added to the R environment.
In this case, you will need to clone the entire repository from github using
git clone git@github.com:International-Soil-Radiocarbon-Database/ISRaD.git
The directory ISRaD/ISRaD_Data/ contains the Excel templates for all of the existing ISRaD data. You will add Excel templates for your data to this directory. You will need to run the QAQC tool on all of your Excel templates. You can do this using either the online QAQC tool, or the QAQC.R script in ISRaD/R/. Once your templates have been added, you will run the compile.R script in ISRaD/R/. The collated Excel spreadsheet and the flattened CSV file will be saved to the directory ISRaD/ISRaD_Data/database/.
Some additional packages are used within ISRaD tools, and can currently lead to errors if the packages are not already installed. The most common missing packages are tidyr, diplyr, openxlsx, rcrossref, RCurl, and magrittr. Use the install.packages() R function. Remember, you may need to load the packages with the library() command.