Raw data

Raw data should always be included in inst/extdata. If you want to include cleaned/processed data in data/, it is generally a good idea to include the code used to process the raw data. If you ever need to reproduce or update your cleaned data, this will save you precious time. The code for processing your data should be included in data-raw/. Strictly speaking, raw data does not need to be documented. However, it is a good idea to include the original source and version (including a download date) in your code.

Internal data

Data you do not wish to directly make available to the user should be saved as R/sysdata.rda. This is the best option for pre-computed data tables that are needed for a function to run. Strictly speaking internal data does not need to be documented. However, it is a good idea to document the internal data in the function documentation.

Exported data

Package data you wish to make available to the user should be stored in data/. Each file in this directory should be either a '.rda' or '.RData'. This file type is fast, small and explicit. The most appropriate way to include exported data is to use usethis::use_data().

When using large datasets, we want to ensure that our files are not bloated and taking up too much space on our users’ machines. As such, you may want to experiment with the compression settings in usethis::use_data(). Generally, xz and gzip can create smaller files than the default bzip2. You can also implement several ‘hacks’ to generate smaller files which you may want to consider for large datasets (depending on whether your data is sensitive to such changes). Data with many decimal places consume a lot of memory, consider how many significant figures are relevant for your data, and round() accordingly. You can also experiment with your file size by multiplying your data by X (e.g. 1,000) to remove decimal places altogether. Note: Remember to undo any transformations when calling or working with the data.

External data

External data is the preferred approach for contributors to include data into palaeoverse and will be required in almost all cases. This is to ensure that the package does not become unnecessary bloated to all users when the data can just be called by a download link. Currently, external data are stored on a GitHub repo (reconstruction files for palaeorotate). It is likely that in the future this will be migrated elsewhere as GitHub is not a data repository (hopefully a dedicated server when funding allows!). If you wish to include external data, please get in touch with one of the palaeoverse developers, and we can discuss what might be the best solution.

#generate temp directory
files <- tempdir()
#download files
download.file(url = "www.goo.com", destfile = paste0(files, "/mgoo.csv"))
#run some kind function using the download
#REMEMBER: remove downloaded files
unlink(x = paste0(files, "/", list.files(files)))

Data documentation

Objects in data/ are always exported by default, and should be documented accordingly. In order to properly document data, you must document the name of the dataset and save it in R/data. For example, the documentation block used to document GTS2020 is saved as R/data.R and is similar to the following (simplified here):

#' Geological Time Scale 2020
#'
#' A dataset of the Geological Time Scale 2020. Age data from:
#'  \url{https://stratigraphy.org/timescale/}.
#' Supplementary information is also included in the dataset for
#' plotting functionality (e.g. GTS2020 colour scheme).
#'
#' @format A data frame with 189 rows and 20 variables:
#' \describe{
#'   \item{index}{Index number for the order of all intervals in the dataset}
#'   \item{stage_number}{Index number for stages}
#'   \item{series_number}{Index number for series}
#'   \item{system_number}{Index number for system}
#'   \item{interval_name}{Names of intervals in the dataset}
#'   ...
#' }
#' @section References:
#' Gradstein, F.M., Ogg, J.G., Schmitz, M.D. and Ogg, G.M. eds. (2020).
#' Geologic time scale 2020. Elsevier.
#' @source Compiled by Lewis A. Jones. See item descriptions for details.
"GTS2020"

What does it mean to document your data?

Documenting your data is to provide a thorough description of the data and any information relevant to understanding it. Good documentation is key to reproducible science, and will also help us to ensure that we acknowledge all data collators who have provided data for the palaeoverse package. When providing us with datasets, please give the following information:

Author(s): Who collected the data, and prepared its current format? Please provide citations if relevant. Have the authors given permission for the dataset to be included in the palaeoverse package?

Description: Brief description of the dataset.

Provenance: When and how was the data collected? When was the dataset finalised in its current form?

Size: Please state the full, uncompressed size of the file.

Variables: Describe each of the columns in your dataset, providing as much information as you can on the full name of the variable, data type (e.g. continuous, discrete, categoric, etc.), units, and how it was collected.

Conventions

Functions are saved as '.R' files in the 'R' folder. The name of the file needs to correspond to the function, e.g. the file time_bins.R contains the function time_bins(). Function names and arguments should be informative and aim to keep in line with available functions in palaeoverse. For example, all functions that bin data, whether it be by time or space, start with bin_, whereas taxonomic-related functions start with tax_ (e.g. tax_unique, tax_check). Where possible, argument names should also consist with functions in the package. For example, if a function requires an occurrence dataframe as input, the argument name should be occdf. It is difficult to give a complete static summary of all the conventions as palaeoverse will undoubtedly evolve over time. We also wish to remain flexible for contributors, provided that it does not compromise the user-friendliness of the package. We welcome contributors to check through the source code of palaeoverse for function examples.

Documentation

For documentation, we use roxygen2. The title, a brief description, and every argument (including the input class and default input) and the output of the function need to be documented in roxygen2 style, for example:

#' An exemplary function
#' This function is used to demonstrate the documentation of functions.
#' @param example \code{character}. Arguments are the function inputs.
#' @param another_example \code{logical}. All arguments need to be documented.
#' @return A \code{list} is returned as output in this example function.
#' @details Describe more details if necessary, and list sources if applicable.
#' @section Developer:
#' Your name
#' @section Reviewer:
#' Name(s)
#' @examples
#' #Show off the example function
#' example_function(example = “documentation”, another_example = TRUE)
#' @export

Add the '@export' namespace tag to make the function available.

