pastclim: Manipulate Time Series of Climate Reconstructions

Description

Methods to easily extract and manipulate climate reconstructions for ecological and anthropological analyses, as described in Leonardi et al. (2023) doi:10.1111/ecog.06481. The package includes datasets of palaeoclimate reconstructions, present observations, and future projections from multiple climate models.

Author(s)

Maintainer: Andrea Manica am315@cam.ac.uk

Authors:

• Michela Leonardi

Other contributors:

• Emily Y. Hallet [contributor]

• Robert Beyer [contributor]

• Mario Krapp [contributor]

• Andrea V. Pozzi [contributor]

See Also

Useful links:

• https://github.com/EvolEcolGroup/pastclim

• https://evolecolgroup.github.io/pastclim/

• Report bugs at https://github.com/EvolEcolGroup/pastclim/issues

Coefficient of variation (expressed as percentage)

Description

R function to compute the coefficient of variation (expressed as a percentage). If there is only a single value, stats::sd = NA. However, one could argue that cv =0; and NA may break the code that receives it. The function returns 0 if the mean is close to zero.

Usage

.cv(x)

Arguments

Value

the cv

Documentation for the Barreto et al 2023 dataset

Description

Spatio-temporal series of monthly temperature and precipitation and 17 derived bioclimatic variables covering the last 5 Ma (Pliocene–Pleistocene), at intervals of 1,000 years, and a spatial resolution of 1 arc-degrees (see Barreto et al., 2023 for details).

Details

PALEO-PGEM-Series is downscaled to 1 × 1 arc-degrees spatial resolution from the outputs of the PALEO-PGEM emulator (Holden et al., 2019), which emulates reasonable and extensively validated global estimates of monthly temperature and precipitation for the Plio-Pleistocene every 1 kyr at a spatial resolution of ~5 × 5 arc-degrees (Holden et al., 2016, 2019).

PALEO-PGEM-Series includes the mean and the standard deviation (i.e., standard error) of the emulated climate over 10 stochastic GCM emulations to accommodate aspects of model uncertainty. This allows users to estimate the robustness of their results in the face of the stochastic aspects of the emulations. For more details, see Section 2.4 in Barreto et al. (2023).

Note that this is a very large dataset, with 5001 time slices. It takes approximately 1 minute to set up each variable when creating a region_slice or region_series. However, once the object has been created, other operations tend to be much faster (especially if you subset the dataset to a small number of time steps of interest).

IMPORTANT: If you use this dataset, make sure to cite the original publications:

Barreto, E., Holden, P. B., Edwards, N. R., & Rangel, T. F. (2023). 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: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:10.5194/gmd-12-5137-2019.

Documentation for the Beyer2020 dataset

Description

This dataset covers the last 120k years, at intervals of 1/2 k years, and a resolution of 0.5 degrees in latitude and longitude.

Details

IMPORTANT: If you use this dataset, make sure to cite the original publication:

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: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:

https://www.marineregions.org/gazetteer.php?p=details&id=4278

https://www.marineregions.org/gazetteer.php?p=details&id=4282

As there is no reconstruction of their depth through time, modern outlines were used for all time steps.

Also, for bio15, the coefficient of variation was computed after adding one to monthly estimates, and it was multiplied by 100 following https://pubs.usgs.gov/ds/691/ds691.pdf

Changelog

v1.1.0 Added monthly variables. Files can be downloaded from: https://zenodo.org/deposit/7062281

v1.0.0 Remove ice sheets and internal seas, and use correct formula for bio15. Files can be downloaded from: doi:10.6084/m9.figshare.19723405.v1

Documentation for CHELSA 2.1

Description

CHELSA version 2.1 is a database of high spatial resolution global weather and climate data, covering both the present and future projections.

Details

IMPORTANT: If you use this dataset, make sure to cite the original publication for the CHELSA dataset:

Karger, D.N., Conrad, O., Böhner, J., Kawohl, T., Kreft, H., Soria-Auza, R.W., Zimmermann, N.E., Linder, P., Kessler, M. (2017) Climatologies at high resolution for the Earth land surface areas. Scientific Data. 4 170122. doi:10.1038/sdata.2017.122

Present-day reconstructions are based on the mean for the period 1981-2000 and are available at at the high resolution of 0.5 arc-minutes (CHELSA_2.1_0.5m). In pastclim, the datasets are given a date of 1990 CE (the mid-point of the period of interest). There are 19 “bioclimatic” variables, as well as monthly estimates for mean temperature, and precipitation. The dataset is very large, as it includes estimates for the oceans as well as the land masses. An alternative to downloading the very large files is to use virtual rasters, which allow the data to remain on the server, with only the pixels required for a given operation being downloaded. Virtual rasters can be used by choosing (CHELSA_2.1_0.5m_vsi)

Future projections are based on the models in CMIP6, downscaled and de-biased using the CHELSA algorithm 2.1. Monthly values of mean temperature, and total precipitation, as well as 19 bioclimatic variables were processed for 5 global climate models (GCMs), and for three Shared Socio-economic Pathways (SSPs): 126, 370 and 585. Model and SSP can be chosen by changing the ending of the dataset name CHELSA_2.1_GCM_SSP_RESm.

Available values for GCM are: "GFDL-ESM4", "IPSL-CM6A-LR", "MPI-ESM1-2-HR", "MRI-ESM2-0", and "UKESM1-0-LL". For SSP, use: "ssp126", "ssp370", and "ssp585". RES is currently limited to "0.5m". Example dataset names are CHELSA_2.1_GFDL-ESM4_ssp126_0.5m and CHELSA_2.1_UKESM1-0-LL_ssp370_0.5m

