Merge remote-tracking branch 'origin/dev' into dev

.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,28 @@
+<!-- This CODE_OF_CONDUCT.md is adapted from the same document in the tidyverse package -->
+
+
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who 
+contribute through reporting issues, posting feature requests, updating documentation,
+submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for
+everyone, regardless of level of experience, gender, gender identity and expression,
+sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or
+imagery, derogatory comments or personal attacks, trolling, public or private harassment,
+insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments,
+commits, code, wiki edits, issues, and other contributions that are not aligned to this 
+Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed 
+from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by 
+opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the Contributor Covenant 
+(https://www.contributor-covenant.org), version 1.0.0, available at 
+https://contributor-covenant.org/version/1/0/0/.

.github/CONTRIBUTING.md

@@ -0,0 +1,102 @@
+# Contributing to pastclim
+
+
+This document outlines how to contribute to the development of `pastclim`. The
+package is maintained on a voluntary basis, so help is always appreciated. 
+
+## The basic process of contributing
+
+Development work for `pastclim` occurs in the `dev` branch. So, if you want to
+propose any changes, you should work on `dev`. Start by forking the project
+onto your github repository, make the changes directly in your fork (either in
+the `dev` branch, or make a custom branch). After updating all the documentation
+and checking that all tests pass (see below), start a Pull Request. Your proposed
+changes will be reviewed, and you might be asked to fix/improve your code. This
+can be an iterative process, requiring a few rounds of revision depending on
+the complexity of the code.
+
+Functions should be documented using [`roxygen`](https://cran.r-project.org/web/packages/roxygen2/vignettes/roxygen2.html).
+If any of your changes affects the documentation , you should rebuild it.
+From the root directory of the package, simply run:
+
+```
+devtools::document()
+```
+
+If you implemented a new functionality, or patched a bug, you should consider 
+whether you should add an appropriate unit test. `pastclim` uses the `testthat` 
+framework for unit tests. You should make sure that tests work with :
+```
+devtools::test()
+```
+
+Finally, before you submit a push request, you should check that your changes 
+don't break the build. You can do that with `check`, which also builds the 
+vignette and runs the tests.:
+```
+devtools::check()
+```
+
+Make sure that you have resolved all warnings and notes raised by
+`devtools::check()`!
+
+Once you have followed **those 3 steps**, you are ready to make your Pull Request.
+Your changes will go through automatic continuous integration, which will check
+the impact of those changes on multiple platforms. If everything goes well, you
+will see a green tick on your submission.
+
+## Fixing typos
+
+If you spot typos, spelling mistakes, or grammatical errors in the documentation,
+you should fix them directly in the file that describes the function. This is the
+`.R` file in the `R` directory, NOT the `.Rd` file in the `man` directory. `.Rd`
+files are automatically generated by `roxygen2` and should not be edited by hand.
+We recommend that you study first how 
+[roxygen2 comments](https://roxygen2.r-lib.org/articles/roxygen2.html) work. 
+
+## Functional changes
+
+If you want to make a change that impacts the functioning of `pastclim`,
+it's a good idea to first file an issue 
+explaining what you have in mind. If the change is meant to fix a bug, then  
+add a minimal 
+[reprex](https://www.tidyverse.org/help/#reprex). 
+
+A good reprex is also the
+perfect starting point for writing a unit test, which should accompany any
+functional change in the code. Unit tests are also essential when fixing bugs, so
+that you can both demonstrate that the fix work, and prevent future changes
+from undoing your work. For unit testing, we use `testthat`; you will find tests under
+`tests`, with a file dedicated to each function, following the convention 
+`test_my_function.R` for naming files. When creating tests, try to make use 
+built-in datasets, rather than adding data
+files to the package.
+
+Ideally, the body of your Pull Request will include the phrase `Fixes #issue-number`,
+where `issue_number` is the number on Github. In this way, your Pull Request
+will be automatically linked to the issue, and the issue will be closed when
+the Pull Request is merged in.
+
+For user-facing changes, add a bullet to the top of `NEWS.md` 
+(i.e. just below the first header). Follow the style described 
+in <https://style.tidyverse.org/news.html>.
+
+Our continuous integration checks that the Pull Request does not
+reduce test coverage.
+
+
+### Code style
+
+New code should follow the tidyverse [style guide](https://style.tidyverse.org). 
+You can use the [styler](https://CRAN.R-project.org/package=styler) package 
+to apply these styles, but please don't restyle code that has nothing to do with your PR.
+
+Lots of commenting in the code helps mantainability; so, if in doubt, always
+add an explanation to your new code.
+
+## Code of Conduct
+         
+Please note that the tidyverse project is released with a
+[Contributor Code of Conduct](CODE_OF_CONDUCT.md). By contributing to this
+project you agree to abide by its terms.
+

CRAN-SUBMISSION

@@ -1,3 +1,3 @@
-Version: 1.2.4
-Date: 2023-04-25 20:01:34 UTC
-SHA: 56d0482f982fd7b991442fd6b8fc62d4168647e3
+Version: 2.0.0
+Date: 2023-11-01 17:32:06 UTC
+SHA: dc93c5c9f92f52ac7b178eac2b7095536868867d

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: pastclim
 Type: Package
 Title: Manipulate Time Series of Palaeoclimate Reconstructions 
-Version: 1.2.4.9006
+Version: 2.0.0.9001
 Authors@R: c(
        person("Michela", "Leonardi", role = "aut"),
        person(c("Emily","Y."), "Hallet", role = "ctb"),

NAMESPACE

@@ -17,11 +17,13 @@ export(get_downloaded_datasets)
 export(get_ice_mask)
 export(get_land_mask)
 export(get_mis_time_steps)
+export(get_resolution)
 export(get_time_bp_steps)
 export(get_time_ce_steps)
 export(get_time_steps)
 export(get_vars_for_dataset)
 export(is_region_series)
+export(koeppen_geiger)
 export(list_available_datasets)
 export(location_series)
 export(location_slice)
@@ -40,6 +42,7 @@ export(var_labels)
 export(ybp2date)
 exportMethods("time_bp<-")
 exportMethods(bioclim_vars)
+exportMethods(koeppen_geiger)
 exportMethods(time_bp)
 import(methods)
 import(terra)

NEWS.md

@@ -1,10 +1,19 @@
-# development
+# development version
+* Add functions for Koeppen Geiger's classification from monthly means.
+
+# pastclim 2.0.0
+* Allow time to be defined as CE besides BP. NOTE that this adds a parameter
+  to a number of functions. If those functions were used without explicitly
+  naming parameters, old code might give an error as the order of parameters
+  has now changed).
 * Add Barreto et al 2023 (based on PALEO-PGEM, covering the last 5 M years)
 * Add all the WorldClim data (present, and future projections with multiple models
-and emission scenarios).
+  and emission scenarios).
+* Add the HYDE 3.3 database providing information on agriculture and population sizes
+  for the last 10k years.
 * Change the units of Krapp et al 2021 to match those of other datasets. Also, fix
-data duplication of some variables which has now also been fixed on the OSF repository
-for that dataset.
+  data duplication of some variables which has now also been fixed on the OSF repository
+  for that dataset.
 * Improve `get_ice_mask()`, `get_land_mask()`, and `distance_from_sea()` to work
   on series rather than just on slices.
 * Speed up `region_*()` functions when subsetting the extent/cropping.

R/bioclim_vars.R

@@ -58,7 +58,7 @@ methods::setMethod(
   }
 )
 
-#' @param filename filename where the raster can be stored.
+#' @param filename filename to save the raster (optional).
 #' @rdname bioclim_vars-methods
 #' @export
 methods::setMethod(
@@ -89,7 +89,7 @@ methods::setMethod(
 )
 
 
-#' @param filename filename where the raster can be stored.
+#' @param filename filename to save the raster (optional).
 #' @rdname bioclim_vars-methods
 #' @export
 methods::setMethod(

R/data.R

@@ -39,3 +39,17 @@
 #'   \item{name}{names of regions}
 #' }
 "region_outline_union"
+
+#' Koeppen-Geiger classes.
+#'
+#' A data.frame defining the details of each class
+#'
+#' @format A data.frame with multiple columns to describe.
+"koeppen_classes"
+
+#' BIOME4 classes.
+#'
+#' A data.frame defining the details of each class
+#'
+#' @format A data.frame with multiple columns to describe.
+"biome4_classes"

R/datasets_docs.R

@@ -18,7 +18,7 @@ NULL
 #' Beyer, R.M.,
 #' Krapp, M. & Manica, A. High-resolution terrestrial climate, bioclimate and
 #' vegetation for the last 120,000 years. Sci Data 7, 236 (2020).
-#' \doi{doi.org/10.1038/s41597-020-0552-1}
+#' \doi{10.1038/s41597-020-0552-1}
 #'
 #' The version included in `pastclim` has the ice sheets masked, as well as
 #' internal seas (Black and Caspian Sea) removed. The latter are based on:
@@ -41,7 +41,7 @@ NULL
 #'
 #' v1.0.0 Remove ice sheets and internal seas, and use correct formula for bio15.
 #' Files can be downloaded from:
-#' \doi{doi.org/10.6084/m9.figshare.19723405.v1}
+#' \doi{10.6084/m9.figshare.19723405.v1}
 #'
 #'
 #' @name Beyer2020
@@ -61,7 +61,7 @@ NULL
 #' Krapp, M., Beyer, R.M., Edmundson, S.L. et al. A statistics-based
 #' reconstruction of high-resolution global terrestrial climate for the last
 #' 800,000 years. Sci Data 8, 228 (2021).
-#' \doi{doi.org/10.1038/s41597-021-01009-3}
+#' \doi{10.1038/s41597-021-01009-3}
 #'
 #' The version included in `pastclim` has the ice sheets masked.
 #'
@@ -71,14 +71,14 @@ NULL
 #' Changelog
 #'
 #' v1.4.0 Change units to match WorldClim. Fix variable duplication found
-#' on earlier versions of the dataset.
+#' on earlier versions of the dataset. \url{https://zenodo.org/records/8415273}
 #'
 #' v1.1.0 Added monthly variables. Files can be downloaded from:
 #' \url{https://zenodo.org/record/7065055}
 #'
 #' v1.0.0 Remove ice sheets and use correct formula for bio15.
 #' Files can be downloaded from:
-#' \doi{doi.org/10.6084/m9.figshare.19733680.v1}
+#' \doi{10.6084/m9.figshare.19733680.v1}
 #'
 #' @name Krapp2021
 NULL
@@ -92,7 +92,7 @@ NULL
 #'
 #' Fick, S.E. and R.J. Hijmans, 2017. WorldClim 2: new 1km spatial resolution
 #' climate surfaces for global land areas. International Journal of Climatology 37 (12): 4302-4315.
-#' \doi{doi.org/10.1002/joc.5086}
+#' \doi{10.1002/joc.5086}
 #'
 #' **Present-day reconstructions** are based on the mean for the period 1970-2000,
 #' and are available at multiple resolutions of
@@ -177,13 +177,43 @@ NULL
 #'  PALEO-PGEM-Series: A spatial time series of the global climate over the
 #'   last 5 million years (Plio-Pleistocene). Global Ecology and
 #'    Biogeography, 32, 1034-1045,
-#'    \doi{doi.org/10.1111/geb.13683}
+#'    \doi{10.1111/geb.13683}
 #'
 #' Holden, P. B., Edwards, N. R., Rangel, T. F., Pereira, E. B., Tran, G. T.,
 #'  and Wilkinson, R. D. (2019): PALEO-PGEM v1.0: a statistical emulator of
 #'   Pliocene–Pleistocene climate, Geosci. Model Dev., 12, 5137–5155,
-#'    \doi{doi.org/10.5194/gmd-12-5137-2019}.
+#'    \doi{10.5194/gmd-12-5137-2019}.
 #'
 #' @name Barreto2023
 NULL
 #> NULL
+
+#' Documentation for HYDE 3.3 dataset
+#'
+#' This database presents an update and expansion of the History Database of
+#' the Global Environment (HYDE, v 3.3) and replaces former HYDE 3.2
+#' version from 2017. HYDE is and internally consistent combination of
+#' updated historical population estimates and land use. Categories
+#' include cropland, with a new distinction into irrigated and rain fed
+#' crops (other than rice) and irrigated and rain fed rice. Also grazing
+#' lands are provided, divided into more intensively used pasture,
+#' converted rangeland and non-converted natural (less intensively used)
+#' rangeland. Population is represented by maps of total, urban, rural
+#' population and population density as well as built-up area.
+#'
+#' The period covered is 10 000 BCE to 2023 CE. Spatial resolution is
+#' 5 arc minutes (approx. 85 km2 at the equator). The full HYDE 3.3 release
+#' contains: a Baseline estimate scenario, a Lower estimate scenario and an
+#' Upper estimate scenario. Currently only the baseline scenario is available
+#' in `pastclim`
+#'
+#' If you use this dataset, make sure to cite the original publication
+#' for the HYDE 3.2 (there is no current publication for 3.3):
+#'
+#' Klein Goldewijk, K., Beusen, A., Doelman, J., and Stehfest, E.:
+#' Anthropogenic land-use estimates for the Holocene; HYDE 3.2,
+#' Earth Syst. Sci. Data, 9, 927-953, 2017. \doi{10.5194/essd-9-1-2017}
+#'
+#' @name HYDE_3.3_baseline
+NULL
+#> NULL

R/download_dataset.R

@@ -31,7 +31,7 @@ download_dataset <- function(dataset, bio_variables = NULL, annual = TRUE,
   # check that the variable is available for this dataset
   available_variables <-
     getOption("pastclim.dataset_list")$variable[getOption("pastclim.dataset_list")$dataset == dataset]
-  # if variable is null, donwload all possible variables
+  # if variable is null, download all possible variables
   if (is.null(bio_variables)) {
     bio_variables <- getOption("pastclim.dataset_list")[getOption("pastclim.dataset_list")$dataset == dataset, ]
     if (!monthly) {
@@ -55,13 +55,6 @@ download_dataset <- function(dataset, bio_variables = NULL, annual = TRUE,
     )
   }
 
-  # if (dataset %in% c("Krapp2021", "Beyer2020", "Example")){
-  #   # add biome to list of variables (we need it to generate the landmask)
-  #   if (!"biome" %in% bio_variables) {
-  #     bio_variables <- c(bio_variables, "biome")
-  #   }
-  # }
-
   # add biome to list of variables (we need it to generate the landmask)
   if (all((!"biome" %in% bio_variables), ("biome" %in% available_variables))) {
     bio_variables <- c(bio_variables, "biome")

R/download_etopo.R

@@ -5,7 +5,7 @@
 #'
 #' @param path	character. Path where to download the data to. If left NULL, the data
 #' will be downloaded from the directory returned by [get_data_path()], and automatically
-#' named "etopo2022_{resolution}s_v1.nc"
+#' named `etopo2022_{resolution}s_v1.nc`
 #' @param resolution numeric resolution in arcsecs (one of 30, or 60).
 #' Defaults to 60 arcsecs.
 #' @returns a dataframe produced by [curl::multi_download()] with information about

R/get_ice_mask.R

@@ -33,6 +33,18 @@ get_ice_mask <- function(time_bp = NULL, dataset) {
     ice_mask <- climate_series["biome"]
     ice_mask[ice_mask != 28] <- NA
     ice_mask[ice_mask == 28] <- 1
+    # sort out categories
+      # we pass a list so that each level if turned into a categorical variable
+      levels(ice_mask) <-
+        rep(list(data.frame(id=1, category= c("ice"))),
+            terra::nlyr(ice_mask))
+      terra::coltab(ice_mask) <- rep (list(
+        data.frame(
+          values = c(1),
+          cols = c("#B5D1E0")
+        )
+      ), terra::nlyr(ice_mask))
+
     names(ice_mask) <- paste("ice_mask", time_bp(ice_mask), sep = "_")
     varnames(ice_mask) <- "ice_mask"
     return(ice_mask)