-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
194 lines (139 loc) · 7.82 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{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
<!-- badges: start -->
[](https://lbesson.mit-license.org/)
[](https://lifecycle.r-lib.org/articles/stages.html)
[](https://lifecycle.r-lib.org/articles/stages.html) <br >
[](https://img.shields.io/github/r-package/v/mchevalier2/crestr) <br >
<br >
[](https://github.com/mchevalier2/crestr/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->
`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.**
<br >
> **_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 <paleo@manuelchevalier.com> 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 **<https://www.manuelchevalier.com/crestr/>**.
### 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 <https://www.manuelchevalier.com/crestr/articles/get-started.html>
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)