As for present reconstructions, an alternative to downloading the very large files is to use virtual rasters. Simply append "_vis" to the name of the dataset of interest (CHELSA_2.1_GFDL-ESM4_ssp126_0.5m_vsi).

The dataset are averages over 30 year periods (2011-2040, 2041-2070, 2071-2100). In pastclim, the midpoints of the periods (2025, 2055, 2075) are used as the time stamps. All 3 periods are automatically downloaded for each combination of GCM model and SSP, and are selected as usual by defining the time in functions such as region_slice().

Documentation for CHELSA-TracCE21k

Description

CHELSA-TraCE21k data provides monthly climate data for temperature and precipitation at 30 arc-sec spatial resolution in 100-year time steps for the last 21,000 years. Palaeo-orography at high spatial resolution and at each time step is created by combining high resolution information on glacial cover from current and Last Glacial Maximum (LGM) glacier databases with the interpolation of a dynamic ice sheet model (ICE6G) and a coupling to mean annual temperatures from CCSM3-TraCE21k. Based on the reconstructed palaeo-orography, mean annual temperature and precipitation was downscaled using the CHELSA V1.2 algorithm.

Details

More details on the dataset are available on its dedicated website.

An alternative to downloading very large files is to use virtual rasters. Simply append "_vis" to the name of the dataset of interest (CHELSA_trace21k_1.0_0.5m_vsi). This is the recommended approach, and it is currently the only available version of the dataset.

IMPORTANT: If you use this dataset, make sure to cite the original publication:

Karger, D.N., Nobis, M.P., Normand, S., Graham, C.H., Zimmermann, N. (2023) CHELSA-TraCE21k – High resolution (1 km) downscaled transient temperature and precipitation data since the Last Glacial Maximum. Climate of the Past. doi:10.5194/cp-2021-30

Documentation for the Example dataset

Description

This dataset is a subset of Beyer2020, used for the vignette of pastclim. Do not use this dataset for any real work, as it might not reflect the most up-to-date version of Beyer2020.

Documentation for HYDE 3.3 dataset

Description

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.

Details

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

More details on the dataset are available on its dedicated website.

IMPORTANT: 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-927-2017

Documentation for the Krapp2021 dataset

Description

This dataset covers the last 800k years, at intervals of 1k years, and a resolution of 0.5 degrees in latitude and longitude.

Details

The units of several variables have been changed to match what is used in WorldClim.

IMPORTANT: If you use this dataset, make sure to cite the original publication:

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:10.1038/s41597-021-01009-3

The version included in pastclim has the ice sheets masked.

Note that, for bio15, we use the corrected version, which follows https://pubs.usgs.gov/ds/691/ds691.pdf

Changelog

v1.4.0 Change units to match WorldClim. Fix variable duplication found on earlier versions of the dataset. https://zenodo.org/records/8415273

v1.1.0 Added monthly variables. Files can be downloaded from: https://zenodo.org/record/7065055

v1.0.0 Remove ice sheets and use correct formula for bio15. Files can be downloaded from: doi:10.6084/m9.figshare.19733680.v1

Documentation for the WorldClim datasets

Description

WorldClim version 2.1 is a database of high spatial resolution global weather and climate data, covering both the present and future projections.

Details

IMPORTANT: If you use this dataset, make sure to cite the original publication:

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:10.1002/joc.5086

Present-day reconstructions are based on the mean for the period 1970-2000, and are available at multiple resolutions of 10 arc-minutes, 5 arc-minutes, 2.5 arc-minute and 0.5 arc-minutes. The resolution of interest can be obtained by changing the ending of the dataset name WorldClim_2.1_RESm, e.g. WorldClim_2.1_10m or WorldClim_2.1_5m (currently, only 10m and 5m are currently available in pastclim). In pastclim, the datasets are given a date of 1985 CE (the mid-point of the period of interest). There are 19 “bioclimatic” variables, as well as monthly estimates for minimum, mean, and maximum temperature, and precipitation.

Future projections are based on the models in CMIP6, downscaled and de-biased using WorldClim 2.1 for the present as a baseline. Monthly values of minimum temperature, maximum temperature, and precipitation, as well as 19 bioclimatic variables were processed for 23 global climate models (GCMs), and for four Shared Socio-economic Pathways (SSPs): 126, 245, 370 and 585. Model and SSP can be chosen by changing the ending of the dataset name WorldClim_2.1_GCM_SSP_RESm.

Available values for GCM are: "ACCESS-CM2", "BCC-CSM2-MR", "CMCC-ESM2", "EC-Earth3-Veg", "FIO-ESM-2-0", "GFDL-ESM4", "GISS-E2-1-G", "HadGEM3-GC31-LL", "INM-CM5-0", "IPSL-CM6A-LR", "MIROC6", "MPI-ESM1-2-HR", "MRI-ESM2-0", and "UKESM1-0-LL". For SSP, use: "ssp126", "ssp245", "ssp370", and "ssp585". RES takes the same values as for present reconstructions (i.e. "10m", "5m", "2.5m", and "0.5m"). Example dataset names are WorldClim_2.1_ACCESS-CM2_ssp245_10m and WorldClim_2.1_MRI-ESM2-0_ssp370_5m. Four combination (namely FIO-ESM-2-0_ssp370, GFDL-ESM4_ssp245, GFDL-ESM4_ssp585, and HadGEM3-GC31-LL_ssp370) are NOT available.

The dataset are averages over 20 year periods (2021-2040, 2041-2060, 2061-2080, 2081-2100). In pastclim, the midpoints of the periods (2030, 2050, 2070, 2090) are used as the time stamps. All 4 periods are automatically downloaded for each combination of GCM model and SSP, and are selected as usual by defining the time in functions such as region_slice().

Cast bathy to SpatRaster