To get started with roxygen2, set your working directory to the package directory, or to the directory where you store your function as a '.R' file. The R command devtools::document() creates a ‘man’ folder in the directory, which contains a '.Rd' file corresponding to your documented function. Opening that file in RStudio, you can create a preview to see what the documentation looks like. After you have implemented changes, rebuild your documentation file with Ctrl+Shift+B or devtools::document().

Efficiency

When possible, you should make coding decisions which will ensure that your code is maximally efficient - this could make a big difference to users who want to apply your function to a large dataset. A few general examples include:

• Using functions from the 'apply' family can be faster than for-loops. However, a for-loop is almost always more reader-friendly, so try to balance the two!
• Storing objects as lists, or lists of lists, rather than data frames inside functions
• Vectorise, when possible. This way a function can operate on all elements of a vector without needing to loop through each element.
• Avoiding using rbind() and cbind() to compile objects row-wise or column-wise within for-loops; specifying the row or column number using the iteration number is usually a faster alternative.

However, please don’t let this deter you - we welcome submissions from R users of all experience levels, and our team of in-house code evaluators can help you with any concerns about efficiency.

Error messages

To ensure that the functions are used appropriately, error messages should be generated when the function is receiving input it is not designed for. Error messages consist of a brief description of what went wrong. Sometimes it makes sense to specify where it went wrong, and what kind of input was expected. Optionally, error messages can include hints to guide the user towards correct input.

Examples of error messages include

• input of the wrong format, e.g. “Error: 'x' must be a numeric vector.”
• input of the wrong dimension, e.g. “Error: 'x' must be a data.frame with two columns.”
• input without mandatory names, e.g. “Error: 'x' does not have a column 'stage'. 'x' must be a data.frame with the columns 'stage' and 'age'.”

To implement error messages in R, the stop() function can be used:

# Generate error message
if (!is.numeric(x)) {
  stop("Error: 'x' must be a numeric vector.")
}

Warning messages

In general, we try to minimise the use of warning messages in palaeoverse as these can be easily ignored by the user, or completely skipped in pipeline analyses (see more?). However, as with most things in life, there is a time and a place. So, while the use of warning() is generally discouraged if throwing an error will suffice, we do allow the use of warning messages in palaeoverse, where appropriate. Warning messages can be useful for providing additional information to the user about function output. For example, in the palaeorotate function we provide a warning to users if one or more points could not be reconstructed due to the georeferenced plate not existing at the desired time of reconstruction.

To implement warning messages in R, the warning() function can be used:

# Generate warning message
if (!is.numeric(x)) {
  warning("Warning: 'x' must be a numeric vector.")
}

Tests

Testing is perhaps one of the most important parts of developing a function. If you have not already, we recommend reading through Chapter 12–Testing of ‘R packages’ before continuing here as palaeoverse follows this guidance.

Before a function can be added to palaeoverse, it needs to go through formal testing. This is required as hopefully your function will be very popular, and we need to ensure that it behaves as expected to avoid any issues. To do so, we make use of the R package testthat.

The initial setup for function testing with testthat is already established in palaeoverse, under the directory 'tests/testthat/'. The organisation of test files must match that of 'R/' files in palaeoverse. For example, the function time_bins() is saved as time_bins.R in the R/ directory, and has an associated test file of 'test-time_bins.R' in the 'tests/testthat' directory. This ensures that associated function testing is clear.

Tip: the usethis package provides a helpful pair of functions for creating/alternating between these files:

• usethis::use_r()
• usethis::use_test()

Make sure to create enough tests within your .R file to cover all of the possible variants of a function. This includes creating tests that cover most or all optional arguments and the majority of options for those arguments (and the required arguments). Remember, even if you personally would not use a function for a particular reason, you must attempt to cover the majority of edge cases that may arise that are allowed by the function.

Related tests should be bundled within test_that() calls combined with strings of text to identify the broad reason for each bundle of tests (e.g., testing a function works with a particular type of data). Finally, if tests rely on data or packages outside of the palaeoverse community must have, they should be skipped if those data or packages are not available.

Ultimately, we aim to have >90% code coverage (95% preferred), which means 90% of the lines of code in our codebase should be tested by at least one test. Pushing code to GitHub will trigger a code coverage check, which will alert you as to whether you need to write more tests.

# Test expected outcome is equal to actual outcome
test_that("time_bins() works", {
  expect_equal(nrow(time_bins(interval = c("Maastrichtian"))), 1)
})

Git and GitHub

We use git via Github (under the palaeoverse GitHub umbrella) to manage our R code and data. If you are not familiar with these tools, there are some excellent free resources available online:

• Setting up git within RStudio (short)
• Collaborating in R with git and GitHub (50 min. youtube video)
• Git and GitHub and R packages (medium length)
• A comprehensive guide to git and R (very long)

How to contribute

Code review

All pull requests must be reviewed by two core developers of palaeoverse (see collaborators) before merging. The review process will ensure that contributions 1) meet the standards and expectations as described above, 2) successfully perform the functions that they claim to perform, and 3) don’t break any other parts of the codebase.

Submitting a pull request to the palaeoverse package will automatically initiate an R CMD check, lintr check, and test coverage check via GitHub Actions. While these checks will conduct some automatic review to ensure the package has not been broken by the new code and that the code matches the style guide (see above), a manual review is still required before the pull request can be merged.

Reviewers may have questions while reviewing your pull request. You are expected to respond to any of these questions via GitHub. If fixes and/or changes are required, you are expected to make these changes. If the required changes are minor enough, reviewers may make them for you, but this should not be expected. If you have any questions or lack the background to make the required changes, you should work with the reviewer to determine a plan of attack.