diff --git a/.github/workflows/R-CMD-check.yaml b/.github/workflows/R-CMD-check.yaml index bd74f87c..76b77e5c 100644 --- a/.github/workflows/R-CMD-check.yaml +++ b/.github/workflows/R-CMD-check.yaml @@ -2,7 +2,7 @@ # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help on: push: - branches: [main, master, terra_41] + branches: [main, master, cran_changes] pull_request: branches: [main, master] diff --git a/DESCRIPTION b/DESCRIPTION index c9ecbfa7..2062b6c4 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: pastclim Type: Package Title: Manipulate Time Series of Palaeoclimate Reconstructions -Version: 1.2.0 +Version: 1.2.1 Authors@R: c( person("Michela", "Leonardi", role = "aut"), person(c("Emily","Y."), "Hallet", role = "ctb"), @@ -11,8 +11,9 @@ Authors@R: c( email = "am315@cam.ac.uk") ) Maintainer: Andrea Manica -Description: This R package is designed to provide an easy way to extract and manipulate palaeoclimate - reconstructions for ecological and anthropological analyses. +Description: Methods to easily extract and manipulate palaeoclimate + reconstructions for ecological and anthropological analyses, as described + in Leonardi et al. (2022) . License: CC BY 4.0 Language: en-GB URL: https://github.com/EvolEcolGroup/pastclim, diff --git a/NAMESPACE b/NAMESPACE index 0ad82c64..35ffae82 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -23,6 +23,7 @@ export(region_slice) export(sample_region_series) export(sample_region_slice) export(set_data_path) +export(set_data_path_for_CRAN) export(slice_region_series) export(time_bp) export(time_series_for_locations) diff --git a/R/check_available_datasets.R b/R/check_available_datasets.R index 732806a6..5ca18f13 100644 --- a/R/check_available_datasets.R +++ b/R/check_available_datasets.R @@ -4,7 +4,7 @@ #' #' @param dataset string defining dataset #' @param include_custom boolean whether a 'custom' dataset is allowed -#' +#' @returns TRUE if the dataset is available #' @keywords internal diff --git a/R/check_dataset_path.R b/R/check_dataset_path.R index 2af74127..06ef9a4c 100644 --- a/R/check_dataset_path.R +++ b/R/check_dataset_path.R @@ -1,13 +1,13 @@ -#' Check dataset and path_to_nc params. +#' Check dataset and path_to_nc params #' -#' Check that the dataset and path_to_nc parameters are valid +#' Check that the dataset and path_to_nc parameters are valid. #' #' @param dataset string defining the dataset to use. If set to "custom", -#' then a single nc file is used from "path_to_nc" +#' then a single nc file is used from "path_to_nc". #' @param path_to_nc the path to the custom nc file containing the palaeoclimate #' reconstructions. All the variables of interest need to be included in #' this file. -#' +#' @returns TRUE if both dataset and path are valid. #' @export diff --git a/R/check_var_downloaded.R b/R/check_var_downloaded.R index 8d8f17ff..a9e24641 100644 --- a/R/check_var_downloaded.R +++ b/R/check_var_downloaded.R @@ -3,6 +3,7 @@ #' #' @param variable a vector of names of the variables of interest #' @param dataset dataset of interest +#' @returns TRUE if the variable has been downloaded. #' #' @keywords internal diff --git a/R/check_var_in_nc.R b/R/check_var_in_nc.R index a174e647..908482fb 100644 --- a/R/check_var_in_nc.R +++ b/R/check_var_in_nc.R @@ -5,6 +5,7 @@ #' @param bio_variables vector of names of variables to be extracted #' @param path_to_nc the path to the custom nc file containing the palaeoclimate #' reconstructions. +#' @returns TRUE if the variable exists #' #' @keywords internal @@ -30,4 +31,5 @@ check_var_in_nc <- function(bio_variables, path_to_nc) { ") not present in the file" ) } + return(TRUE) } diff --git a/R/df_from_region_series.R b/R/df_from_region_series.R index 1742c7ca..d084aee0 100644 --- a/R/df_from_region_series.R +++ b/R/df_from_region_series.R @@ -8,6 +8,8 @@ #' @param x climate time series generated with \code{region_series} #' @param xy a boolean whether x and y coordinates should be added #' to the dataframe (default to TRUE) +#' @returns a data.frame where each cell each raster layer (i.e. timestep) is a +#' row, and the available variables are columns. #' #' @export diff --git a/R/df_from_region_slice.R b/R/df_from_region_slice.R index 1d69e656..79c8bef6 100644 --- a/R/df_from_region_slice.R +++ b/R/df_from_region_slice.R @@ -9,6 +9,8 @@ #' generated with \code{region_slice} #' @param xy a boolean whether x and y coordinates should be added #' to the dataframe (default to TRUE) +#' @returns a data.frame where each cell the raster is a +#' row, and the available variables are columns. #' #' @export diff --git a/R/download_dataset.R b/R/download_dataset.R index 3baf3614..f01b8216 100644 --- a/R/download_dataset.R +++ b/R/download_dataset.R @@ -1,4 +1,4 @@ -#' Download palaeoclimatereconstructions. +#' Download palaeoclimate reconstructions. #' #' This function downloads palaeoclimate reconstructions. Files will be stored #' in the data path of `pastclim`, which can be inspected with @@ -9,6 +9,7 @@ #' will not work on custom datasets. #' @param bio_variables one or more variable names to be downloaded. If left #' to NULL, all variables available for this dataset will be downloaded +#' @returns TRUE if the dataset(s) was downloaded correctly. #' #' @export @@ -60,4 +61,5 @@ download_dataset <- function(dataset, bio_variables = NULL) { ) } } + return(TRUE) } diff --git a/R/get_available_datasets.R b/R/get_available_datasets.R index be688bec..7daf7660 100644 --- a/R/get_available_datasets.R +++ b/R/get_available_datasets.R @@ -3,6 +3,7 @@ #' List the datasets available in pastclim. Most functions can also be #' used on custom datasets by setting `dataset="custom"` #' +#' @returns a character vector of the available datasets #' @export get_available_datasets <- function() { diff --git a/R/get_biome_classes.R b/R/get_biome_classes.R index acb53128..8f190bc6 100644 --- a/R/get_biome_classes.R +++ b/R/get_biome_classes.R @@ -6,6 +6,7 @@ #' @param dataset string defining dataset to be downloaded (a list of possible #' values can be obtained with \code{get_available_datasets}). This function #' will not work on custom datasets. +#' @returns a data.frame with columns id and category. #' #' @export diff --git a/R/get_data_path.R b/R/get_data_path.R new file mode 100644 index 00000000..b4ad2cd6 --- /dev/null +++ b/R/get_data_path.R @@ -0,0 +1,43 @@ +#' Get the data path where climate reconstructions are stored +#' +#' This function returns the path where climate reconstructions are stored. +#' +#' The path is stored in an option for `pastclim` named `data_path`. If +#' a configuration file was saved when using \code{set_data_path}, the path +#' is retrieved from a file named "pastclim_data.txt", which +#' is found in the directory returned by +#' `tools::R_user_dir("pastclim","config")` (i.e. +#' the default configuration directory for the package as set in R >= 4.0). +#' +#' @param silent boolean on whether a message is returned when data_path is +#' not set (i.e. equal to NULL) +#' @returns the data path +#' @export + +get_data_path <- function(silent=FALSE) { + # if the package already initiliased + if (!is.null(getOption("pastclim.data_path"))) { + return(getOption("pastclim.data_path")) + } else { # get the info from the config file + # if the path was not set yet, return a message + if (!file.exists(file.path( + tools::R_user_dir("pastclim", "config"), + "pastclim_data.txt" + ))) { + if (!silent) { + message("A default data_path was not set for pastclim;\n", + "use `set_data_path()` to set it.") + } + return(NULL) + } + path_to_nc <- utils::read.table(file.path( + tools::R_user_dir("pastclim", "config"), + "pastclim_data.txt" + ))[1, 1] + if (!dir.exists(path_to_nc)){ + stop("The path ",path_to_nc," from the config file does not exist!\n", + "You can reset the path with `set_data_path`.") + } + return(path_to_nc) + } +} diff --git a/R/get_dataset_info.R b/R/get_dataset_info.R index 0560ece6..22df63f4 100644 --- a/R/get_dataset_info.R +++ b/R/get_dataset_info.R @@ -5,6 +5,7 @@ #' \code{get_available_datasets} #' #' @param dataset A dataset in pastclim +#' @returns text describing the dataset #' @keywords internal get_dataset_info <- function(dataset) { @@ -24,6 +25,7 @@ get_dataset_info <- function(dataset) { #' @param which lines should be printed #' @param before string to be printed before the output #' @param after string to be printed after the output +#' @returns text of the help file #' #' @keywords internal diff --git a/R/get_downloaded_datasets.R b/R/get_downloaded_datasets.R index 7bd91aa2..aa788bda 100644 --- a/R/get_downloaded_datasets.R +++ b/R/get_downloaded_datasets.R @@ -2,7 +2,8 @@ #' #' List the downloaded variable for each dataset. #' -#' @param data_path leave it to NULL to use the default datapath +#' @param data_path leave it to NULL to use the default data_path +#' @returns a list of variable names per dataset. #' #' @export @@ -21,4 +22,4 @@ get_downloaded_datasets <- function(data_path = NULL) { ] } downloaded_vars -} \ No newline at end of file +} diff --git a/R/get_ice_mask.R b/R/get_ice_mask.R index 2c7cba3c..9a82b07a 100644 --- a/R/get_ice_mask.R +++ b/R/get_ice_mask.R @@ -1,6 +1,6 @@ #' Get the ice mask for a dataset. #' -#' Get the ice mask for a dataset at a given timepoint. +#' Get the ice mask for a dataset at a given time point. #' #' @param time_bp time slice in years before present (negative) #' @param dataset string defining dataset to be downloaded (a list of possible diff --git a/R/get_land_mask.R b/R/get_land_mask.R index e29b0e0f..440856b2 100644 --- a/R/get_land_mask.R +++ b/R/get_land_mask.R @@ -1,6 +1,6 @@ #' Get the land mask for a dataset. #' -#' Get the land mask for a dataset at a given timepoint. +#' Get the land mask for a dataset at a given time point. #' #' @param time_bp time slice in years before present (negative) #' @param dataset string defining dataset to be downloaded (a list of possible diff --git a/R/get_vars_for_dataset.R b/R/get_vars_for_dataset.R index 1f76a3ff..c2a84a8e 100644 --- a/R/get_vars_for_dataset.R +++ b/R/get_vars_for_dataset.R @@ -53,7 +53,7 @@ get_vars_for_dataset <- function(dataset, path_to_nc = NULL, details=FALSE) { #' #' @param variable a vector of names of the variables of interest #' @param dataset dataset of interest -#' +#' @returns TRUE if var is available #' @keywords internal check_available_variable <- function(variable, dataset) { @@ -76,6 +76,7 @@ check_available_variable <- function(variable, dataset) { #' #' @param variable string defining the variable name #' @param dataset string defining dataset to be downloaded +#' @returns the name of the variable #' get_varname <- function(variable, dataset) { diff --git a/R/is_region_series.R b/R/is_region_series.R index ef6c7a51..b8dca74a 100644 --- a/R/is_region_series.R +++ b/R/is_region_series.R @@ -1,11 +1,11 @@ #' Check the object is a valid region series #' #' A region series is a \code{terra::SpatRasterDataset} for which each -#' subdataset is a variable, and all variables have the same number of +#' sub-dataset is a variable, and all variables have the same number of #' time steps. #' #' The standard test only checks that each SpatRaster has the same number of -#' layers. The more thorough test (obtainedwith strict=TRUE) actually checks +#' layers. The more thorough test (obtained with strict=TRUE) actually checks #' that all time steps are identical by comparing the result of #' \code{terra::time} applied to each variable #' @@ -13,6 +13,7 @@ #' regional reconstructions obtained from \code{region_series}. #' @param strict a boolean defining whether to preform a thorough test (see #' description above for details). +#' @returns TRUE if the object is a region series #' #' @export diff --git a/R/location_series.R b/R/location_series.R index 7fa791f9..cb43879e 100644 --- a/R/location_series.R +++ b/R/location_series.R @@ -22,7 +22,7 @@ #' @param path_to_nc the path to the custom nc file containing the palaeoclimate #' reconstructions. All the variables of interest need to be included in #' this file. -#' +#' @returns a data.frame with the climatic variables of interest #' @export location_series <- @@ -111,6 +111,7 @@ location_series <- #' Deprecated version of \code{location_series} #' #' @param ... arguments to be passed to \code{series} +#' @returns a data.frame with the climatic variables of interest #' #' @export diff --git a/R/location_slice.R b/R/location_slice.R index 1f73dd04..0fdf1346 100644 --- a/R/location_slice.R +++ b/R/location_slice.R @@ -22,7 +22,7 @@ #' information (i.e. they are under water or ice). Interpolation is only #' performed from the first ring of nearest neighbours; if climate is not #' available, NA will be returned for that location. Defaults to TRUE. -#' +#' @returns a data.frame with the climatic variables of interest. #' @export location_slice <- @@ -152,6 +152,7 @@ location_slice <- #' Deprecated version of \code{location_slice} #' #' @param ... arguments to be passed to \code{location_slice} +#' @returns a data.frame with the climatic variables of interest #' #' @export diff --git a/R/region_series.R b/R/region_series.R index 370db7d5..1d0a7680 100644 --- a/R/region_series.R +++ b/R/region_series.R @@ -25,6 +25,9 @@ #' @param crop a polygon used to crop the reconstructions (e.g. the outline #' of a continental mass). A \code{sf:sfg} or a \code{terra::SpatVector} object #' is used to define the polygon. +#' @returns a +#' SpatRasterDataset \code{terra::sds} object, with +#' each variable as a sub-dataset. #' #' @import terra #' @export diff --git a/R/region_slice.R b/R/region_slice.R index d8ae8e91..a2865aea 100644 --- a/R/region_slice.R +++ b/R/region_slice.R @@ -22,6 +22,9 @@ #' @param crop a polygon used to crop the reconstructions (e.g. the outline #' of a continental mass). A \code{sf:sfg} or a \code{terra::SpatVector} object #' is used to define the polygon. +#' @returns a +#' SpatRaster \code{terra::SpatRaster} object, with +#' each variable as a layer. #' #' @import terra #' @export @@ -51,6 +54,9 @@ region_slice <- #' Deprecated version of \code{region_slice} #' #' @param ... arguments to be passed to \code{region_slice} +#' @returns a +#' SpatRaster \code{terra::SpatRaster} object, with +#' each variable as a layer. #' #' @export diff --git a/R/sample_region_series.R b/R/sample_region_series.R index 8b359f0d..51e879a5 100644 --- a/R/sample_region_series.R +++ b/R/sample_region_series.R @@ -20,6 +20,8 @@ #' defaults to "random" #' @param replace boolean determining whether we sample with replacement #' @param na.rm boolean determining whether NAs are removed +#' @returns a data.frame with the sampled cells and their respective values for +#' the climate variables. #' #' @export @@ -50,6 +52,8 @@ sample_region_series<-function(x, size, method="random", replace=FALSE, na.rm=TR #' defaults to "random" #' @param replace boolean determining whether we sample with replacement #' @param na.rm boolean determining whether NAs are removed +#' @returns a data.frame with the sampled cells and their respective values for +#' the climate variables. #' #' @keywords internal @@ -101,6 +105,8 @@ sample_rs_fixed<-function(x, size, method="random", replace=FALSE, na.rm=TRUE) #' defaults to "random" #' @param replace boolean determining whether we sample with replacement #' @param na.rm boolean determining whether NAs are removed +#' @returns a data.frame with the sampled cells and their respective values for +#' the climate variables. #' #' @keywords internal diff --git a/R/sample_region_slice.R b/R/sample_region_slice.R index 2fb198cd..6b0a36ae 100644 --- a/R/sample_region_slice.R +++ b/R/sample_region_slice.R @@ -1,6 +1,6 @@ #' Sample points from a region time slice #' -#' This function samples points from a region time slice (i.e. a timepoint). +#' This function samples points from a region time slice (i.e. a time point). #' #' This function wraps \code{terra::spatSample} to appropriate sample the #' \code{terra::SpatRaster} returned @@ -14,7 +14,9 @@ #' defaults to "random" #' @param replace boolean determining whether we sample with replacement #' @param na.rm boolean determining whether NAs are removed -#' +#' @returns a data.frame with the sampled cells and their respective values for +#' the climate variables. + #' @export sample_region_slice<-function(x, size, method="random", replace=FALSE, na.rm=TRUE) diff --git a/R/set_data_path.R b/R/set_data_path.R index 72b67b83..0a5309f9 100644 --- a/R/set_data_path.R +++ b/R/set_data_path.R @@ -9,82 +9,85 @@ #' @param path_to_nc the path to the file that contains the downloaded #' reconstructions. If left unset, the default location returned by #' `tools::R_user_dir("pastclim","data")` will be used +#' @param ask boolean on whether the user should be asked to confirm their +#' choices +#' @param write_config boolean on whether the path should be saved in a config +#' file +#' @param copy_example boolean on whether the example dataset should be saved +#' in the data_path +#' @return TRUE if the path was set correctly #' #' @export -set_data_path <- function(path_to_nc = NULL) { - # if we don't have a config directory, create one - if (!dir.exists(tools::R_user_dir("pastclim", "config"))) { - dir.create(tools::R_user_dir("pastclim", "config"), recursive = TRUE) - } - # if use the default location for data +set_data_path <- function(path_to_nc = NULL, ask = TRUE, write_config = TRUE, + copy_example = TRUE) { if (is.null(path_to_nc)) { - path_to_nc <- tools::R_user_dir("pastclim", "data") - # create it if it does not exist yet - if (!dir.exists(path_to_nc)) { - dir.create(path_to_nc, recursive = TRUE) + data_dir <- tools::R_user_dir("pastclim", "data") + } else { + data_dir <- path_to_nc + } + if (ask){ # if we ask the user + message_to_user<-paste0("The data_path will be set to ", + data_dir,".\n") + if (copy_example){ + message_to_user<-paste0(message_to_user, + "A copy of the Example dataset will be copied there.\n") } - } else { # if custom path, stop if it does not exist - if (!dir.exists(path_to_nc)){ - stop(path_to_nc, " does not exist!") + + if (write_config){ + message_to_user<-paste0(message_to_user, + "This path will be saved by pastclim for future use.\n") + } else { + message_to_user<-paste0(message_to_user, + "You have chosen not to save the path for future use.\n", + "You will have to reset the path when R is restarted.\n") } + message_to_user<-paste0(message_to_user,"Proceed?") + user_choice <- utils::menu(c("Yes","No"), title = message_to_user) + } else { # else, if we don't ask, answer yes + user_choice <- 1 } - utils::write.table(path_to_nc, - row.names = FALSE, - col.names = FALSE, - file = file.path( - tools::R_user_dir("pastclim", "config"), - "pastclim_data.txt" - ) - ) - - # update option - options(pastclim.data_path = path_to_nc) - # move the example data into the new data path - copy_example_data() -} - - -#' Get the data path where climate reconstructions are stored -#' -#' This function returns the path where climate reconstructions will be stored. -#' When `pastclim` is installed, the data path defaults to the directory -#' returned by `tools::R_user_dir("pastclim","data")` (i.e. the data directory -#' for the package in R>=4.0). The data path can be changed with -#' \code{set_data_path}. Once changed, `pastclim` will remember the new data -#' path in the future. -#' -#' The data path is stored in a file named "pastclim_data.txt", which -#' is found in the directory returned by -#' `tools::R_user_dir("pastclim","config")` (i.e. -#' the default configuration directory for the package as set in R >= 4.0). -#' -#' @export - -get_data_path <- function() { - # if the package already initiliased - if (!is.null(getOption("pastclim.data_path"))) { - return(getOption("pastclim.data_path")) - } else { # get the info from the config file - # if data path was never set before, we set it to its default location - if (!file.exists(file.path( - tools::R_user_dir("pastclim", "config"), - "pastclim_data.txt" - ))) { - set_data_path() + # if the user said yes + if (user_choice==1){ + # if the data directory does not exist, attempt to make it + if (!dir.exists(data_dir)) { + dir.create(data_dir, recursive = TRUE) + # do we need to check succeful dir creation, or does it raise an error? } - path_to_nc <- utils::read.table(file.path( - tools::R_user_dir("pastclim", "config"), - "pastclim_data.txt" - ))[1, 1] - return(path_to_nc) + # if requested, write the path in a config file for future use + if (write_config){ + # if we don't have a config directory, create one + if (!dir.exists(tools::R_user_dir("pastclim", "config"))) { + dir.create(tools::R_user_dir("pastclim", "config"), recursive = TRUE) + } + utils::write.table(data_dir, + row.names = FALSE, + col.names = FALSE, + file = file.path( + tools::R_user_dir("pastclim", "config"), + "pastclim_data.txt" + )) + } + } else { # if the user said no + message("Aborted: the data path was not set.") + return(FALSE) + } + # update option + options(pastclim.data_path = data_dir) + # if requested, copy the example dataset in it + if (copy_example){ + copy_example_data() } + return (TRUE) } + #' Internal function to copy the example dataset when a new data path is set #' #' Copy example dataset +#' +#' @returns TRUE if the data were copied successfully #' #' @keywords internal @@ -92,9 +95,32 @@ copy_example_data <- function() { if (!file.exists(file.path(get_data_path(), "example_climate_v2.nc"))) { file.copy( from = system.file("/extdata/example_climate_v2.nc", - package = "pastclim" + package = "pastclim" ), to = file.path(get_data_path(), "example_climate_v2.nc") ) } + return(TRUE) +} + +#' Set the data path for examples on CRAN +#' +#' Users should NOT need this function. It is used to set up a +#' data path in the temporary directory for examples and tests +#' to run on CRAN. +#' +#' @returns None +#' @export + + +set_data_path_for_CRAN <- function() { + # set up data path for this test + data_path <- file.path(tempdir(),"pastclim_data") + # clear it if it exists + unlink(data_path, recursive = TRUE) + # set data path + set_data_path(path_to_nc = data_path, + ask = FALSE, + write_config = FALSE, + copy_example = TRUE) } diff --git a/R/slice_region_series.R b/R/slice_region_series.R index 5c77af58..b77d78ba 100644 --- a/R/slice_region_series.R +++ b/R/slice_region_series.R @@ -10,6 +10,7 @@ #' can use \code{time_bp(x[[1]])} (note that you have to use #' the `time` function on the first element of the 'sds' object, i.e. on one #' of the 'SpatRaster' objects) +#' @returns a \code{SpatRaster} of the relevant slice. #' #' @export diff --git a/R/time_bp.R b/R/time_bp.R index 3b2df44b..79e0f755 100644 --- a/R/time_bp.R +++ b/R/time_bp.R @@ -4,7 +4,7 @@ #' present #' #' @param x a \code{terra::SpatRaster} -#' +#' @returns a date in years BP (where negative numbers indicate a date in the past) #' @export diff --git a/R/time_bp_series.R b/R/time_bp_series.R index 70f92038..2a631b22 100644 --- a/R/time_bp_series.R +++ b/R/time_bp_series.R @@ -4,7 +4,8 @@ #' #' @param time_bp vector of times BP #' @param time_steps time steps for which reconstructions are available -#' +#' @returns the indeces for the relevant time steps +#' #' @keywords internal time_bp_series<-function(time_bp, time_steps){ diff --git a/R/time_bp_to_index.R b/R/time_bp_to_index.R index 6769516c..b7a82cb7 100644 --- a/R/time_bp_to_index.R +++ b/R/time_bp_to_index.R @@ -1,10 +1,10 @@ -#' Convert a time BP to indexes in a netcdf file. +#' Find the closest index to a given time in years BP #' #' Internal function #' #' @param time_bp vector of times BP #' @param time_steps time steps for which reconstructions are available -#' +#' @returns the indeces for the relevant time steps #' @keywords internal time_bp_to_index <- function(time_bp, time_steps) { diff --git a/R/var_labels.R b/R/var_labels.R index 4bf2cb6a..b4692816 100644 --- a/R/var_labels.R +++ b/R/var_labels.R @@ -17,6 +17,10 @@ #' @examples #' var_labels("bio01", dataset = "Example") #' +#' # set the data_path for this example to run on CRAN +#' # users don't need to run this line +#' set_data_path_for_CRAN() +#' #' # for a SpatRaster #' climate_20k <- region_slice( #' time_bp = -20000, diff --git a/R/zzz.R b/R/zzz.R index b3a219bc..c9bb42f9 100644 --- a/R/zzz.R +++ b/R/zzz.R @@ -2,14 +2,11 @@ # store the data path as an option for easy retrieval op <- options() op.pastclim <- list( - pastclim.data_path = get_data_path() + pastclim.data_path = get_data_path(silent=TRUE) ) toset <- !(names(op.pastclim) %in% names(op)) if (any(toset)) options(op.pastclim[toset]) - # copy example dataset into the data path (and update it if it has changed) - copy_example_data() - # check that gdal was compiled with netcdf support d <- gdal(drivers=TRUE) if (!"netCDF" %in% terra::gdal(drivers=TRUE)$name){ diff --git a/README.md b/README.md index 915e842d..7983e020 100644 --- a/README.md +++ b/README.md @@ -74,7 +74,7 @@ of this issue can be found on [stack**overflow**](https://stackoverflow.com/ques ### terra without NETCDF driver for macOS -A number of versions of `terra` available as binaries for macOS on CRAN (including the latest one) have +A number of versions of `terra` available as binaries for macOS X86-64 on CRAN (including the latest one) have been compiled without a NETCDF driver. This prevents `pastclim`, which relies on `terra`, from correctly reading files. When loaded, `pastclim` checks if the driver is available; in case of a missing driver, you will get the error: diff --git a/cran-comments.md b/cran-comments.md index 0b96bbca..8a75c5d8 100644 --- a/cran-comments.md +++ b/cran-comments.md @@ -1,8 +1,52 @@ -This is a new package not present on CRAN yet. +This is a resubmission + +# Feedback on previous submission (with details of fixes) + +Please do not start the description with "This package", package name, +title or similar. + +> Description changed as requested. + +If there are references describing the methods in your package, please +add these in the description field of your DESCRIPTION file in the form +authors (year) +authors (year) +authors (year, ISBN:...) +or if those are not available: +with no space after 'doi:', 'arXiv:', 'https:' and angle brackets for +auto-linking. (If you want to add a title as well please put it in +quotes: "Title") + +> Reference added as suggested. + +Please add \value to .Rd files regarding exported methods and explain +the functions results in the documentation. Please write about the +structure of the output (class) and also what the output means. (If a +function does not return a value, please document that too, e.g. +\value{No return value, called for side effects} or similar) +Missing Rd-tags in up to 26 .Rd files, e.g.: + check_dataset_path.Rd: \value + climate_for_locations.Rd: \value + climate_for_time_slice.Rd: \value + df_from_region_series.Rd: \value + df_from_region_slice.Rd: \value + download_dataset.Rd: \value + ... + +> My apologies, I relied on devtools::check() to test the documentation, +I see now that it fails to check returns. All functions now should have a +return value in their documentation. + +Please ensure that your functions do not write by default or in your +examples/vignettes/tests in the user's home filespace (including the +package directory and getwd()). This is not allowed by CRAN policies. +Please omit any default path in writing functions. In your +examples/vignettes/tests you can write to tempdir(). -> +R/set_data_path.R and corresponding tests + +> Functions changed to ensure that no files are written to the user's home +filespace (sorry, I had misread the note about R_user_dir on CRAN). -On all testing environment (see below), we only get a note because of the -package being a new submission (expected), and a false positive for mispelling -(palaeoclimate is an existing word and IS spelled correctly). ## Test environments - R-hub windows-x86_64-devel (r-devel) @@ -10,6 +54,11 @@ package being a new submission (expected), and a false positive for mispelling - R-hub fedora-clang-devel (r-devel) - devtools::check_mac_release +On all testing environment (see below), I only get a note because of the +package being a new submission (expected), and a false positive for mispelling +(palaeoclimate is an existing word and IS spelled correctly; the rest are parts +of the author list of the paper describing the package). + ## R CMD check results On all systems: @@ -19,7 +68,10 @@ Maintainer: ‘Andrea Manica ’ New submission Possibly misspelled words in DESCRIPTION: - palaeoclimate (14:90) + al (16:18) + et (16:15) + Leonardi (16:6) + palaeoclimate (14:55) Palaeoclimate (3:34) 0 errors ✔ | 0 warnings ✔ | 1 notes ✖ diff --git a/inst/rawdata_scripts/check_returns_in_documentation.R b/inst/rawdata_scripts/check_returns_in_documentation.R new file mode 100644 index 00000000..18fa8930 --- /dev/null +++ b/inst/rawdata_scripts/check_returns_in_documentation.R @@ -0,0 +1,14 @@ +# with wd set to the root of the package, source this script +# it will return a list of the map pages missing returns +# note that map pages for datasets don't need returns. + +check_returns_in_documentation <-function(){ + # note the additiona \ to run through system 2 + files_with_value <- basename(system2(command = "grep", + args='-Ril "\\\\value" ./man/', + stdout=TRUE) + ) + all_files<-dir ("./man") + return(all_files[!all_files %in% files_with_value]) +} +check_returns_in_documentation() diff --git a/inst/rawdata_scripts/readme.md b/inst/rawdata_scripts/readme.md index 691cd74e..d02f4bad 100644 --- a/inst/rawdata_scripts/readme.md +++ b/inst/rawdata_scripts/readme.md @@ -1,4 +1,8 @@ -This files provides an overivew of the scripts used to generate the data used in pastclim. All R scripts assume that you are in the root directory of the package: +This files provides an overivew of the scripts used to generate the data used in pastclim. All R scripts assume that you are in the root directory of the package. + +NOTE: these scripts were used with terra <1.6-41, which changed the way time +is coded. Make sure that you check the scripts before running, as they might not +function as expected. ## scripts to package the climate data diff --git a/man/check_available_dataset.Rd b/man/check_available_dataset.Rd index b48004ad..305d52ec 100644 --- a/man/check_available_dataset.Rd +++ b/man/check_available_dataset.Rd @@ -11,6 +11,9 @@ check_available_dataset(dataset, include_custom = FALSE) \item{include_custom}{boolean whether a 'custom' dataset is allowed} } +\value{ +TRUE if the dataset is available +} \description{ Internal getter function } diff --git a/man/check_available_variable.Rd b/man/check_available_variable.Rd index be956c9c..7ada379e 100644 --- a/man/check_available_variable.Rd +++ b/man/check_available_variable.Rd @@ -11,6 +11,9 @@ check_available_variable(variable, dataset) \item{dataset}{dataset of interest} } +\value{ +TRUE if var is available +} \description{ Internal getter function } diff --git a/man/check_dataset_path.Rd b/man/check_dataset_path.Rd index beda2f10..7f50bc5b 100644 --- a/man/check_dataset_path.Rd +++ b/man/check_dataset_path.Rd @@ -2,18 +2,21 @@ % Please edit documentation in R/check_dataset_path.R \name{check_dataset_path} \alias{check_dataset_path} -\title{Check dataset and path_to_nc params.} +\title{Check dataset and path_to_nc params} \usage{ check_dataset_path(dataset, path_to_nc) } \arguments{ \item{dataset}{string defining the dataset to use. If set to "custom", -then a single nc file is used from "path_to_nc"} +then a single nc file is used from "path_to_nc".} \item{path_to_nc}{the path to the custom nc file containing the palaeoclimate reconstructions. All the variables of interest need to be included in this file.} } +\value{ +TRUE if both dataset and path are valid. +} \description{ -Check that the dataset and path_to_nc parameters are valid +Check that the dataset and path_to_nc parameters are valid. } diff --git a/man/check_var_downloaded.Rd b/man/check_var_downloaded.Rd index 7147ccc2..a7e9e05d 100644 --- a/man/check_var_downloaded.Rd +++ b/man/check_var_downloaded.Rd @@ -12,6 +12,9 @@ check_var_downloaded(variable, dataset) \item{dataset}{dataset of interest} } +\value{ +TRUE if the variable has been downloaded. +} \description{ Internal functions to check whether we have downloaded a given variable for a dataset diff --git a/man/check_var_in_nc.Rd b/man/check_var_in_nc.Rd index 28842acd..da509b72 100644 --- a/man/check_var_in_nc.Rd +++ b/man/check_var_in_nc.Rd @@ -12,6 +12,9 @@ check_var_in_nc(bio_variables, path_to_nc) \item{path_to_nc}{the path to the custom nc file containing the palaeoclimate reconstructions.} } +\value{ +TRUE if the variable exists +} \description{ Internal function to test a custom nc file. } diff --git a/man/climate_for_locations.Rd b/man/climate_for_locations.Rd index 2fe3b355..e3648205 100644 --- a/man/climate_for_locations.Rd +++ b/man/climate_for_locations.Rd @@ -9,6 +9,9 @@ climate_for_locations(...) \arguments{ \item{...}{arguments to be passed to \code{location_slice}} } +\value{ +a data.frame with the climatic variables of interest +} \description{ Deprecated version of \code{location_slice} } diff --git a/man/climate_for_time_slice.Rd b/man/climate_for_time_slice.Rd index 701b8315..0938e0c0 100644 --- a/man/climate_for_time_slice.Rd +++ b/man/climate_for_time_slice.Rd @@ -9,6 +9,11 @@ climate_for_time_slice(...) \arguments{ \item{...}{arguments to be passed to \code{region_slice}} } +\value{ +a +SpatRaster \code{terra::SpatRaster} object, with +each variable as a layer. +} \description{ Deprecated version of \code{region_slice} } diff --git a/man/copy_example_data.Rd b/man/copy_example_data.Rd index 0acecaa1..1b09a1d9 100644 --- a/man/copy_example_data.Rd +++ b/man/copy_example_data.Rd @@ -6,6 +6,9 @@ \usage{ copy_example_data() } +\value{ +TRUE if the data were copied successfully +} \description{ Copy example dataset } diff --git a/man/df_from_region_series.Rd b/man/df_from_region_series.Rd index 320982cc..992a86c1 100644 --- a/man/df_from_region_series.Rd +++ b/man/df_from_region_series.Rd @@ -12,6 +12,10 @@ df_from_region_series(x, xy = TRUE) \item{xy}{a boolean whether x and y coordinates should be added to the dataframe (default to TRUE)} } +\value{ +a data.frame where each cell each raster layer (i.e. timestep) is a +row, and the available variables are columns. +} \description{ Extract the climatic information from a region series and organise them as a data frame. diff --git a/man/df_from_region_slice.Rd b/man/df_from_region_slice.Rd index ff11fc57..2341b706 100644 --- a/man/df_from_region_slice.Rd +++ b/man/df_from_region_slice.Rd @@ -13,6 +13,10 @@ generated with \code{region_slice}} \item{xy}{a boolean whether x and y coordinates should be added to the dataframe (default to TRUE)} } +\value{ +a data.frame where each cell the raster is a +row, and the available variables are columns. +} \description{ Extract the climatic information from a region slice and organise it as a data frame. This is just a wrapper around \code{terra::as.data.frame}. diff --git a/man/download_dataset.Rd b/man/download_dataset.Rd index fcd40348..1c785ca9 100644 --- a/man/download_dataset.Rd +++ b/man/download_dataset.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/download_dataset.R \name{download_dataset} \alias{download_dataset} -\title{Download palaeoclimatereconstructions.} +\title{Download palaeoclimate reconstructions.} \usage{ download_dataset(dataset, bio_variables = NULL) } @@ -14,6 +14,9 @@ will not work on custom datasets.} \item{bio_variables}{one or more variable names to be downloaded. If left to NULL, all variables available for this dataset will be downloaded} } +\value{ +TRUE if the dataset(s) was downloaded correctly. +} \description{ This function downloads palaeoclimate reconstructions. Files will be stored in the data path of `pastclim`, which can be inspected with diff --git a/man/get_available_datasets.Rd b/man/get_available_datasets.Rd index 2c0f0e9b..8a23716c 100644 --- a/man/get_available_datasets.Rd +++ b/man/get_available_datasets.Rd @@ -6,6 +6,9 @@ \usage{ get_available_datasets() } +\value{ +a character vector of the available datasets +} \description{ List the datasets available in pastclim. Most functions can also be used on custom datasets by setting `dataset="custom"` diff --git a/man/get_biome_classes.Rd b/man/get_biome_classes.Rd index b97cb397..342d071e 100644 --- a/man/get_biome_classes.Rd +++ b/man/get_biome_classes.Rd @@ -11,6 +11,9 @@ get_biome_classes(dataset) values can be obtained with \code{get_available_datasets}). This function will not work on custom datasets.} } +\value{ +a data.frame with columns id and category. +} \description{ Get a full list of biomes and how their id as coded in the biome variable for a given dataset. diff --git a/man/get_data_path.Rd b/man/get_data_path.Rd index 7b7fe7f7..b11e480e 100644 --- a/man/get_data_path.Rd +++ b/man/get_data_path.Rd @@ -1,21 +1,25 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/set_data_path.R +% Please edit documentation in R/get_data_path.R \name{get_data_path} \alias{get_data_path} \title{Get the data path where climate reconstructions are stored} \usage{ -get_data_path() +get_data_path(silent = FALSE) +} +\arguments{ +\item{silent}{boolean on whether a message is returned when data_path is +not set (i.e. equal to NULL)} +} +\value{ +the data path } \description{ -This function returns the path where climate reconstructions will be stored. -When `pastclim` is installed, the data path defaults to the directory -returned by `tools::R_user_dir("pastclim","data")` (i.e. the data directory -for the package in R>=4.0). The data path can be changed with -\code{set_data_path}. Once changed, `pastclim` will remember the new data -path in the future. +This function returns the path where climate reconstructions are stored. } \details{ -The data path is stored in a file named "pastclim_data.txt", which +The path is stored in an option for `pastclim` named `data_path`. If +a configuration file was saved when using \code{set_data_path}, the path +is retrieved from a file named "pastclim_data.txt", which is found in the directory returned by `tools::R_user_dir("pastclim","config")` (i.e. the default configuration directory for the package as set in R >= 4.0). diff --git a/man/get_dataset_info.Rd b/man/get_dataset_info.Rd index 66769182..77cefcba 100644 --- a/man/get_dataset_info.Rd +++ b/man/get_dataset_info.Rd @@ -9,6 +9,9 @@ get_dataset_info(dataset) \arguments{ \item{dataset}{A dataset in pastclim} } +\value{ +text describing the dataset +} \description{ This function provides full information about a given dataset. A full list of datasets available in pastclim can be obtained with diff --git a/man/get_downloaded_datasets.Rd b/man/get_downloaded_datasets.Rd index 122537e6..16b07540 100644 --- a/man/get_downloaded_datasets.Rd +++ b/man/get_downloaded_datasets.Rd @@ -7,7 +7,10 @@ get_downloaded_datasets(data_path = NULL) } \arguments{ -\item{data_path}{leave it to NULL to use the default datapath} +\item{data_path}{leave it to NULL to use the default data_path} +} +\value{ +a list of variable names per dataset. } \description{ List the downloaded variable for each dataset. diff --git a/man/get_ice_mask.Rd b/man/get_ice_mask.Rd index 9a1acc29..e8806ebb 100644 --- a/man/get_ice_mask.Rd +++ b/man/get_ice_mask.Rd @@ -14,5 +14,5 @@ values can be obtained with \code{get_available_datasets}). This function will not work on custom datasets.} } \description{ -Get the ice mask for a dataset at a given timepoint. +Get the ice mask for a dataset at a given time point. } diff --git a/man/get_land_mask.Rd b/man/get_land_mask.Rd index c12f2af1..01383f30 100644 --- a/man/get_land_mask.Rd +++ b/man/get_land_mask.Rd @@ -14,5 +14,5 @@ values can be obtained with \code{get_available_datasets}). This function will not work on custom datasets.} } \description{ -Get the land mask for a dataset at a given timepoint. +Get the land mask for a dataset at a given time point. } diff --git a/man/get_varname.Rd b/man/get_varname.Rd index 1b92f8c9..998279dd 100644 --- a/man/get_varname.Rd +++ b/man/get_varname.Rd @@ -11,6 +11,9 @@ get_varname(variable, dataset) \item{dataset}{string defining dataset to be downloaded} } +\value{ +the name of the variable +} \description{ Internal function to get the varname for this variable } diff --git a/man/help_console.Rd b/man/help_console.Rd index bcd2be3f..d3225a7f 100644 --- a/man/help_console.Rd +++ b/man/help_console.Rd @@ -23,6 +23,9 @@ help_console( \item{which}{lines should be printed} } +\value{ +text of the help file +} \description{ This function prints a help file to console. It is based on a function published on R-bloggers: diff --git a/man/is_region_series.Rd b/man/is_region_series.Rd index 0e97f4b1..74a22a45 100644 --- a/man/is_region_series.Rd +++ b/man/is_region_series.Rd @@ -13,14 +13,17 @@ regional reconstructions obtained from \code{region_series}.} \item{strict}{a boolean defining whether to preform a thorough test (see description above for details).} } +\value{ +TRUE if the object is a region series +} \description{ A region series is a \code{terra::SpatRasterDataset} for which each -subdataset is a variable, and all variables have the same number of +sub-dataset is a variable, and all variables have the same number of time steps. } \details{ The standard test only checks that each SpatRaster has the same number of -layers. The more thorough test (obtainedwith strict=TRUE) actually checks +layers. The more thorough test (obtained with strict=TRUE) actually checks that all time steps are identical by comparing the result of \code{terra::time} applied to each variable } diff --git a/man/location_series.Rd b/man/location_series.Rd index 96c9d041..bd7355a0 100644 --- a/man/location_series.Rd +++ b/man/location_series.Rd @@ -28,6 +28,9 @@ then a single nc file is used from "path_to_nc"} reconstructions. All the variables of interest need to be included in this file.} } +\value{ +a data.frame with the climatic variables of interest +} \description{ This function extract a time series of local climate for a set of locations. Note that this function does not apply any interpolation diff --git a/man/location_slice.Rd b/man/location_slice.Rd index 8d7cada9..cb57797e 100644 --- a/man/location_slice.Rd +++ b/man/location_slice.Rd @@ -38,6 +38,9 @@ information (i.e. they are under water or ice). Interpolation is only performed from the first ring of nearest neighbours; if climate is not available, NA will be returned for that location. Defaults to TRUE.} } +\value{ +a data.frame with the climatic variables of interest. +} \description{ This function extract local climate for a set of locations at the appropriate times (selecting the closest time slice available for the diff --git a/man/region_series.Rd b/man/region_series.Rd index 7cb564e7..6f531797 100644 --- a/man/region_series.Rd +++ b/man/region_series.Rd @@ -39,6 +39,11 @@ the full extent of the reconstruction is given.} of a continental mass). A \code{sf:sfg} or a \code{terra::SpatVector} object is used to define the polygon.} } +\value{ +a +SpatRasterDataset \code{terra::sds} object, with +each variable as a sub-dataset. +} \description{ This function extracts a time series of one or more climate variables for a given diff --git a/man/region_slice.Rd b/man/region_slice.Rd index 9c0712d9..65623ed8 100644 --- a/man/region_slice.Rd +++ b/man/region_slice.Rd @@ -37,6 +37,11 @@ the full extent of the reconstruction is given.} of a continental mass). A \code{sf:sfg} or a \code{terra::SpatVector} object is used to define the polygon.} } +\value{ +a +SpatRaster \code{terra::SpatRaster} object, with +each variable as a layer. +} \description{ This function extracts a slice of one or more climate variables for a given dataset covering a region (or the whole world). The function returns a diff --git a/man/sample_region_series.Rd b/man/sample_region_series.Rd index 6e591876..58906faf 100644 --- a/man/sample_region_series.Rd +++ b/man/sample_region_series.Rd @@ -21,6 +21,10 @@ defaults to "random"} \item{na.rm}{boolean determining whether NAs are removed} } +\value{ +a data.frame with the sampled cells and their respective values for +the climate variables. +} \description{ This function samples points from a region time series. Sampling can either be performed for the same locations at all time steps (if only one value is given diff --git a/man/sample_region_slice.Rd b/man/sample_region_slice.Rd index 2d2b4457..c1f7715f 100644 --- a/man/sample_region_slice.Rd +++ b/man/sample_region_slice.Rd @@ -19,8 +19,12 @@ defaults to "random"} \item{na.rm}{boolean determining whether NAs are removed} } +\value{ +a data.frame with the sampled cells and their respective values for +the climate variables. +} \description{ -This function samples points from a region time slice (i.e. a timepoint). +This function samples points from a region time slice (i.e. a time point). } \details{ This function wraps \code{terra::spatSample} to appropriate sample the diff --git a/man/sample_rs_fixed.Rd b/man/sample_rs_fixed.Rd index b34782ab..24cfa190 100644 --- a/man/sample_rs_fixed.Rd +++ b/man/sample_rs_fixed.Rd @@ -20,6 +20,10 @@ defaults to "random"} \item{na.rm}{boolean determining whether NAs are removed} } +\value{ +a data.frame with the sampled cells and their respective values for +the climate variables. +} \description{ Internal function for fixed sampling from \code{sample_region_series}, used when a single size is given. diff --git a/man/sample_rs_variable.Rd b/man/sample_rs_variable.Rd index e95eed39..b4a014a1 100644 --- a/man/sample_rs_variable.Rd +++ b/man/sample_rs_variable.Rd @@ -19,6 +19,10 @@ defaults to "random"} \item{na.rm}{boolean determining whether NAs are removed} } +\value{ +a data.frame with the sampled cells and their respective values for +the climate variables. +} \description{ Internal function for sampling different number of points for each timestep of a region series from \code{sample_region_series}, diff --git a/man/set_data_path.Rd b/man/set_data_path.Rd index 0a108fbf..3e67b6c4 100644 --- a/man/set_data_path.Rd +++ b/man/set_data_path.Rd @@ -4,12 +4,29 @@ \alias{set_data_path} \title{Set the data path where climate reconstructions will be stored} \usage{ -set_data_path(path_to_nc = NULL) +set_data_path( + path_to_nc = NULL, + ask = TRUE, + write_config = TRUE, + copy_example = TRUE +) } \arguments{ \item{path_to_nc}{the path to the file that contains the downloaded reconstructions. If left unset, the default location returned by `tools::R_user_dir("pastclim","data")` will be used} + +\item{ask}{boolean on whether the user should be asked to confirm their +choices} + +\item{write_config}{boolean on whether the path should be saved in a config +file} + +\item{copy_example}{boolean on whether the example dataset should be saved +in the data_path} +} +\value{ +TRUE if the path was set correctly } \description{ This function sets the path where climate reconstructions will be stored. diff --git a/man/set_data_path_for_CRAN.Rd b/man/set_data_path_for_CRAN.Rd new file mode 100644 index 00000000..5d2ba6fa --- /dev/null +++ b/man/set_data_path_for_CRAN.Rd @@ -0,0 +1,16 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/set_data_path.R +\name{set_data_path_for_CRAN} +\alias{set_data_path_for_CRAN} +\title{Set the data path for examples on CRAN} +\usage{ +set_data_path_for_CRAN() +} +\value{ +None +} +\description{ +Users should NOT need this function. It is used to set up a +data path in the temporary directory for examples and tests +to run on CRAN. +} diff --git a/man/slice_region_series.Rd b/man/slice_region_series.Rd index 258ace2c..8e4117ef 100644 --- a/man/slice_region_series.Rd +++ b/man/slice_region_series.Rd @@ -16,6 +16,9 @@ can use \code{time_bp(x[[1]])} (note that you have to use the `time` function on the first element of the 'sds' object, i.e. on one of the 'SpatRaster' objects)} } +\value{ +a \code{SpatRaster} of the relevant slice. +} \description{ This function extracts a time slice from time series of one or more climate variables for a given dataset covering a region (or the whole world). diff --git a/man/time_bp.Rd b/man/time_bp.Rd index d0de696e..6e346004 100644 --- a/man/time_bp.Rd +++ b/man/time_bp.Rd @@ -9,6 +9,9 @@ time_bp(x) \arguments{ \item{x}{a \code{terra::SpatRaster}} } +\value{ +a date in years BP (where negative numbers indicate a date in the past) +} \description{ A wrapper around \code{terra::time}, which converts time into years before present diff --git a/man/time_bp_series.Rd b/man/time_bp_series.Rd index 93a49836..d027d683 100644 --- a/man/time_bp_series.Rd +++ b/man/time_bp_series.Rd @@ -11,6 +11,9 @@ time_bp_series(time_bp, time_steps) \item{time_steps}{time steps for which reconstructions are available} } +\value{ +the indeces for the relevant time steps +} \description{ Internal function } diff --git a/man/time_bp_to_index.Rd b/man/time_bp_to_index.Rd index a960330d..fcecf08e 100644 --- a/man/time_bp_to_index.Rd +++ b/man/time_bp_to_index.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/time_bp_to_index.R \name{time_bp_to_index} \alias{time_bp_to_index} -\title{Convert a time BP to indexes in a netcdf file.} +\title{Find the closest index to a given time in years BP} \usage{ time_bp_to_index(time_bp, time_steps) } @@ -11,6 +11,9 @@ time_bp_to_index(time_bp, time_steps) \item{time_steps}{time steps for which reconstructions are available} } +\value{ +the indeces for the relevant time steps +} \description{ Internal function } diff --git a/man/time_series_for_locations.Rd b/man/time_series_for_locations.Rd index 96e60414..a612925d 100644 --- a/man/time_series_for_locations.Rd +++ b/man/time_series_for_locations.Rd @@ -9,6 +9,9 @@ time_series_for_locations(...) \arguments{ \item{...}{arguments to be passed to \code{series}} } +\value{ +a data.frame with the climatic variables of interest +} \description{ Deprecated version of \code{location_series} } diff --git a/man/var_labels.Rd b/man/var_labels.Rd index 0fa661bb..44aad940 100644 --- a/man/var_labels.Rd +++ b/man/var_labels.Rd @@ -29,6 +29,10 @@ for plotting \examples{ var_labels("bio01", dataset = "Example") +# set the data_path for this example to run on CRAN +# users don't need to run this line +set_data_path_for_CRAN() + # for a SpatRaster climate_20k <- region_slice( time_bp = -20000, diff --git a/tests/testthat/test_check_dataset_path.R b/tests/testthat/test_check_dataset_path.R index aabd3c4e..3e212861 100644 --- a/tests/testthat/test_check_dataset_path.R +++ b/tests/testthat/test_check_dataset_path.R @@ -1,3 +1,13 @@ +# set up data path for this test +data_path <- file.path(tempdir(),"pastclim_data") +unlink(data_path, recursive = TRUE) # it should not exist, but remove it just in case +# set data path +set_data_path(path_to_nc = data_path, + ask = FALSE, + write_config = FALSE, + copy_example = TRUE) +################################################################################ + test_that("check_dataset_path errors", { expect_true(check_dataset_path("Example", NULL)) expect_error( @@ -26,3 +36,8 @@ test_that("check_dataset_path errors", { "path_to_nc does not point to a file" ) }) + +################################################################################ +# clean up for the next test +unlink(data_path, recursive = TRUE) + diff --git a/tests/testthat/test_df_from_region_series.R b/tests/testthat/test_df_from_region_series.R index 8cd6ce68..9f27f1e9 100644 --- a/tests/testthat/test_df_from_region_series.R +++ b/tests/testthat/test_df_from_region_series.R @@ -1,3 +1,13 @@ +# set up data path for this test +data_path <- file.path(tempdir(),"pastclim_data") +unlink(data_path, recursive = TRUE) # it should not exist, but remove it just in case +# set data path +set_data_path(path_to_nc = data_path, + ask = FALSE, + write_config = FALSE, + copy_example = TRUE) +################################################################################ + test_that("get df from region series", { x <- region_series( time_bp = list(min=-15000,max=0), c("bio01", "bio10", "bio12"), @@ -5,4 +15,8 @@ test_that("get df from region series", { ) df_series <- df_from_region_series(x ,xy=TRUE) expect_true(length(unique(df_series$time_bp))==4) -}) \ No newline at end of file +}) + +################################################################################ +# clean up for the next test +unlink(data_path, recursive = TRUE) diff --git a/tests/testthat/test_df_from_region_slice.R b/tests/testthat/test_df_from_region_slice.R index 3693e529..38cff6ac 100644 --- a/tests/testthat/test_df_from_region_slice.R +++ b/tests/testthat/test_df_from_region_slice.R @@ -1,3 +1,13 @@ +# set up data path for this test +data_path <- file.path(tempdir(),"pastclim_data") +unlink(data_path, recursive = TRUE) # it should not exist, but remove it just in case +# set data path +set_data_path(path_to_nc = data_path, + ask = FALSE, + write_config = FALSE, + copy_example = TRUE) +################################################################################ + test_that("get df from region slice", { x <- region_slice( time_bp = -10000, c("bio01", "bio10", "bio12"), @@ -9,4 +19,8 @@ test_that("get df from region slice", { expect_false(all(c("x","y") %in% names(df_slice))) expect_error(df_from_region_slice("foo", xy=FALSE), "x is not a valid SpatRaster ") -}) \ No newline at end of file +}) + +################################################################################ +# clean up for the next test +unlink(data_path, recursive = TRUE) diff --git a/tests/testthat/test_download_dataset.R b/tests/testthat/test_download_dataset.R index 6c1f83d6..e13d31cf 100644 --- a/tests/testthat/test_download_dataset.R +++ b/tests/testthat/test_download_dataset.R @@ -1,3 +1,13 @@ +# set up data path for this test +data_path <- file.path(tempdir(),"pastclim_data") +unlink(data_path, recursive = TRUE) # it should not exist, but remove it just in case +# set data path +set_data_path(path_to_nc = data_path, + ask = FALSE, + write_config = FALSE, + copy_example = TRUE) +################################################################################ + test_that("download_dataset", { expect_error( download_dataset("Beyer"), @@ -14,3 +24,8 @@ test_that("download_dataset", { # expect no error as the dataset exists expect_error(download_dataset("Example"), NA) }) + +################################################################################ +# clean up for the next test +unlink(data_path, recursive = TRUE) + diff --git a/tests/testthat/test_get_available_dataset.R b/tests/testthat/test_get_available_dataset.R index 9f9b4e08..4561b4f4 100644 --- a/tests/testthat/test_get_available_dataset.R +++ b/tests/testthat/test_get_available_dataset.R @@ -1,3 +1,13 @@ +# set up data path for this test +data_path <- file.path(tempdir(),"pastclim_data") +unlink(data_path, recursive = TRUE) # it should not exist, but remove it just in case +# set data path +set_data_path(path_to_nc = data_path, + ask = FALSE, + write_config = FALSE, + copy_example = TRUE) +################################################################################ + testthat::test_that("get_and_check_available_datasets", { testthat::expect_true(all(get_available_datasets() %in% c( "Beyer2020", @@ -16,3 +26,7 @@ testthat::test_that("get_and_check_available_datasets", { "'dataset' must be one of " ) }) + +################################################################################ +# clean up for the next test +unlink(data_path, recursive = TRUE) diff --git a/tests/testthat/test_get_biome_classes.R b/tests/testthat/test_get_biome_classes.R index e45774f8..f19078dd 100644 --- a/tests/testthat/test_get_biome_classes.R +++ b/tests/testthat/test_get_biome_classes.R @@ -1,4 +1,18 @@ +# set up data path for this test +data_path <- file.path(tempdir(),"pastclim_data") +unlink(data_path, recursive = TRUE) # it should not exist, but remove it just in case +# set data path +set_data_path(path_to_nc = data_path, + ask = FALSE, + write_config = FALSE, + copy_example = TRUE) +################################################################################ + testthat::test_that("get biome classes", { # check that we have 29 classes as expected expect_true(nrow(get_biome_classes("Example")) == 29) }) + +################################################################################ +# clean up for the next test +unlink(data_path, recursive = TRUE) diff --git a/tests/testthat/test_get_downloaded_datasets.R b/tests/testthat/test_get_downloaded_datasets.R index def5f0b3..988384cc 100644 --- a/tests/testthat/test_get_downloaded_datasets.R +++ b/tests/testthat/test_get_downloaded_datasets.R @@ -1,3 +1,14 @@ +# set up data path for this test +data_path <- file.path(tempdir(),"pastclim_data") +unlink(data_path, recursive = TRUE) # it should not exist, but remove it just in case +# set data path +set_data_path(path_to_nc = data_path, + ask = FALSE, + write_config = FALSE, + copy_example = TRUE) +################################################################################ + + testthat::test_that("get_downloaded_datasets", { path_to_example_nc <- system.file("/extdata/", package = "pastclim") # there is only the Example dataset available @@ -18,3 +29,7 @@ testthat::test_that("get_downloaded_datasets", { "^variable" ) }) + +################################################################################ +# clean up for the next test +unlink(data_path, recursive = TRUE) diff --git a/tests/testthat/test_get_file_for_dataset.R b/tests/testthat/test_get_file_for_dataset.R index de1b9d0b..2784a294 100644 --- a/tests/testthat/test_get_file_for_dataset.R +++ b/tests/testthat/test_get_file_for_dataset.R @@ -1,3 +1,13 @@ +# set up data path for this test +data_path <- file.path(tempdir(),"pastclim_data") +unlink(data_path, recursive = TRUE) # it should not exist, but remove it just in case +# set data path +set_data_path(path_to_nc = data_path, + ask = FALSE, + write_config = FALSE, + copy_example = TRUE) +################################################################################ + test_that("get_file_for_dataset", { expect_true(nrow(get_file_for_dataset("bio01", "Example")) == 1) expect_error( @@ -10,3 +20,7 @@ test_that("get_file_for_dataset", { "^'dataset' must be one of " ) }) + +################################################################################ +# clean up for the next test +unlink(data_path, recursive = TRUE) diff --git a/tests/testthat/test_get_mis_time_steps.R b/tests/testthat/test_get_mis_time_steps.R index 55348749..c4500f2f 100644 --- a/tests/testthat/test_get_mis_time_steps.R +++ b/tests/testthat/test_get_mis_time_steps.R @@ -1,3 +1,13 @@ +# set up data path for this test +data_path <- file.path(tempdir(),"pastclim_data") +unlink(data_path, recursive = TRUE) # it should not exist, but remove it just in case +# set data path +set_data_path(path_to_nc = data_path, + ask = FALSE, + write_config = FALSE, + copy_example = TRUE) +################################################################################ + test_that("get_mis_time_steps for standard dataset", { expect_equal(get_mis_time_steps(mis = "2", dataset = "Example"), c(-20000, -15000), @@ -27,3 +37,7 @@ test_that("get_mis_time_steps requires correct variables", { "'mis' should be one of" ) }) + +################################################################################ +# clean up for the next test +unlink(data_path, recursive = TRUE) \ No newline at end of file diff --git a/tests/testthat/test_get_set_data_path.R b/tests/testthat/test_get_set_data_path.R index c594e744..df4b934f 100644 --- a/tests/testthat/test_get_set_data_path.R +++ b/tests/testthat/test_get_set_data_path.R @@ -1,24 +1,44 @@ +# start with a clean slate in case other tests set up the path +options(pastclim.data_path = NULL) # reset the option + test_that("set and get data path", { - # set data path to temp dir - set_data_path(tempdir()) - expect_true(file.exists(file.path( - tools::R_user_dir("pastclim", "config"), - "pastclim_data.txt" - ))) - expect_equal(get_data_path(), tempdir()) - # give error if custom dir does not exist - expect_error(set_data_path("blah/blah"),"blah") + # try to get path when none is set + expect_message(null_data_path <- get_data_path()) + expect_null(null_data_path) + # now do the same in silent mode + expect_no_message(null_data_path <- get_data_path(silent = TRUE)) + expect_null(null_data_path) + + # now set the path in a subdirectory of tempdir + data_path <- file.path(tempdir(),"pastclim_data") + unlink(data_path, recursive = TRUE) # it should not exist, but remove it just in case + # set data path + expect_true(set_data_path(path_to_nc = data_path, + ask = FALSE, + write_config = FALSE, + copy_example = FALSE)) + expect_equal(get_data_path(), data_path) + unlink(data_path, recursive = TRUE) # clean up + options(pastclim.data_path = NULL) # reset the option - # use dir with spaces - new_path <- file.path(tempdir(),"/Users/pkgbuilds/Library/Application Support/org.R-project.R/R/pastclim") - if (!dir.exists(new_path)){ - dir.create(new_path, recursive = TRUE) - } - set_data_path(new_path) - expect_equal(get_data_path(), new_path) - # now use the standard directory for the library - set_data_path() - expect_equal(get_data_path(), tools::R_user_dir("pastclim", "data")) - # give error if custom dir does not exist - expect_error(set_data_path("blah/blah"),"blah") + # use dir with spaces (as it is the case for the default data dir on MacOS) + data_path <- file.path(tempdir(),"/Users/pkgbuilds/Library/Application Support/org.R-project.R/R/pastclim") + unlink(data_path, recursive = TRUE) # it should not exist, but remove it just in case + expect_true(set_data_path(path_to_nc = data_path, + ask = FALSE, + write_config = FALSE, + copy_example = FALSE)) + expect_equal(get_data_path(), data_path) + # this should be empty + expect_true(length(dir(data_path)) ==0) + # now copy the data files + options(pastclim.data_path = NULL) # reset the option + + expect_true(set_data_path(path_to_nc = data_path, + ask = FALSE, + write_config = FALSE, + copy_example = TRUE)) + # there should be a file now + expect_true(length(dir(data_path)) == 1) + unlink(data_path, recursive = TRUE) # clean up }) diff --git a/tests/testthat/test_get_time_steps.R b/tests/testthat/test_get_time_steps.R index 702f22fb..c3ea551e 100644 --- a/tests/testthat/test_get_time_steps.R +++ b/tests/testthat/test_get_time_steps.R @@ -1,3 +1,13 @@ +# set up data path for this test +data_path <- file.path(tempdir(),"pastclim_data") +unlink(data_path, recursive = TRUE) # it should not exist, but remove it just in case +# set data path +set_data_path(path_to_nc = data_path, + ask = FALSE, + write_config = FALSE, + copy_example = TRUE) +################################################################################ + test_that("get_time_steps requires correct variables", { expect_error( get_time_steps(dataset = "blah"), @@ -35,3 +45,8 @@ test_that("get_time_steps for local file", { ignore_attr = TRUE ) }) + + +################################################################################ +# clean up for the next test +unlink(data_path, recursive = TRUE) diff --git a/tests/testthat/test_get_vars_for_dataset.R b/tests/testthat/test_get_vars_for_dataset.R index 630dbb8f..ea0f38a1 100644 --- a/tests/testthat/test_get_vars_for_dataset.R +++ b/tests/testthat/test_get_vars_for_dataset.R @@ -1,3 +1,13 @@ +# set up data path for this test +data_path <- file.path(tempdir(),"pastclim_data") +unlink(data_path, recursive = TRUE) # it should not exist, but remove it just in case +# set data path +set_data_path(path_to_nc = data_path, + ask = FALSE, + write_config = FALSE, + copy_example = TRUE) +################################################################################ + test_that("get_vars_for_dataset give appropriate errors", { expect_error( get_vars_for_dataset(dataset = "blah"), @@ -32,3 +42,7 @@ test_that("get_vars_for_dataset for local file", { details = TRUE) expect_true(inherits(vars,"data.frame")) }) + +################################################################################ +# clean up for the next test +unlink(data_path, recursive = TRUE) \ No newline at end of file diff --git a/tests/testthat/test_is_region_series.R b/tests/testthat/test_is_region_series.R index 052ab3bd..4b93340b 100644 --- a/tests/testthat/test_is_region_series.R +++ b/tests/testthat/test_is_region_series.R @@ -1,3 +1,13 @@ +# set up data path for this test +data_path <- file.path(tempdir(),"pastclim_data") +unlink(data_path, recursive = TRUE) # it should not exist, but remove it just in case +# set data path +set_data_path(path_to_nc = data_path, + ask = FALSE, + write_config = FALSE, + copy_example = TRUE) +################################################################################ + test_that("is_region_series returns correct values", { climate_region <- region_series( time_bp = list(min=-15000,max=0), c("bio01", "bio10", "bio12"), @@ -30,7 +40,9 @@ test_that("is_region_series returns correct values", { ) expect_error(is_region_series(europe_climate_20k), "x should be a SpatRasterDataset") - - - -}) \ No newline at end of file +}) + +################################################################################ +# clean up for the next test +unlink(data_path, recursive = TRUE) + diff --git a/tests/testthat/test_location_series.R b/tests/testthat/test_location_series.R index 88998f5d..d6fd188c 100644 --- a/tests/testthat/test_location_series.R +++ b/tests/testthat/test_location_series.R @@ -1,3 +1,13 @@ +# set up data path for this test +data_path <- file.path(tempdir(),"pastclim_data") +unlink(data_path, recursive = TRUE) # it should not exist, but remove it just in case +# set data path +set_data_path(path_to_nc = data_path, + ask = FALSE, + write_config = FALSE, + copy_example = TRUE) +################################################################################ + test_that("time_series_for_location", { # using standard dataset locations <- data.frame(name=c("A","B","C","D"), @@ -110,3 +120,7 @@ test_that("time_series_for_location", { "path_to_nc does not point to a file" ) }) + +################################################################################ +# clean up for the next test +unlink(data_path, recursive = TRUE) \ No newline at end of file diff --git a/tests/testthat/test_location_slice.R b/tests/testthat/test_location_slice.R index 2e31df42..27bbd7ef 100644 --- a/tests/testthat/test_location_slice.R +++ b/tests/testthat/test_location_slice.R @@ -1,3 +1,13 @@ +# set up data path for this test +data_path <- file.path(tempdir(),"pastclim_data") +unlink(data_path, recursive = TRUE) # it should not exist, but remove it just in case +# set data path +set_data_path(path_to_nc = data_path, + ask = FALSE, + write_config = FALSE, + copy_example = TRUE) +################################################################################ + test_that("location_slice", { locations <- data.frame( name = c("A","B","C","D"), @@ -130,3 +140,7 @@ test_that("location_slice", { expect_true(identical(this_climate[, -c(1:3)], this_climate_timeoff[, -c(1:3)])) }) + +################################################################################ +# clean up for the next test +unlink(data_path, recursive = TRUE) \ No newline at end of file diff --git a/tests/testthat/test_region_series.R b/tests/testthat/test_region_series.R index 514706a8..19755eb2 100644 --- a/tests/testthat/test_region_series.R +++ b/tests/testthat/test_region_series.R @@ -1,3 +1,13 @@ +# set up data path for this test +data_path <- file.path(tempdir(),"pastclim_data") +unlink(data_path, recursive = TRUE) # it should not exist, but remove it just in case +# set data path +set_data_path(path_to_nc = data_path, + ask = FALSE, + write_config = FALSE, + copy_example = TRUE) +################################################################################ + test_that("region series", { # using standard dataset climate_region <- region_series( @@ -99,7 +109,7 @@ test_that("ext on region series", { dataset = "Example", ext = ext ), NA) - +}) test_that("crop on region series", { # this should work @@ -125,8 +135,9 @@ test_that("ext on region series", { dataset = "Example", crop = region_outline$Eurasia),NA) - }) - - + }) - + +################################################################################ +# clean up for the next test +unlink(data_path, recursive = TRUE) diff --git a/tests/testthat/test_region_slice.R b/tests/testthat/test_region_slice.R index fb242d03..48b2a297 100644 --- a/tests/testthat/test_region_slice.R +++ b/tests/testthat/test_region_slice.R @@ -1,3 +1,13 @@ +# set up data path for this test +data_path <- file.path(tempdir(),"pastclim_data") +unlink(data_path, recursive = TRUE) # it should not exist, but remove it just in case +# set data path +set_data_path(path_to_nc = data_path, + ask = FALSE, + write_config = FALSE, + copy_example = TRUE) +################################################################################ + test_that("region slice", { # using standard dataset climate_slice <- region_slice( @@ -27,3 +37,7 @@ test_that("region slice", { "time_bp should be a single time step" ) }) + +################################################################################ +# clean up for the next test +unlink(data_path, recursive = TRUE) diff --git a/tests/testthat/test_sample_region_series.R b/tests/testthat/test_sample_region_series.R index 40c35c72..8523cd2f 100644 --- a/tests/testthat/test_sample_region_series.R +++ b/tests/testthat/test_sample_region_series.R @@ -1,3 +1,13 @@ +# set up data path for this test +data_path <- file.path(tempdir(),"pastclim_data") +unlink(data_path, recursive = TRUE) # it should not exist, but remove it just in case +# set data path +set_data_path(path_to_nc = data_path, + ask = FALSE, + write_config = FALSE, + copy_example = TRUE) +################################################################################ + test_that("sample_region_series works correctly", { set.seed(123) # sample series @@ -40,3 +50,7 @@ test_that("sample_region_series works correctly", { expect_error(sample_region_series(climate_ts, size = n_points), "x is not a valid object generated by region_series") }) + +################################################################################ +# clean up for the next test +unlink(data_path, recursive = TRUE) diff --git a/tests/testthat/test_sample_region_slice.R b/tests/testthat/test_sample_region_slice.R index 5b3eb3f2..c668e06a 100644 --- a/tests/testthat/test_sample_region_slice.R +++ b/tests/testthat/test_sample_region_slice.R @@ -1,3 +1,13 @@ +# set up data path for this test +data_path <- file.path(tempdir(),"pastclim_data") +unlink(data_path, recursive = TRUE) # it should not exist, but remove it just in case +# set data path +set_data_path(path_to_nc = data_path, + ask = FALSE, + write_config = FALSE, + copy_example = TRUE) +################################################################################ + test_that("sample_region_slice samples correctly", { climate_20k <- region_slice( time_bp = -20000, @@ -14,4 +24,7 @@ test_that("sample_region_slice samples correctly", { expect_error(sample_region_slice(climate_20k,c(10,10)), "size should be a single value") }) - \ No newline at end of file + +################################################################################ +# clean up for the next test +unlink(data_path, recursive = TRUE) diff --git a/tests/testthat/test_slice_region_series.R b/tests/testthat/test_slice_region_series.R index 26a604e2..3e7ea1b2 100644 --- a/tests/testthat/test_slice_region_series.R +++ b/tests/testthat/test_slice_region_series.R @@ -1,3 +1,13 @@ +# set up data path for this test +data_path <- file.path(tempdir(),"pastclim_data") +unlink(data_path, recursive = TRUE) # it should not exist, but remove it just in case +# set data path +set_data_path(path_to_nc = data_path, + ask = FALSE, + write_config = FALSE, + copy_example = TRUE) +################################################################################ + test_that("climate_for_time_slice", { climate_region <- region_series( c(-20000, -10000), c("bio01", "bio12"), @@ -23,3 +33,7 @@ test_that("climate_for_time_slice", { expect_error(slice_region_series(climate_region, time_bp = -10000), "x is not a valid object generated by region_series") }) + +################################################################################ +# clean up for the next test +unlink(data_path, recursive = TRUE) diff --git a/tests/testthat/test_time_bp_series.R b/tests/testthat/test_time_bp_series.R index f69e40cb..79efdf09 100644 --- a/tests/testthat/test_time_bp_series.R +++ b/tests/testthat/test_time_bp_series.R @@ -1,3 +1,13 @@ +# set up data path for this test +data_path <- file.path(tempdir(),"pastclim_data") +unlink(data_path, recursive = TRUE) # it should not exist, but remove it just in case +# set data path +set_data_path(path_to_nc = data_path, + ask = FALSE, + write_config = FALSE, + copy_example = TRUE) +################################################################################ + test_that("time_bp_series returns correct values", { time_bp <- c(-10000,-20000) time_steps <- sort(-seq(0,20000,by = 5000)) @@ -27,4 +37,9 @@ test_that("time_bp_series returns correct values", { ##################################################### expect_error(time_bp_series("blah",time_steps), "time_bp can only be") -}) \ No newline at end of file +}) + +################################################################################ +# clean up for the next test +unlink(data_path, recursive = TRUE) + diff --git a/tests/testthat/test_var_labels.R b/tests/testthat/test_var_labels.R index 33c02406..c7311882 100644 --- a/tests/testthat/test_var_labels.R +++ b/tests/testthat/test_var_labels.R @@ -1,3 +1,13 @@ +# set up data path for this test +data_path <- file.path(tempdir(),"pastclim_data") +unlink(data_path, recursive = TRUE) # it should not exist, but remove it just in case +# set data path +set_data_path(path_to_nc = data_path, + ask = FALSE, + write_config = FALSE, + copy_example = TRUE) +################################################################################ + test_that("var_labels for plots", { # check that we can correctly return expressions for every variable (i.e. # that nothing is malforms and crashes the parsing) @@ -32,4 +42,8 @@ test_that("var_labels for plots", { expect_error(var_labels(matrix(1:4,ncol=1), dataset = "Example"), "x should be either a character vector or a SpatRaster") } -) \ No newline at end of file +) + +################################################################################ +# clean up for the next test +unlink(data_path, recursive = TRUE) diff --git a/vignettes/a0_pastclim_overview.Rmd b/vignettes/a0_pastclim_overview.Rmd index 85922029..9c265d94 100644 --- a/vignettes/a0_pastclim_overview.Rmd +++ b/vignettes/a0_pastclim_overview.Rmd @@ -17,7 +17,7 @@ knitr::opts_chunk$set( # Install the library -You will need to install the library from Github. For this step, you will need to +You will need to install the library from GitHub. For this step, you will need to use `devtools` (if you haven't done so already, install it from CRAN with `install.packages("devtools")`. Once you have `devtools`, simply use: ```{r install, eval=FALSE} @@ -85,24 +85,41 @@ pastclim:::get_dataset_info(dataset="Beyer2020") ``` For the datasets available in `pastclim`, there are functions that help you download the data -and choose the variables. +and choose the variables. When you start `pastclim` for the first time, you will +need to set the path where reconstructions are stored using `set_data_path`. By +default, the package data path will be used: -Datasets will stored in the package data path, which can be obtained with: +```{r eval=FALSE} +library(pastclim) +set_data_path() +``` -```{r} +```{r echo=FALSE, results='hide'} library(pastclim) -get_data_path() +set_data_path_for_CRAN() ``` +``` +#> The data_path will be set to /home/andrea/.local/share/R/pastclim. +#> A copy of the Example dataset will be copied there. +#> This path will be saved by pastclim for future use. +#> Proceed? +#> +#> 1: Yes +#> 2: No +``` + +Press 1 if you are happy with the offered choices, and `pastclim` +will remember your data path in future sessions. Note that your +data path will look different than in this example, as it depends +on your user name and operating system. + If you prefer using a custom path (e.g. in "~/my_reconstructions"), it can be set with: ```{r eval=FALSE} set_data_path(path_to_nc = "~/my_reconstructions") ``` -`pastclim` will remember this new path in the future, even after closing and restarting -R. - The package includes a small dataset, *Example*, that we will use in this vignette but is not suitable for running analyses; the real datasets are large (from 100s of Mb to a few Gb), and you will need to specify what you want to download (see below). diff --git a/vignettes/a1_available_datasets.Rmd b/vignettes/a1_available_datasets.Rmd index 03525a48..e3401aa9 100644 --- a/vignettes/a1_available_datasets.Rmd +++ b/vignettes/a1_available_datasets.Rmd @@ -21,6 +21,20 @@ A number of datasets are available in pastclim. It is possible to use custom dat ```{r} library(pastclim) +``` + +```{r echo=FALSE, results='hide'} +data_path <- file.path(tempdir(),"pastclim_data") +# clear it in case it exists already +unlink(data_path, recursive = TRUE) +# set data path +set_data_path(path_to_nc = data_path, + ask = FALSE, + write_config = FALSE, + copy_example = TRUE) +``` + +```{r} get_available_datasets() ``` diff --git a/vignettes/a2_custom_datasets.Rmd b/vignettes/a2_custom_datasets.Rmd index e1d055f5..1a0afcdd 100644 --- a/vignettes/a2_custom_datasets.Rmd +++ b/vignettes/a2_custom_datasets.Rmd @@ -21,7 +21,7 @@ This guide is aimed at formatting data in such a way that they can be used with ## An example: the Trace21k-CHELSEA -Here we provide a simple example of how to format such a dataset in R. We will use a version of the Trace21k dataset, downscaled to 30 arcsecs using the CHELSEA algorithm(available from [this website](https://chelsa-climate.org/chelsa-trace21k/)). The data are stored as geoTIFF files, one file per timestep per variable. First, we need to collate all the files for a given variable (we will use *bio01* as an example) within a single `netcdf` file. As the original files are large, we will illustrate here how do to that for only a few timesteps which were aggregated to 3x3 degrees to keep files sizes small. +Here we provide a simple example of how to format such a dataset in R. We will use a version of the Trace21k dataset, downscaled to 30 arcsecs using the CHELSEA algorithm(available from [this website](https://chelsa-climate.org/chelsa-trace21k/)). The data are stored as geoTIFF files, one file per time step per variable. First, we need to collate all the files for a given variable (we will use *bio01* as an example) within a single `netcdf` file. As the original files are large, we will illustrate here how do to that for only a few time steps which were aggregated to 3x3 degrees to keep files sizes small. We start by translating each geoTIFF into a `netcdf` file. The files have the prefix *CHELSA_TraCE21k_bio01_-**xxx**_V1.0.small.tif*, where **xxx** is the number of the time step. We will only use 3 time step for illustrative purposes. @@ -35,7 +35,7 @@ list_of_tiffs <- file.path(tiffs_path,dir(tiffs_path)) bio01 <- terra::rast(list_of_tiffs) ``` -Now we need to set the time axis of the raster (in this case, reconstructions are every 100 years), and generate some userfriendly names to layers in the raster: +Now we need to set the time axis of the raster (in this case, reconstructions are every 100 years), and generate some user friendly names to layers in the raster: ```{r} terra::time(bio01)<-c(0,-100,-200) @@ -65,9 +65,23 @@ ncdf4::nc_close(nc_in) ``` -We can now read in our custom netcdf file. +We can now read in our custom netcdf file with `pastclim`. ```{r} library(pastclim) +``` + +```{r echo=FALSE, results='hide'} +data_path <- file.path(tempdir(),"pastclim_data") +# clear it in case it exists already +unlink(data_path, recursive = TRUE) +# set data path +set_data_path(path_to_nc = data_path, + ask = FALSE, + write_config = FALSE, + copy_example = TRUE) +``` + +```{r} custom_series <- region_series(bio_variables = "bio01", dataset = "custom", path_to_nc = nc_name @@ -86,13 +100,13 @@ climate_100<-slice_region_series(custom_series, time_bp = -100) terra::plot(climate_100) ``` -Note that these reconstructions include the ocean and the icesheets, and it would -be much better to remove them as they are not needed for most ecological/archaological studies (and +Note that these reconstructions include the ocean and the ice sheets, and it would +be much better to remove them as they are not needed for most ecological/archaeological studies (and it allows for smaller files). # Making the data available to others -Once you have created suitably fomatted netcdf files that can be used as custom datasets in +Once you have created suitably formatted netcdf files that can be used as custom datasets in `pastclim`, you can add those data officially to the package, and thus make them available to others. Here are the necessary steps: @@ -142,6 +156,6 @@ the *nc* dataset. 3) Once you have added lines detailing the variables in your dataset, run the script "./inst/rawdata_scripts/create_files_by_dataset.R" to store that information into the appropriate dataset in `pastclim`. -4) Provide information on the new dataset in the file "./R/dataset_docs", using `roxygen2` notation. Make sure that you provide an appropriate reference for the original data, as it is important that users can refer back to the original source. +4) Provide information on the new dataset in the file "./R/dataset_docs", using `roxygen2` syntax. Make sure that you provide an appropriate reference for the original data, as it is important that users can refer back to the original source. 4) Make a Pull Request on GitHub. \ No newline at end of file