Description

This function converts a marmap::bathy object to a terra::SpatRaster.

Usage

bathy_to_spatraster(bathy)

Arguments

Value

a terra::SpatRaster with the relief for the chosen region

Compute bioclimatic variables

Description

Function to compute "bioclimatic" variables from monthly average temperature and precipitation data. For modern data, this variables are generally computed using min and maximum temperature, but for many palaeoclimatic reconstructions only average temperature is available. Most variables, with the exception of BIO02 and BIO03, can be rephrased meaningfully in terms of mean temperature. This function is a modified version of predicts::bcvars.

Usage

bioclim_vars(prec, tavg, ...)

## S4 method for signature 'numeric,numeric'
bioclim_vars(prec, tavg)

## S4 method for signature 'SpatRaster,SpatRaster'
bioclim_vars(prec, tavg, filename = "", ...)

## S4 method for signature 'SpatRasterDataset,SpatRasterDataset'
bioclim_vars(prec, tavg, filename = "", ...)

## S4 method for signature 'matrix,matrix'
bioclim_vars(prec, tavg)

Arguments

Details

The variables are:

• BIO01 = Annual Mean Temperature

• BIO04 = Temperature Seasonality (standard deviation x 100)

• BIO05 = Max Temperature of Warmest Month

• BIO06 = Min Temperature of Coldest Month

• BIO07 = Temperature Annual Range (P5-P6)

• BIO08 = Mean Temperature of Wettest Quarter

• BIO09 = Mean Temperature of Driest Quarter

• BIO10 = Mean Temperature of Warmest Quarter

• BIO11 = Mean Temperature of Coldest Quarter

• BIO12 = Annual Precipitation

• BIO13 = Precipitation of Wettest Month

• BIO14 = Precipitation of Driest Month

• BIO15 = Precipitation Seasonality (Coefficient of Variation)

• BIO16 = Precipitation of Wettest Quarter

• BIO17 = Precipitation of Driest Quarter

• BIO18 = Precipitation of Warmest Quarter

• BIO19 = Precipitation of Coldest Quarter

These summary Bioclimatic variables are after:

Nix, 1986. A biogeographic analysis of Australian elapid snakes. In: R. Longmore (ed.). Atlas of elapid snakes of Australia. Australian Flora and Fauna Series 7. Australian Government Publishing Service, Canberra.

and expanded following the ANUCLIM manual

Value

the bioclim variables

BIOME4 classes.

Description

A data.frame defining the details of each class

Usage

biome4_classes

Format

A data.frame with multiple columns to describe.

Check if dataset is available.

Description

Internal getter function

Usage

check_available_dataset(dataset, include_custom = FALSE)

Arguments

Value

TRUE if the dataset is available

Check if var is available for this dataset.

Description

Internal getter function

Usage

check_available_variable(variable, dataset)

Arguments

Value

TRUE if var is available

Check that we have a valid pair of coordinate names

Description

This internal function checks that coords (as passed to functions) is a valid set of names, or, if NULL, that we have standard variable names in data

Usage

check_coords_names(data, coords)

Arguments

Value

A vector of length 2 with the valid names, in the correct order

Check dataset and path_to_nc params

Description

Check that the dataset and path_to_nc parameters are valid. Specifically, if path_to_nc should only be set if dataset is custom (and conversely, custom datasets require a path_to_nc).

Usage

check_dataset_path(dataset, path_to_nc)

Arguments

Value

TRUE if both dataset and path are valid.

Check multiple time variables

Description

Check that we only have one set of times

Usage

check_time_vars(time_bp, time_ce, allow_null = TRUE)

Arguments

Value

times in bp

Internal function to check whether we have downloaded a given variable for a dataset

Description

Internal function to check whether we have downloaded a given variable for a dataset

Usage

check_var_downloaded(variable, dataset)

Arguments

Value

TRUE if the variable has been downloaded.

Check whether variables exist in a netcdf file

Description

Internal function to test a custom nc file.

Usage

check_var_in_nc(bio_variables, path_to_nc)

Arguments

Value

TRUE if the variable exists

Clean the data path

Description

This function deletes old reconstructions that have been superseded in the data_path. It assumes that the only files in data_path are part of pastclim (i.e. there are no custom datasets stored in that directory).

Usage

clean_data_path(ask = TRUE)

Arguments

Value

TRUE if files are deleted successfully

Extract local climate for one or more locations for a given time slice.

Description

Deprecated version of location_slice()

Usage

climate_for_locations(...)

Arguments

Value

a data.frame with the climatic variables of interest

Extract a climate slice for a region

Description

Deprecated version of region_slice()]

Usage

climate_for_time_slice(...)

Arguments

Value

a SpatRaster terra::SpatRaster object, with each variable as a layer.

Internal function to copy the example dataset when a new data path is set

Description

Copy example dataset

Usage

copy_example_data()

Value

TRUE if the data were copied successfully

Compute a delta raster.

Description

This function generates a delta (difference) raster, computed as the difference between model estimates (x) and some observations (high_res_obs). x is a terra::SpatRaster of the variable we want to downscale, and it can contain multiple time steps. ref_time sets the time slice for which the delta should be computed.

Usage

delta_compute(x, ref_time, obs, max_land = NULL)

Arguments

Details

If obs has a higher resolution than x, the latter is interpolated using a bilinear algorithm. For areas that are present in some time slices, but not in the observations (e.g. due to sea level change), the delta map is extended to cover the maximum cumulative land mask (over all time steps) using inverse distance weighted interpolation.

Value

a terra::SpatRaster of the delta

Downscale using the delta method

Description

The delta method computes the difference between an observed raster and the equivalent predictions from a model for a given time step, and then applies that difference (delta) to all other time steps. You will first need to create the delta raster with delta_compute(), and thus use it as an argument for this function.

