crestr

A R package to apply the climate reconstruction CREST.

https://github.com/mchevalier2/crestr

Keywords

Repository

A R package to apply the climate reconstruction CREST.

README.Rmd

---
output: github_document
---



```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# **crestr** An R package to perform probabilistic palaeoclimate reconstructions from palaeoecological datasets 


[![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](https://lbesson.mit-license.org/)
[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html)
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://lifecycle.r-lib.org/articles/stages.html) 

![CRAN/METACRAN](https://img.shields.io/cran/v/crestr)
[![GitHub R package version](https://img.shields.io/github/r-package/v/mchevalier2/crestr)](https://img.shields.io/github/r-package/v/mchevalier2/crestr) 

![Total downloads](https://cranlogs.r-pkg.org/badges/grand-total/crestr)
![Last month downloads](https://cranlogs.r-pkg.org/badges/crestr)
 


[![R-CMD-check](https://github.com/mchevalier2/crestr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/mchevalier2/crestr/actions/workflows/R-CMD-check.yaml)



`crestr` produces probabilistic reconstructions of past climate change from fossil assemblage data [(Chevalier, 2022)](https://cp.copernicus.org/articles/18/821/2022/). `crestr` works by analysing how certain biological indicators (like plant or animal remains) respond to climate factors, using statistical methods to estimate these relationships. These relationships are mdelled as probability density functions (_PDFs_; see [Chevalier *et al.* (2014)](https://www.doi.org/10.5194/cp-10-2081-2014) and [Chevalier (2019)](https://www.doi.org/10.1016/j.gloplacha.2019.01.016)). The theory underpinning this package is explained in section [_A bit of theory_](https://www.manuelchevalier.com/crestr/articles/theory.html) and is illustrated with an application based on pseudo-data in section [_Get Started_](https://www.manuelchevalier.com/crestr/articles/get-started.html). The different vignettes present different aspects of the structure of the package and the data it contains, along with applications based on real data.


**Why choose `crestr`?** Unlike traditional methods, crestr uses probabilistic techniques to provide more accurate and flexible climate reconstructions. **Its focus on accessibility means you don’t need to be an expert coder to get meaningful results.**





> **_NOTE:_** While active development of crestr has concluded, its robust features will continue to provide valuable insights for palaeoclimate research. The available documentation and resources will remain accessible for independent use. In addition, I am committed to maintaining this bug-free. As such, please reach out at  if you encounter technical issues.



## Installation

Ready to explore the climate history hidden in your data? Install `crestr` now and leverage its robust tools for your research.

The package is available from [GitHub](https://github.com/mchevalier2/crestr/) and can be installed as follow:

``` r
if(!require(devtools)) install.packages("devtools")
devtools::install_github("mchevalier2/crestr")
```





## How to use `crestr`

### Online documentation

The package is fully documented and the help of each function can be accessed
with `?function`. More detailed information as well as documented examples are
available from ****.

### A Quick Example

The following example illustrates the basics of `crestr` using pseudo-data
(_i.e._ randomly generated data).


```{r example}
library(crestr)
## loading example data
data(crest_ex)
data(crest_ex_pse)
data(crest_ex_selection)
```

Let's first have a look at the data. The dataset is composed of 20 fossil
samples from which 7 taxa have been identified. The data are expressed in percentages.

```{r data_preview_fossil}
## the first 6 samples
head(crest_ex)
##
## the structure of the data frame
str(crest_ex)
```

For each reconstruction, a proxy-species equivalency ('pse') table must be provided.
Here, with the 7 pseudo-taxa, it looks like:
```{r data_preview_pse}
crest_ex_pse
```

Finally, unique sets of taxa can be specified to reconstruct each climate
variable. In the example, *bio1* (mean annual temperature) and *bio12* (annual
precipitation) will be reconstructed. The dataset has been designed so that
Taxa 1, 2, 3 and 7 are sensitive to *bio1* while Taxa 1, 4, 5 and 7 are sensitive
to *bio12*. Check 
for more details on this selection.

```{r data_preview_selection}
crest_ex_selection
```

These pseudo-data can be provided to the **crest** function and provided some
parameters (see the full vignettes for a detail of these parameters), the
reconstructions will be processed.

```{r reconstructing_climate, results='hide'}
recons <- crest(
   df = crest_ex, pse = crest_ex_pse, taxaType = 0,
   site_info = c(7.5, 7.5), site_name = 'crest_example',
   climate = c("bio1", "bio12"), bin_width = c(2, 50),
   shape = c("normal", "lognormal"),
   selectedTaxa = crest_ex_selection, dbname = "crest_example"
)
```

A specific print function was created to summarise the crestObj.

```{r showcase-print}
recons
```

The climate sampled by the data can be graphically represented for a quick
assessment of the calibration dataset.

```{r plot-climate-space, out.width="100%", fig.height=7, fig.width=7}
plot_climateSpace(recons)
```


Additional graphical tools can be used to assess which taxa should/could be used
for each variable. On the following example, it is clear that Taxon2 has a much
stronger correlation with *bio1* than to *bio12*, hence its selection for *bio1*
only.

```{r plot-plot_taxaCharacteristics, fig.width=7.5, fig.height=8.8}
plot_taxaCharacteristics(recons, taxanames='Taxon2')
```

The results can be quickly visualised using the plot function and the
reconstructed climate values can be accessed from the nested `recons` object:

```{r extract_results_0}
names(recons)
lapply(recons$reconstructions, names)
```

```{r extract_results}
head(recons$reconstructions$bio1$optima)
str(recons$reconstructions$bio1$optima)
```

```{r extract_results2}
signif(recons$reconstructions$bio1$likelihood[1:6, 1:6], 3)
str(recons$reconstructions$bio1$likelihood)
```


```{r plot,  fig.show="hold", out.width="50%"}
plot(recons, climate = 'bio1')
plot(recons, climate = 'bio12', simplify=TRUE, uncertainties=c(0.4, 0.6, 0.8))
```

If satisfying, the results can be directly exported from the R environment in
unique spreadsheets for each variables (or csv files) and the **crest** object
is exported as an RData file to enable easy reuse in the future.

```{r export}
export(recons, loc=getwd(), dataname='crest-test')
list.files(file.path(getwd(), 'crest-test'))
```

```{r delete export example, echo = FALSE, results = "hide"}
unlink(file.path(getwd(), 'crest-test'), recursive=TRUE)
```


## References

 - Chevalier, M., Cheddadi, R., Chase, B.M., 2014. CREST (Climate REconstruction
   SofTware): a probability density function (PDF)-based quantitative climate
   reconstruction method. *Clim. Past* 10, 2081–2098. [10.5194/cp-10-2081-2014](https://www.doi.org/10.5194/cp-10-2081-2014)
 - Chevalier, M., 2019. Enabling possibilities to quantify past climate from
   fossil assemblages at a global scale. *Glob. Planet. Change* 175, 27–35.
   [10.1016/j.gloplacha.2019.01.016](https://www.doi.org/10.1016/j.gloplacha.2019.01.016)
 - Chevalier, M., 2022. _crestr_ an R package to perform probabilistic climate
   reconstructions from palaeoecological datasets. Clim. Past
   [doi:10.5194/cp-18-821-2022](https://www.doi.org/10.5194/cp-18-821-2022)

Owner

Citation (CITATION.cff)

cff-version: 1.2.0
message: "If you use this software, please cite it as below."
authors:
- family-names: "Chevalier"
  given-names: "Manuel"
  orcid: "https://orcid.org/0000-0002-8183-9881"
title: "crestr: an R package to perform probabilistic climate reconstructions from palaeoecological datasets"
version: 1.4.1
doi: 10.5194/cp-18-821-2022
date-released: 2025-01-22
url: "https://www.manuelchevalier.com/crestr"

GitHub Events

Committers

Last synced: about 2 years ago

Packages