Merge branch 'cran_changes' into dev

.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]
 

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 = "[email protected]")
      )
 Maintainer: Andrea Manica <[email protected]>
-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) <doi:10.1101/2022.05.18.492456>.
 License: CC BY 4.0
 Language: en-GB
 URL: https://github.com/EvolEcolGroup/pastclim,

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)

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
 
 

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
 
 

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
 

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)
 }

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
 

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
 

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)
 }

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() {

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
 

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)
+  }
+}

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
 

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
-}
+}

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

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

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) {

R/is_region_series.R

@@ -1,18 +1,19 @@
 #' 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
 #'
 #' @param x a \code{terra::SpatRasterDataset} representing a time series of
 #' 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
 

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
 

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
 

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

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
 

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
 

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)