Usage

delta_downscale(
  x,
  delta_rast,
  x_landmask_high = NULL,
  range_limits = NULL,
  nmax = 7,
  set = list(idp = 0.5),
  ...
)

Arguments

Details

It is possible to also provide a high resolution landmask to this function. For cells which are not included in the original simulation (e.g. because the landmask was discretised at lower resolution), an inverse distance weighted algorithm (as implemented in gstat::gstat()) is used to interpolate the missing values. See the manpage for gstat::gstat() for more parameters that can change the behaviour of the iwd interpolation.

Value

a terra::SpatRaster of the downscaled variable, where each layers is a time step.

Extract data frame from a region series

Description

Extract the climatic information from a region series and organise them as a data frame.

Usage

df_from_region_series(x, xy = TRUE)

Arguments

Details

To extract a data frame from a region slice, see df_from_region_slice().

Value

a data.frame where each cell each raster layer (i.e. timestep) is a row, and the available variables are columns.

Extract data frame from a region slice

Description

Extract the climatic information from a region slice and organise it as a data frame. This is just a wrapper around terra::as.data.frame().

Usage

df_from_region_slice(x, xy = TRUE)

Arguments

Details

To extract a data frame from a region series, see df_from_region_series().

Value

a data.frame where each cell the raster is a row, and the available variables are columns.

Compute a raster of distances from the sea for each land pixel.

Description

Get the land mask for a dataset at a given time point, and compute distance from the sea for each land pixel.

Usage

distance_from_sea(time_bp = NULL, time_ce = NULL, dataset)

Arguments

Value

a terra::SpatRaster of distances from the coastline in km

Download the CHELSA modern and future observations.

Description

This function downloads annual and monthly variables from the CHELSA v2.1 dataset.

Usage

download_chelsa(dataset, bio_var, filename)

Arguments

Value

TRUE if the requested CHELSA variable was downloaded successfully

Download the CHELSA trace21k

Description

This function downloads annual and monthly variables from the CHELSA trace v1.0 dataset.

Usage

download_chelsa_trace21k(dataset, bio_var, filename = NULL, time_bp = NULL)

Arguments

Details

As this dataset is huge, we should not download all files in most situations. For this reason, time_bp has to be set for downloading (but it is allowed for virtual datasets)

Value

TRUE if the requested CHELSA variable was downloaded successfully

Download palaeoclimate reconstructions.

Description

This function downloads palaeoclimate reconstructions. Files will be stored in the data path of pastclim, which can be inspected with get_data_path() and changed with set_data_path()

Usage

download_dataset(dataset, bio_variables = NULL, annual = TRUE, monthly = FALSE)

Arguments

Value

TRUE if the dataset(s) was downloaded correctly.

Download the ETOPO Global relief model

Description

This function downloads the ETOPO2022 global relief model at 0.5 or 1 arc-minute (i.e. 30 or 60 arc-seconds) resolution. This is a large file (>1Gb).

Usage

download_etopo(path = NULL, resolution = 1, force = FALSE)

Arguments

Value

a dataframe produced by curl::multi_download() with information about the download (including error codes)

Download part of the ETOPO relief dataset.

Description

This function downloads part of the ETOPO2020 relief (topography+bathymetry) dataset.

Usage

download_etopo_subset(rast_template, ...)

Arguments

Details

Use this function if you only need part of the dataset, or you need a relatively low resolution. This function fetches the necessary subset on the fly from the NOAA server. If you plan to use the ETOPO2022 dataset extensively, it is worthwhile downloading it permanently to your computer with download_etopo(), but beware that it is a large file (>1Gb). This function uses marmap::getNOAA.bathy() to download the data, and then converts them into a terra::SpatRaster formatted to be compatible with pastclim. NOTE: this function does not save the relief, it returns a terra::SpatRaster. If you plan to reuse this relief multiple times, it would be wise to save it with terra::writeCDF().

Value

a terra::SpatRaster with the relief for the chosen region

Download the paleoclim time series.

Description

This function downloads annual and monthly variables from the Paleoclim V1.0 dataset.

Usage

download_paleoclim(dataset, bio_var, filename = NULL)

Arguments

Value

TRUE if the requested paleoclim variable was downloaded successfully

Download the worldclim future time series.

Description

This function downloads annual and monthly variables from the WorldClim v2.1 dataset for future projections.

Usage

download_worldclim_future(dataset, bio_var, filename = NULL)

Arguments

Details

Note: the data come as tiffs each containing all bio (or prec/temp) variables for a given time step. From these, we generate a vrt per variable. So, since we download the full set for a give variable type, we create all the vrts for that variable type (e.g. all the bio). We use the filename to get the version name, and then at the end to check that we did generate it correctly given our programmatic way of creating the names of all vrt files.

Value

TRUE if the requested worldclim variable was downloaded successfully

Download a WorldClim modern observations.

Description

This function downloads annual and monthly variables from the WorldClim 2.1 dataset.

Usage

download_worldclim_present(dataset, bio_var, filename)

Arguments

Value

TRUE if the requested WorldClim variable was downloaded successfully

Downscale an ice mask

Description

Downscaling the ice mask presents some issues. The mask is a binary raster, so any standard downscaling approach will still look very blocky. We can smooth the contour by applying a Gaussian filter. How strong that filter should be is very much a matter of personal opinion, as we do not have any data to compare to. This function attempts to use a sensible default value, but it is worth exploring alternative values to find a good solution.

Usage

downscale_ice_mask(
  ice_mask_low_res,
  land_mask_high_res,
  d = c(0.5, 3),
  expand_xy = c(5, 5)
)

Arguments

Details

