-
Notifications
You must be signed in to change notification settings - Fork 2
/
README.Rmd
188 lines (131 loc) · 9.46 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
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
<!-- You'll still need to render `README.Rmd` regularly, to keep `README.md` up-to-date. `devtools::build_readme()` is handy for this. You could also use GitHub Actions to re-render `README.Rmd` every time you push. An example workflow can be found here: <https://github.com/r-lib/actions/tree/master/examples>. -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# canaper <img src="man/figures/logo.png" align="right" alt="" width="120" />
<!-- badges: start -->
[](https://zenodo.org/badge/latestdoi/359280907)
[](https://github.com/ropensci/canaper/actions)
[](https://www.repostatus.org/#active)
[](https://app.codecov.io/gh/ropensci/canaper?branch=main)
[](https://github.com/ropensci/software-review/issues/475)
[](https://CRAN.R-project.org/package=canaper)
<!-- badges: end -->
```{r srr-tags-intro, eval = FALSE, echo = FALSE}
#' @srrstats {G1.1} documents novelty
```
The goal of `canaper` is to enable [categorical analysis of neo- and paleo-endemism (CANAPE)](https://doi.org/10.1038/ncomms5473) in **R**.
- For [tutorials](https://docs.ropensci.org/canaper/articles/canape.html), see the `canaper` [website](https://docs.ropensci.org/canaper/).
## Installation
The stable version can be installed from
[CRAN](https://CRAN.R-project.org/package=canaper):
```r
install.packages("canaper")
```
The development version can be installed from
[r-universe](http://ropensci.r-universe.dev/ui/#package:canaper) or
[github](https://github.com/ropensci/canaper/):
``` r
# r-universe
options(repos = c(
ropensci = "https://ropensci.r-universe.dev/",
CRAN = "https://cran.rstudio.com/"
))
install.packages("canaper", dep = TRUE)
# OR
# github (requires `remotes` or `devtools`)
remotes::install_github("ropensci/canaper")
```
## Example usage
These examples use the dataset from [Phylocom](https://phylodiversity.net/phylocom/).
The dataset includes a community (site x species) matrix and a phylogenetic tree.
```{r example-data}
library(canaper)
data(phylocom)
# Example community matrix including 4 "clumped" communities,
# one "even" community, and one "random" community
phylocom$comm
# Example phylogeny
phylocom$phy
```
The main "workhorse" function of `canaper` is `cpr_rand_test()`, which conducts a randomization test to determine if observed values of phylogenetic diversity (PD) and phylogenetic endemism (PE) are significantly different from random. It also calculates the same values on an alternative phylogeny where all branch lengths have been set equal (alternative PD, alternative PE) as well as the ratio of the original value to the alternative value (relative PD, relative PE).
```{r rand-test-example}
set.seed(071421)
rand_test_results <- cpr_rand_test(
phylocom$comm, phylocom$phy,
null_model = "swap"
)
```
`cpr_rand_test` produces **a lot** of columns (nine per metric), so let's just look at a subset of them:
```{r rand-test-res}
rand_test_results[, 1:9]
```
This is a summary of the columns:
- `*_obs`: Observed value
- `*_obs_c_lower`: Count of times observed value was lower than random values
- `*_obs_c_upper`: Count of times observed value was higher than random values
- `*_obs_p_lower`: Percentage of times observed value was lower than random values
- `*_obs_p_upper`: Percentage of times observed value was higher than random values
- `*_obs_q`: Count of the non-NA random values used for comparison
- `*_obs_z`: Standard effect size (z-score)
- `*_rand_mean`: Mean of the random values
- `*_rand_sd`: Standard deviation of the random values
The next step in CANAPE is to classify endemism types according to the significance of PE, alternative PE, and relative PE. This adds a column called `endem_type`.
```{r categorize-endem}
canape_results <- cpr_classify_endem(rand_test_results)
canape_results[, "endem_type", drop = FALSE]
```
This data set is very small, so it doesn't include all possible endemism types. In total, they include:
- `paleo`: paleoendemic
- `neo`: neoendemic
- `not significant` (what it says)
- `mixed`: mixture of both paleo and neo
- `super`: mixed and highly significant (*p* < 0.01)
For a more complete example, please [see the vignette](https://docs.ropensci.org/canaper/articles/canape.html)
## Comparsion with other software
Several other R packages are available to calculate diversity metrics for ecological communities. The non-exhaustive summary below focuses on alpha diversity metrics in comparison with `canaper`, and is **not** a comprehensive description of each package.
- [PhyloMeasures](https://doi.org/10.1111/ecog.01814): Calculates phylogenetic community diversity metrics including MPD, MNTD, PD, phylosor, and unifrac. Null models for matrix randomization include `uniform`, `frequency.by.richness`, and `sequential`.
- [phyloregion](https://github.com/darunabas/phyloregion): Calculates PD but not MPD or MNTD. Implements sparse matrix encoding to increase computing speed, which is used by `canaper`. Null models for matrix randomization include `tipshuffle`, `rowwise`, and `colwise`. Also performs regionalization based on taxonomic or phylogenetic beta diversity.
- [picante](https://github.com/skembel/picante): Calculates MPD, MNTD, PD, etc. Null models for community matrix randomization include `frequency`, `richness`, `independentswap`, and `trialswap`.
- [vegan](https://github.com/vegandevs/vegan): Performs a large range of mostly non-phylogenetic diversity analyses. Includes the largest selection of null models (> 20), according to data type (binary vs. quantitative). `canaper` uses `vegan` to randomize community matrices.
- [biodiverse](http://shawnlaffan.github.io/biodiverse/): Not an R package, but software written in perl with a GUI. Performs all of the calculations needed for CANAPE, and many other metrics (> 300). Includes `rand_structured` null model as well as spatially structured null models. None of these null models are currently available in any R packages AFAIK, except for `independentswap`.
## Other information
Poster at [Botany 2021](https://2021.botanyconference.org/)
- [PDF](https://github.com/joelnitta/botany_poster_2021/raw/main/canaper.pdf)
- [Video](https://www.youtube.com/watch?v=LXn_ziEli_Q)
## Citing this package
If you use this package, please cite it! Here is an example:
- Nitta JH, Laffan SW, Mishler BD, Iwasaki W. (2021) canaper: Categorical analysis of neo- and paleo-endemism in R. doi: 10.5281/zenodo.5094032
The example DOI above is for the overall package.
Here is the latest DOI, which you should use if you are using the latest version of the package:
[](https://zenodo.org/badge/latestdoi/359280907)
You can find DOIs for older versions by viewing the "Releases" menu on the right.
## Papers citing `canaper`
- van Galen *et al.* 2023. "Correlated evolution in an ectomycorrhizal host-symbiont system". *New Phytologist* https://doi.org/10.1111/nph.18802
- Naranjo *et al.* 2023. "Ancestral area analyses reveal Pleistocene-influenced evolution in a clade of coastal plain endemic plants". *Journal of Biogeography* 50, 393-405 https://doi.org/10.1111/jbi.14541
- Ellepola *et al.* 2022. "The role of climate and islands in species diversification and reproductive-mode evolution of Old World tree frogs". *Communications Biology* 5, 347 https://doi.org/10.1038/s42003-022-03292-1
- Lu *et al.* 2022 "A comprehensive evaluation of flowering plant diversity and conservation priority for national park planning in China". *Fundamental Research* https://doi.org/10.1016/j.fmre.2022.08.008
- Nitta *et al.* 2022 "Spatial phylogenetics of Japanese ferns: Patterns, processes, and implications for conservation". *American Journal of Botany* 109, 727-745 https://doi.org/10.1002/ajb2.1848
## Contributing and code of conduct
Contributions to `canaper` are welcome! For more information, please see [CONTRIBUTING.md](https://github.com/ropensci/canaper/blob/main/.github/CONTRIBUTING.md)
Please note that this package is released with a [Contributor Code of Conduct](https://ropensci.org/code-of-conduct/). By contributing to this project, you agree to abide by its terms.
## Note to developers
[roxyglobals](https://github.com/anthonynorth/roxyglobals) is used to maintain [`R/globals.R`](R/globals.R), but is not available on CRAN.
You will need to install this package from github and use the `@autoglobal` or `@global` roxygen tags to develop functions with globals.
## Licenses
- Code: [MIT](https://github.com/ropensci/canaper/blob/main/LICENSE.md)
- Example datasets
- `acacia`, `biod_example`: [GNU General Public License v3.0](https://github.com/ropensci/canaper/blob/main/data-raw/LICENSE-gpl-3.txt)
- `phylocom`: [BSD-3-Clause](https://github.com/ropensci/canaper/blob/main/data-raw/LICENSE-bsd3.txt)
## References
Mishler, B., Knerr, N., González-Orozco, C. *et al*. Phylogenetic measures of biodiversity and neo- and paleo-endemism in Australian *Acacia*. *Nat Commun* 5, 4473 (2014). https://doi.org/10.1038/ncomms5473