# available datasets

## Overview of datasets available in `pastclim`

A number of datasets are available in pastclim. It is possible to use custom datasets as long as they are properly formatted (look at the article on how to format custom datasets if you are interested). It is possible to get a list of all available datasets with:

    library(pastclim)

    get_available_datasets()
    #> [1] "Example"           "Beyer2020"         "Krapp2021"
    #> [4] "Barreto2023"       "HYDE_3.3_baseline"
    #> for present day reconstructions, use "WorldClim_2.1_RESm", where RES is an available resolution.
    #> for future predictions, use "WorldClim_2.1_GCM_SSP_RESm", where GCM is the GCM model, SSP is the Shared Societ-economic Pathways scenario.
    #> use help("WorldClim_2.1") for a list of available options

A more comprehensive list can be obtained with:

    list_available_datasets()
    #>   [1] "Example"
    #>   [2] "Beyer2020"
    #>   [3] "Krapp2021"
    #>   [4] "Barreto2023"
    #>   [5] "WorldClim_2.1_10m"
    #>   [6] "WorldClim_2.1_5m"
    #>   [7] "WorldClim_2.1_ACCESS-CM2_ssp126_10m"
    #>   [8] "WorldClim_2.1_ACCESS-CM2_ssp126_5m"
    #>   [9] "WorldClim_2.1_ACCESS-CM2_ssp245_10m"
    #>  [10] "WorldClim_2.1_ACCESS-CM2_ssp245_5m"
    #>  [11] "WorldClim_2.1_ACCESS-CM2_ssp370_10m"
    #>  [12] "WorldClim_2.1_ACCESS-CM2_ssp370_5m"
    #>  [13] "WorldClim_2.1_ACCESS-CM2_ssp585_10m"
    #>  [14] "WorldClim_2.1_ACCESS-CM2_ssp585_5m"
    #>  [15] "WorldClim_2.1_BCC-CSM2-MR_ssp126_10m"
    #>  [16] "WorldClim_2.1_BCC-CSM2-MR_ssp126_5m"
    #>  [17] "WorldClim_2.1_BCC-CSM2-MR_ssp245_10m"
    #>  [18] "WorldClim_2.1_BCC-CSM2-MR_ssp245_5m"
    #>  [19] "WorldClim_2.1_BCC-CSM2-MR_ssp370_10m"
    #>  [20] "WorldClim_2.1_BCC-CSM2-MR_ssp370_5m"
    #>  [21] "WorldClim_2.1_BCC-CSM2-MR_ssp585_10m"
    #>  [22] "WorldClim_2.1_BCC-CSM2-MR_ssp585_5m"
    #>  [23] "WorldClim_2.1_CMCC-ESM2_ssp126_10m"
    #>  [24] "WorldClim_2.1_CMCC-ESM2_ssp126_5m"
    #>  [25] "WorldClim_2.1_CMCC-ESM2_ssp245_10m"
    #>  [26] "WorldClim_2.1_CMCC-ESM2_ssp245_5m"
    #>  [27] "WorldClim_2.1_CMCC-ESM2_ssp370_10m"
    #>  [28] "WorldClim_2.1_CMCC-ESM2_ssp370_5m"
    #>  [29] "WorldClim_2.1_CMCC-ESM2_ssp585_10m"
    #>  [30] "WorldClim_2.1_CMCC-ESM2_ssp585_5m"
    #>  [31] "WorldClim_2.1_EC-Earth3-Veg_ssp126_10m"
    #>  [32] "WorldClim_2.1_EC-Earth3-Veg_ssp126_5m"
    #>  [33] "WorldClim_2.1_EC-Earth3-Veg_ssp245_10m"
    #>  [34] "WorldClim_2.1_EC-Earth3-Veg_ssp245_5m"
    #>  [35] "WorldClim_2.1_EC-Earth3-Veg_ssp370_10m"
    #>  [36] "WorldClim_2.1_EC-Earth3-Veg_ssp370_5m"
    #>  [37] "WorldClim_2.1_EC-Earth3-Veg_ssp585_10m"
    #>  [38] "WorldClim_2.1_EC-Earth3-Veg_ssp585_5m"
    #>  [39] "WorldClim_2.1_FIO-ESM-2-0_ssp126_10m"
    #>  [40] "WorldClim_2.1_FIO-ESM-2-0_ssp126_5m"
    #>  [41] "WorldClim_2.1_FIO-ESM-2-0_ssp245_10m"
    #>  [42] "WorldClim_2.1_FIO-ESM-2-0_ssp245_5m"
    #>  [43] "WorldClim_2.1_FIO-ESM-2-0_ssp370_10m"
    #>  [44] "WorldClim_2.1_FIO-ESM-2-0_ssp370_5m"
    #>  [45] "WorldClim_2.1_FIO-ESM-2-0_ssp585_10m"
    #>  [46] "WorldClim_2.1_FIO-ESM-2-0_ssp585_5m"
    #>  [47] "WorldClim_2.1_GFDL-ESM4_ssp126_10m"
    #>  [48] "WorldClim_2.1_GFDL-ESM4_ssp126_5m"
    #>  [49] "WorldClim_2.1_GFDL-ESM4_ssp245_10m"
    #>  [50] "WorldClim_2.1_GFDL-ESM4_ssp245_5m"
    #>  [51] "WorldClim_2.1_GFDL-ESM4_ssp370_10m"
    #>  [52] "WorldClim_2.1_GFDL-ESM4_ssp370_5m"
    #>  [53] "WorldClim_2.1_GFDL-ESM4_ssp585_10m"
    #>  [54] "WorldClim_2.1_GFDL-ESM4_ssp585_5m"
    #>  [55] "WorldClim_2.1_GISS-E2-1-G_ssp126_10m"
    #>  [56] "WorldClim_2.1_GISS-E2-1-G_ssp126_5m"
    #>  [57] "WorldClim_2.1_GISS-E2-1-G_ssp245_10m"
    #>  [58] "WorldClim_2.1_GISS-E2-1-G_ssp245_5m"
    #>  [59] "WorldClim_2.1_GISS-E2-1-G_ssp370_10m"
    #>  [60] "WorldClim_2.1_GISS-E2-1-G_ssp370_5m"
    #>  [61] "WorldClim_2.1_GISS-E2-1-G_ssp585_10m"
    #>  [62] "WorldClim_2.1_GISS-E2-1-G_ssp585_5m"
    #>  [63] "WorldClim_2.1_HadGEM3-GC31-LL_ssp126_10m"
    #>  [64] "WorldClim_2.1_HadGEM3-GC31-LL_ssp126_5m"
    #>  [65] "WorldClim_2.1_HadGEM3-GC31-LL_ssp245_10m"
    #>  [66] "WorldClim_2.1_HadGEM3-GC31-LL_ssp245_5m"
    #>  [67] "WorldClim_2.1_HadGEM3-GC31-LL_ssp370_10m"
    #>  [68] "WorldClim_2.1_HadGEM3-GC31-LL_ssp370_5m"
    #>  [69] "WorldClim_2.1_HadGEM3-GC31-LL_ssp585_10m"
    #>  [70] "WorldClim_2.1_HadGEM3-GC31-LL_ssp585_5m"
    #>  [71] "WorldClim_2.1_INM-CM5-0_ssp126_10m"
    #>  [72] "WorldClim_2.1_INM-CM5-0_ssp126_5m"
    #>  [73] "WorldClim_2.1_INM-CM5-0_ssp245_10m"
    #>  [74] "WorldClim_2.1_INM-CM5-0_ssp245_5m"
    #>  [75] "WorldClim_2.1_INM-CM5-0_ssp370_10m"
    #>  [76] "WorldClim_2.1_INM-CM5-0_ssp370_5m"
    #>  [77] "WorldClim_2.1_INM-CM5-0_ssp585_10m"
    #>  [78] "WorldClim_2.1_INM-CM5-0_ssp585_5m"
    #>  [79] "WorldClim_2.1_IPSL-CM6A-LR_ssp126_10m"
    #>  [80] "WorldClim_2.1_IPSL-CM6A-LR_ssp126_5m"
    #>  [81] "WorldClim_2.1_IPSL-CM6A-LR_ssp245_10m"
    #>  [82] "WorldClim_2.1_IPSL-CM6A-LR_ssp245_5m"
    #>  [83] "WorldClim_2.1_IPSL-CM6A-LR_ssp370_10m"
    #>  [84] "WorldClim_2.1_IPSL-CM6A-LR_ssp370_5m"
    #>  [85] "WorldClim_2.1_IPSL-CM6A-LR_ssp585_10m"
    #>  [86] "WorldClim_2.1_IPSL-CM6A-LR_ssp585_5m"
    #>  [87] "WorldClim_2.1_MIROC6_ssp126_10m"
    #>  [88] "WorldClim_2.1_MIROC6_ssp126_5m"
    #>  [89] "WorldClim_2.1_MIROC6_ssp245_10m"
    #>  [90] "WorldClim_2.1_MIROC6_ssp245_5m"
    #>  [91] "WorldClim_2.1_MIROC6_ssp370_10m"
    #>  [92] "WorldClim_2.1_MIROC6_ssp370_5m"
    #>  [93] "WorldClim_2.1_MIROC6_ssp585_10m"
    #>  [94] "WorldClim_2.1_MIROC6_ssp585_5m"
    #>  [95] "WorldClim_2.1_MPI-ESM1-2-HR_ssp126_10m"
    #>  [96] "WorldClim_2.1_MPI-ESM1-2-HR_ssp126_5m"
    #>  [97] "WorldClim_2.1_MPI-ESM1-2-HR_ssp245_10m"
    #>  [98] "WorldClim_2.1_MPI-ESM1-2-HR_ssp245_5m"
    #>  [99] "WorldClim_2.1_MPI-ESM1-2-HR_ssp370_10m"
    #> [100] "WorldClim_2.1_MPI-ESM1-2-HR_ssp370_5m"
    #> [101] "WorldClim_2.1_MPI-ESM1-2-HR_ssp585_10m"
    #> [102] "WorldClim_2.1_MPI-ESM1-2-HR_ssp585_5m"
    #> [103] "WorldClim_2.1_MRI-ESM2-0_ssp126_10m"
    #> [104] "WorldClim_2.1_MRI-ESM2-0_ssp126_5m"
    #> [105] "WorldClim_2.1_MRI-ESM2-0_ssp245_10m"
    #> [106] "WorldClim_2.1_MRI-ESM2-0_ssp245_5m"
    #> [107] "WorldClim_2.1_MRI-ESM2-0_ssp370_10m"
    #> [108] "WorldClim_2.1_MRI-ESM2-0_ssp370_5m"
    #> [109] "WorldClim_2.1_MRI-ESM2-0_ssp585_10m"
    #> [110] "WorldClim_2.1_MRI-ESM2-0_ssp585_5m"
    #> [111] "WorldClim_2.1_UKESM1-0-LL_ssp126_10m"
    #> [112] "WorldClim_2.1_UKESM1-0-LL_ssp126_5m"
    #> [113] "WorldClim_2.1_UKESM1-0-LL_ssp245_10m"
    #> [114] "WorldClim_2.1_UKESM1-0-LL_ssp245_5m"
    #> [115] "WorldClim_2.1_UKESM1-0-LL_ssp370_10m"
    #> [116] "WorldClim_2.1_UKESM1-0-LL_ssp370_5m"
    #> [117] "WorldClim_2.1_UKESM1-0-LL_ssp585_10m"
    #> [118] "WorldClim_2.1_UKESM1-0-LL_ssp585_5m"
    #> [119] "HYDE_3.3_baseline"

For each dataset, you can get detailed information using the help function:

    help("Example")

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

Here we provide the full documentation for each dataset (sorted in alphabetical order):

    #> 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<e2><80><93>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 <c3><97> 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 <c3><97> 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).
    #>
    #>      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
    #>      <https://doi.org/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<e2><80><93>Pleistocene climate, Geosci.
    #>      Model Dev., 12, 5137<e2><80><93>5155, doi:10.5194/gmd-12-5137-2019
    #>      <https://doi.org/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:
    #>
    #>      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
    #>      <https://doi.org/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
    #>      <https://doi.org/10.6084/m9.figshare.19723405.v1>
    #>
    #>
    #> #######################################################
    #> 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'
    #>
    #>      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
    #>      <https://doi.org/10.5194/essd-9-1-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.
    #>
    #>      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
    #>      <https://doi.org/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
    #>      <https://doi.org/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. If you use this dataset, make sure to cite the
    #>      original publication:
    #>
    #> Details:
    #>
    #>      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
    #>      <https://doi.org/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),
    #>      corresponding to a time_bp of 35. There are 19 <e2><80><9c>bioclimatic<e2><80><9d>
    #>      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_
    #>
    #>      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()'.
    #>
    #>
    #> #######################################################