The Guassian filter can lead to edge effects. To minimise such effects, this function initially crops the ice mask to an extent that is larger than land_mask_high_res, as defined by expand_xy. After applying the Gaussian filter, the resulting raster is then cropped to the exact size of land_mask_high_res.

Value

a terra::SpatRaster of the ice mask (1's), with the rest of the world (sea and land) as NA's

Generate file names to download the chelsa future dataset

Description

This function creates a vector of paths needed to download the CHELSA future dataset

Usage

filenames_chelsa_future(dataset, bio_var)

Arguments

Value

a vector of times, one per band

Generate file names to download the chelsa present dataset

Description

This function creates a vector of paths needed to download the CHELSA present dataset

Usage

filenames_chelsa_present(dataset, bio_var)

Arguments

Value

a vector of times, one per band

Generate file names to download the chelsa trace 21k

Description

This function creates a vector of paths needed to download the CHELSA trace21k

Usage

filenames_chelsa_trace21k(dataset, bio_var)

Arguments

Value

a vector of times, one per band

Generate file names to download the chelsa present dataset

Description

This function creates a vector of paths needed to download the CHELSA present dataset. Possible names are "paleoclim_1.0_10m", "paleoclim_1.0_5m", "paleoclim_1.0_2.5m"

Usage

filenames_paleoclim(dataset, bio_var)

Arguments

Value

a vector of times, one per band

Generate file names to download the WorldClim present dataset

Description

This function creates a vector of paths needed to download the WorldClim present dataset

Usage

filenames_worldclim_future(dataset, bio_var)

Arguments

Value

a vector of times, one per band

Generate file names to download the WorldClim present dataset

Description

This function creates a vector of paths needed to download the WorldClim present dataset

Usage

filenames_worldclim_present(dataset, bio_var)

Arguments

Value

a vector of times, one per band

Get the available datasets.

Description

List the datasets available in pastclim, which can be passed to functions in pastclim as values for the parameter dataset. Most functions can also be used on custom datasets by setting dataset="custom"

Usage

get_available_datasets()

Details

This function provides a user-friendly list, summarising the many datasets available from WorldClim. A comprehensive list of all available datasets can be obtained with list_available_datasets.

Value

a character vector of the available datasets

Get the biome classes for a dataset.

Description

Get a full list of biomes and how their id as coded in the biome variable for a given dataset.

Usage

get_biome_classes(dataset)

Arguments

Value

a data.frame with columns id and category.

Get the data path where climate reconstructions are stored

Description

This function returns the path where climate reconstructions are stored.

Usage

get_data_path(silent = FALSE)

Arguments

Details

The path is stored in an option for pastclim named data_path. If a configuration file was saved when using 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).

Value

the data path

Get the information about a dataset

Description

This function provides full information about a given dataset. A full list of datasets available in pastclim can be obtained with list_available_datasets()

Usage

get_dataset_info(dataset)

Arguments

Value

text describing the dataset

Get the variables downloaded for each dataset.

Description

List the downloaded variable for each dataset.

Usage

get_downloaded_datasets(data_path = NULL)

Arguments

Value

a list of variable names per dataset.

Get the ice mask for a dataset.

Description

Get the ice mask for a dataset, either for the whole series or for specific time points.

Usage

get_ice_mask(time_bp = NULL, dataset)

Arguments

Details

Note that not all datasets have ice information.

Value

a binary terra::SpatRaster with the ice mask as 1s

Get the land mask for a dataset.

Description

Get the land mask for a dataset, either for the whole series or for specific time points.

Usage

get_land_mask(time_bp = NULL, time_ce = NULL, dataset)

Arguments

Value

a binary terra::SpatRaster with the land mask as 1s

Get time steps for a given MIS

Description

Get the time steps available in a given dataset for a MIS.

Usage

get_mis_time_steps(mis, dataset, path_to_nc = NULL)

Arguments

Value

a vector of time steps

Get resolution of a given dataset

Description

Get the resolution of a given dataset.

Usage

get_resolution(dataset, path_to_nc = NULL)

Arguments

Value

a vector of resolution in the x and y axes

Get sea level estimate

Description

This function returns the estimated sea level from Spratt et al. 2016, using the long PC1. Sea levels are from contemporary sea level (note that the original data are with reference to the sea level during the Holocene ~5k year ago).

Usage

get_sea_level(time_bp)

Arguments

Value

a vector of sea levels in meters from present level

Get time steps for a given dataset

Description

Get the time steps (in time_bp or time_ce) available in a given dataset.

Usage

get_time_bp_steps(dataset, path_to_nc = NULL)

get_time_ce_steps(dataset, path_to_nc = NULL)

get_time_steps(dataset, path_to_nc = NULL)

Arguments

Value

a vector of time steps (in time_bp, or time_ce)

Get the metadata for a variable in a given dataset.

Description

Internal getter function

Usage

get_var_meta(variable, dataset)

Arguments

Value

the metadata (including filename) for that variable in that dataset

Get a the varname for this variable

Description

Internal function to get the varname for this variable

Usage

get_varname(variable, dataset)

Arguments

Value

the name of the variable

Get a list of variables for a given dataset.

Description

This function lists the variables available for a given dataset. Note that the spelling and use of capitals in names might differ from the original publications, as pastclim harmonises the names of variables across different reconstructions.

Usage

get_vars_for_dataset(
  dataset,
  path_to_nc = NULL,
  details = FALSE,
  annual = TRUE,
  monthly = FALSE
)

Arguments

Value

a vector of variable names

Print help to console

Description

This function prints a help file to console. It is based on a function published on R-bloggers: from https://www.r-bloggers.com/2013/06/printing-r-help-files-in-the-console-or-in-knitr-documents/

Usage

help_console(
  topic,
  format = c("text", "html", "latex"),
  lines = NULL,
  before = NULL,
  after = NULL
)

Arguments

Value

text of the help file

Interpolate x to match mask y

Description

Fill in x to match cells available in y, using inverse distance weighted interpolation. Interpolation is fitted using gstat::gstat(); the default parameters for gstat::gstat() are "nmax=7" and "idp=.5", but can be changed by providing arguments to this function (which will be passed to gstat::gstat()). See gstat::gstat() for details on the available parameters and their meaning.

Usage

idw_interp(x, y, nmax = 7, set = list(idp = 0.5), ...)

Arguments

Value

a terra::SpatRaster of the interpolated version of x

Check the object is a valid region series

Description

A region series is a terra::SpatRasterDataset for which each sub-dataset is a variable, and all variables have the same number of time steps.

Usage

is_region_series(x, strict = FALSE)

Arguments

Details

The standard test only checks that all sub-datasets (each of which is a terra::SpatRaster) have the same number of layers. The more thorough test (obtained with strict=TRUE) actually checks that all variables have the same identical time steps by comparing the result of terra::time() applied to each variable.

Value

TRUE if the object is a region series

Koeppen-Geiger classes.

Description

A data.frame defining the details of each class

Usage

koeppen_classes

Format

A data.frame with multiple columns to describe.

Reconstruct biomes based on the Köppen Geiger's classification

Description

Function to reconstruct biomes following the Köppen Geiger's classification, as implemented in Beck et al (2018). This function is a translation of the Matlab function "KoeppenGeiger" provided in that publication. See Table 1 in beck et al (2018) for the rules implemented in this function.

Usage

koeppen_geiger(prec, tavg, broad = FALSE, class_names = TRUE, ...)

## S4 method for signature 'matrix,matrix'
koeppen_geiger(prec, tavg, broad = FALSE, class_names = TRUE)

## S4 method for signature 'SpatRaster,SpatRaster'
koeppen_geiger(
  prec,
  tavg,
  broad = FALSE,
  class_names = TRUE,
  filename = "",
  ...
)

## S4 method for signature 'SpatRasterDataset,SpatRasterDataset'
koeppen_geiger(
  prec,
  tavg,
  broad = FALSE,
  class_names = TRUE,
  filename = "",
  ...
)

Arguments

Details

Beck, H.E., McVicar, T.R., Vergopolan, N. et al. High-resolution (1 km) Köppen-Geiger maps for 1901–2099 based on constrained CMIP6 projections. Sci Data 10, 724 (2023). https://doi.org/10.1038/s41597-023-02549-6

Value

a data.frame with the Köppen Geiger classification

Examples

prec <- matrix(
  c(
    66, 51, 53, 53, 33, 34.2, 70.9, 58, 54, 104.3, 81.2, 82.8, 113.3,
    97.4, 89, 109.7, 89, 93.4, 99.8, 92.6, 85.3, 102.3, 84, 81.6, 108.6,
    88.4, 82.7, 140.1, 120.4, 111.6, 120.4, 113.9, 96.7, 90, 77.4, 79.1
  ),
  ncol = 12, byrow = TRUE
)
tavg <- matrix(
  c(
    -0.2, 1.7, 2.9, 0.3, 4.2, 5, 4, 9, 9.2, 7.3, 12.6, 12.7, 12.1,
    17.2, 17, 15.5, 20.5, 20.3, 17.9, 22.8, 22.9, 17.4, 22.3, 22.4, 13.2,
    18.2, 18.6, 8.8, 13, 13.6, 3.5, 6.4, 7.5, 0.3, 2.1, 3.4
  ),
  ncol = 12, byrow = TRUE
)
koeppen_geiger(prec, tavg, broad = TRUE)

List all the available datasets.

Description

List the datasets available in pastclim. The list is comprehensive, and includes all combinations of models and future scenarios for WorldClim. For a more user-friendly list, use get_available_datasets(). Most functions can also be used on custom datasets by setting dataset="custom"

Usage

list_available_datasets()

Value

a character vector of the available datasets

Load the dataset list

Description

This function returns a dataframe with the details for each variable available in every dataset. It defaults to the copy stored within the package, but it checks in case there is an updated version stored as 'dataset_list_included.csv' in tools::R_user_dir("pastclim","config"). If the latter is present, the last column, named 'dataset_list_v', provides the version of this table, and the most advanced table is used.

Usage

load_dataset_list(on_cran = FALSE)

Arguments

Value

the dataset list

Load the ETOPO global relief

Description

This function loads previously downloaded ETOPO 2022 global relief dataset, at 0.5 or 1 arc-minute (i.e. 30 or 60 arc-seconds) resolution. The function assumes that the file name is ⁠etopo2022_{resolution}m_v1.nc⁠ To save the file in the default path with an appropriate name and file format, simply use download_etopo().

Usage

load_etopo(path = NULL, resolution = 1, version = "1")

Arguments

Value

a terra::SpatRaster of relief

Extract a time series of bioclimatic variables for one or more locations.

Description

This function extract a time series of local climate for a set of locations. Note that this function does not apply any interpolation (as opposed to location_slice()). If you have a coastal location that just falls into the water for the reconstructions, you will have to amend the coordinates to put it more firmly on land.

Usage

location_series(
  x,
  time_bp = NULL,
  time_ce = NULL,
  coords = NULL,
  bio_variables,
  dataset,
  path_to_nc = NULL,
  nn_interpol = FALSE,
  buffer = FALSE,
  directions = 8
)

Arguments

Value

a data.frame with the climatic variables of interest

Extract local climate for one or more locations for a given time slice.

Description

This function extract local climate for a set of locations at the appropriate times (selecting the closest time slice available for the specific date associated with each location).

Usage

location_slice(
  x,
  time_bp = NULL,
  time_ce = NULL,
  coords = NULL,
  bio_variables,
  dataset,
  path_to_nc = NULL,
  nn_interpol = TRUE,
  buffer = FALSE,
  directions = 8
)

Arguments

Value

a data.frame with the climatic variables of interest.

Extract local climate for one or more locations for a given time slice.

Description

This function extract local climate for a set of locations at the appropriate times (selecting the closest time slice available for the specific date associated with each location).

Usage

location_slice_from_region_series(
  x,
  time_bp = NULL,
  time_ce = NULL,
  coords = NULL,
  region_series,
  nn_interpol = TRUE,
  buffer = FALSE,
  directions = 8
)

Arguments

Value

a data.frame with the climatic variables of interest.

Create a binary mask

Description

Create a binary mask from a raster: NAs are converted to 0s, and any other value to 1.

Usage

make_binary_mask(x)

Arguments

Value

a terra::SpatRaster with 0s and 1s

Create a land mask

Description

Create a land mask for a given time step. The land mask is based on the simple logic of moving the ocean up and down given the current relief profile ( topography+bathymetry, i.e. the elevation both above and below sea level). Note that this approach ignores any rebound due to changing mass and distribution of ice sheets. LIMITATIONS: The land mask will show internal lakes/seas as land, as their level is unrelated to the general sea level. If you have specific reconstructions of internal lakes (or want to simply reuse their current extents), you will have to add them onto the masks generated by this function. Also note that the land mask does not include ice sheets. This means that some areas that are permanently covered by ice at the two poles will show up as sea. This means that, for any reconstruction including Greenland or Antarctica, the resulting land mask will need to be modified to include the appropriate ice sheets.

Usage

make_land_mask(relief_rast, time_bp, sea_level = NULL)

Arguments

Value

a terra::SpatRaster of the land masks (with land as 1's and sea as NAs), where the layers are different times

Time boundaries of marine isotope stages (MIS).

Description

A dataset containing the beginning and end of MIS.

Usage

mis_boundaries

Format

A data frame with 24 rows and 2 variables:

mis

the stage, a string

start

the start of a given MIS, in kya

end

the start of a given MIS, in kya

Mode

Description

Find the mode of vector x (note that, if multiple values have the same frequency, this function simply picks the first occurring one)

Usage

mode(x)

Arguments

Value

the mode

Documentation for Paleoclim

Description

Paleoclim is a set of high resolution paleoclimate reconstructions, mostly based on the CESM model, downscaled with the CHELSA dataset to 3 different spatial resolutions: paleoclim_1.0_2.5m at 2.5 arc-minutes (~5 km), paleoclim_1.0_5m at 5 arc-minutes (~10 km), and paleoclim_1.0_10m 10 arc-minutes (~20 km). All 19 biovariables are available. There are only a limited number of time slices available for this dataset; furthermore, currently only time slices from present to 130ka are available in pastclim.

Details

More details on the dataset are available on its dedicated website.

IMPORTANT: If you use this dataset, make sure to cite the original publication:

Brown, Hill, Dolan, Carnaval, Haywood (2018) PaleoClim, high spatial resolution paleoclimate surfaces for global land areas. Nature – Scientific Data. 5:180254

Read a raster for pastclim

Description

This function is a wrapper around terra::rast(), with additional logic to correctly import time for vrt datasets (time is stored as custom metadata in pastclim-generated vrt files)

Usage

pastclim_rast(
  x,
  bio_var_orig,
  bio_var_pastclim,
  var_longname = NULL,
  var_units = NULL
)

Arguments

Value

a terra::SpatRaster

Region extents.

Description

A list of extents for major regions.

Usage

region_extent

Format

A list of vectors giving the extents.

Region outlines.

Description

An sf::sf object containing outlines for major regions. Outlines that span the antimeridian have been split into multiple polygons.

Usage

region_outline

Format

sf::sf of outlines.

name

names of regions

Region outlines unioned.

Description

An sf::sf object containing outlines for major regions. Each outline is represented as a single polygon. If you want multiple polygons, use region_outline.

Usage

region_outline_union

Format

sf::sf of outlines.

name

names of regions

Extract a time series of climate variables for a region

Description

This function extracts a time series of one or more climate variables for a given dataset covering a region (or the whole world). The function returns a terra::SpatRasterDataset object, with each variable as a sub-dataset.

Usage

region_series(
  time_bp = NULL,
  time_ce = NULL,
  bio_variables,
  dataset,
  path_to_nc = NULL,
  ext = NULL,
  crop = NULL
)

Arguments

Value

a terra::SpatRasterDataset object, with each variable as a sub-dataset.

Extract a climate slice for a region

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 SpatRaster terra::SpatRaster object, with each variable as a layer.

Usage

region_slice(
  time_bp = NULL,
  time_ce = NULL,
  bio_variables,
  dataset,
  path_to_nc = NULL,
  ext = NULL,
  crop = NULL
)

Arguments

Value

a SpatRaster terra::SpatRaster object, with each variable as a layer.

Sample points from a region time series

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 for size), or for different locations for each time step (if size is a vector of length equal to the number of time steps). To sample the same number of points, but different locations, for each time step, provide a vector repeating the same value for each time step.

Usage

sample_region_series(x, size, method = "random", replace = FALSE, na.rm = TRUE)

Arguments

Details

This function wraps terra::spatSample() to appropriate sample the terra::SpatRasters in the terra::SpatRasterDataset returned by region_series().

Value

a data.frame with the sampled cells and their respective values for the climate variables.

Sample points from a region time slice

Description

This function samples points from a region time slice (i.e. a time point).

Usage

sample_region_slice(x, size, method = "random", replace = FALSE, na.rm = TRUE)

Arguments

Details

This function wraps terra::spatSample() to appropriate sample the terra::SpatRaster returned by region_slice(). You can also use terra::spatSample() directly on a slice (which is a standard terra::SpatRaster).

Value

a data.frame with the sampled cells and their respective values for the climate variables.

Sample the same locations from a region time series

Description

Internal function for fixed sampling from sample_region_series(), used when a single size is given.

Usage

sample_rs_fixed(x, size, method = "random", replace = FALSE, na.rm = TRUE)

Arguments

Value

a data.frame with the sampled cells and their respective values for the climate variables.

Sample the different number of points from a region time series

Description

Internal function for sampling different number of points for each timestep of a region series from sample_region_series(), used when size is a vector of values.

Usage

sample_rs_variable(x, size, method = "random", replace = FALSE, na.rm = TRUE)

Arguments

Value

a data.frame with the sampled cells and their respective values for the climate variables.

Set the data path where climate reconstructions will be stored

Description

This function sets the path where climate reconstructions will be stored. This information is stored in a file names "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).

Usage

set_data_path(
  path_to_nc = NULL,
  ask = TRUE,
  write_config = TRUE,
  copy_example = TRUE,
  on_CRAN = FALSE
)

Arguments

Value

TRUE if the path was set correctly

Extract a slice for a time series of climate variables for a region

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

Usage

slice_region_series(x, time_bp = NULL, time_ce = NULL)

Arguments

Value

a terra::SpatRaster of the relevant slice.

Extract and set time in years before present for SpatRaster and SpatRasterDataset

Description

This functions extracts and sets time in years BP (i.e. from 1950) for a terra::SpatRaster or a terra::SpatRasterDataset. In a terra::SpatRaster object, time is stored with unit "years", which are years from 0AD. This means that, when a summary of the terra::SpatRaster is inspected, the times will appear as time_bp+1950. The same applies when the function terra::time() is used instead of time_bp().

Usage

time_bp(x)

## S4 method for signature 'SpatRaster'
time_bp(x)

## S4 method for signature 'SpatRasterDataset'
time_bp(x)

time_bp(x) <- value

## S4 replacement method for signature 'SpatRaster'
time_bp(x) <- value

## S4 replacement method for signature 'SpatRasterDataset'
time_bp(x) <- value

Arguments

Value

a date in years BP (where negative numbers indicate a date in the past)

Convert a time BP to indexes for a series

Description

Internal function

Usage

time_bp_to_i_series(time_bp, time_steps)

Arguments

Value

the indeces for the relevant time steps

Find the closest index to a given time in years BP

Description

Internal function

Usage

time_bp_to_index(time_bp, time_steps)

Arguments

Value

the indeces for the relevant time steps

Extract a time series of bioclimatic variables for one or more locations.

Description

Deprecated version of location_series()

Usage

time_series_for_locations(...)

Arguments

Value

a data.frame with the climatic variables of interest

Update the dataset list

Description

If a newer dataset list (which includes all the information about the files storing the data for pastclim), download it and start using it as 'dataset_list_included.csv' in tools::R_user_dir("pastclim","config"). If the latter is present, the last column, named 'dataset_list_v', provides the version of this table, and the most advanced table is used.

Usage

update_dataset_list(on_cran = FALSE)

Arguments

Value

TRUE if the dataset was updated

Test whether a URL is valid

Description

This function check that a URL points to a real file

Usage

url_is_valid(url, verbose = FALSE)

Arguments

Value

boolean on whether the file exists

Validate an netcdf file for pastclim

Description

This function validates a netcdf file as a potential dataset for pastclim. The key checks are: a) that the dimensions (longitude, latitude and time) have been set correctly. b) that all variables have the appropriate metadata (longname and units)

Usage

validate_nc(path_to_nc)

Arguments

Value

TRUE if the file is valid.

Generate pretty variable labels for plotting

Description

Generate pretty labels (in the form of an expression) that can be used for plotting

Usage

var_labels(x, dataset, with_units = TRUE, abbreviated = FALSE)

Arguments

Value

a expression that can be used as a label in plots

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(on_CRAN = TRUE)

# for a SpatRaster
climate_20k <- region_slice(
  time_bp = -20000,
  bio_variables = c("bio01", "bio10", "bio12"),
  dataset = "Example"
)
terra::plot(climate_20k, main = var_labels(climate_20k, dataset = "Example"))
terra::plot(climate_20k, main = var_labels(climate_20k,
  dataset = "Example",
  abbreviated = TRUE
))

Get metadata from vrt

Description

This function extract metadata information from a vrt. It returns the description for the whole dataset (needed to set the varname in the raster) and time information for each band. It first checks that the vrt dataset has a metadata element with key "pastclim_time_bp" set to TRUE. If that is the case, for each band, it extract the metadata with key "time" and returns them as numeric (i.e. converting them from character). Note that an error is returned if there are duplicated time elements for any of the bands (whilst duplicated elements are valid in the XML schema for VRT, they do not make sense for the time axis).

Usage

vrt_get_meta(vrt_path)

Arguments

Value

list of three elements: vector description and time_bp defining each band, and a boolean time_bp show determining whether times should be given as time_bp when labelling bands by terra.

Convert years BP from pastclim to lubridate date, or vice versa

Description

These functions convert between years BP as used by pastclim (negative numbers going into the past, positive into the future) and standard POSIXct date objects.

Usage

ybp2date(x)

date2ybp(x)

Arguments

Value

a POSIXct date object, or a vector

Examples

ybp2date(-10000)
ybp2date(0)
# back and forth
date2ybp(ybp2date(-10000))