https://github.com/ropensci/dwctaxon
R package for working with Darwin Core Taxon data
https://github.com/ropensci/dwctaxon
database r-package rstats
Last synced: 4 months ago
JSON representation
R package for working with Darwin Core Taxon data
- Host: GitHub
- URL: https://github.com/ropensci/dwctaxon
- Owner: ropensci
- License: other
- Created: 2021-12-02T07:40:14.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2025-12-15T02:06:55.000Z (6 months ago)
- Last Synced: 2026-02-08T10:00:36.228Z (5 months ago)
- Topics: database, r-package, rstats
- Language: R
- Homepage: https://docs.ropensci.org/dwctaxon/
- Size: 6.23 MB
- Stars: 9
- Watchers: 1
- Forks: 0
- Open Issues: 13
-
Metadata Files:
- Readme: README.Rmd
- Changelog: NEWS.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Citation: CITATION.cff
- Codemeta: codemeta.json
Awesome Lists containing this project
README
---
output: github_document
editor_options:
chunk_output_type: console
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/"
)
# Increase width for printing tibbles
old <- options(width = 140)
set.seed(12345)
```
# dwctaxon 
[](https://www.repostatus.org/#active)
[](https://zenodo.org/badge/latestdoi/434126221)
[](https://ropensci.r-universe.dev/dwctaxon)
[](https://app.codecov.io/gh/ropensci/dwctaxon?branch=main)
[](https://github.com/ropensci/dwctaxon/actions?query=workflow%3Apkgcheck)
[](https://github.com/ropensci/software-review/issues/574)
[](https://doi.org/10.21105/joss.06215)
The goal of dwctaxon is to facilitate working with [Darwin Core Taxon data](https://dwc.tdwg.org/terms/#taxon) in R.
## Statement of need
dwctaxon facilitates **editing** and **validating** Darwin Core Taxon data. There are various reasons one might want to do this. Here is a non-exhaustive list of use-cases for dwctaxon:
- To maintain an existing taxonomic database.
- To prepare a taxonomic database as a reference for taxonomic name resolution, for example with the [taxastand](https://github.com/joelnitta/taxastand) or [U.Taxonstand](https://doi.org/10.1016/j.pld.2022.09.001) R packages.
- To curate taxonomic data as part of a [Darwin Core Archive](https://en.wikipedia.org/wiki/Darwin_Core_Archive).
In theory, dwctaxon could be used to create taxonomic databases from scratch, but it is more likely to be useful for updating and validating existing databases (R in general is more suited to data wrangling and analysis as opposed to data entry).
## Resources
For detailed usage examples, see the vignettes:
- [What is DwC?](https://docs.ropensci.org/dwctaxon/articles/what-is-dwc.html)
- [Editing DwC taxon data](https://docs.ropensci.org/dwctaxon/articles/editing.html)
- [Validating DwC taxon data](https://docs.ropensci.org/dwctaxon/articles/validation.html)
- [Real World Example](https://docs.ropensci.org/dwctaxon/articles/real-data.html)
For more information about dwctaxon, in particular for using it to maintain a reference database for taxonomic name resolution, see [taxastand and dwctaxon: A pair of R packages for standardizing species names in Darwin Core format (BioDigiCon 2022 talk)](https://www.joelnitta.com/talks/2022-09-27_biodigi.html).
## Installation
The stable version can be installed from [CRAN](https://cran.r-project.org/package=dwctaxon):
```r
install.packages("dwctaxon")
```
The development version can be installed from [r-universe](https://ropensci.r-universe.dev/dwctaxon) or [github](https://github.com/ropensci/dwctaxon).
``` r
options(repos = c(
ropensci = "https://ropensci.r-universe.dev/",
CRAN = "https://cran.rstudio.com/"
))
install.packages("dwctaxon", dep = TRUE)
```
OR
``` r
# install.packages("remotes")
remotes::install_github("ropensci/dwctaxon")
```
## Usage
First, load packages and a dataset to work with:
```{r load-pkg-data, message = FALSE}
library(tibble) # recommended for pretty printing of tibbles
library(dwctaxon)
dct_filmies
```
`dct_filmies` is a taxonomic dataset of filmy ferns included in dwctaxon.
For demonstration purposes, we will just use the first five rows:
```{r filmies-small}
filmies_small <- head(dct_filmies, 5)
```
All functions in dwctaxon start with `dct_`.
### Edit data
`dct_add_row()` adds one or more rows, automatically providing values for `taxonID`.
```{r add-row}
filmies_small |>
dct_add_row(
scientificName = "Hymenophyllum dwctaxonense Nitta",
taxonomicStatus = "accepted"
)
```
`dct_modify_row()` modifies a row, automatically re-mapping synonyms if needed.
```{r modify-row}
# Change C. densinervium to a synonym of C. crassum
filmies_small |>
dct_modify_row(
scientificName = "Cephalomanes densinervium (Copel.) Copel.",
taxonomicStatus = "synonym",
acceptedNameUsage = "Cephalomanes crassum (Copel.) M. G. Price"
)
```
`dct_fill_col()` fills in values for columns that have "term" - "termID" pairs (e.g., `acceptedNameUsage` and `acceptedNameUsageID`).
```{r fill-col}
# Fill-in the acceptedNameUsage column with scientific names
filmies_small |>
dct_fill_col(
fill_to = "acceptedNameUsage",
fill_from = "scientificName",
match_to = "taxonID",
match_from = "acceptedNameUsageID"
)
```
### Validate data
`dct_validate()` is the main function for validation, and automatically conducts a series of checks. The individual checks can be run with `dct_check_*()` functions.
The `dct_filmies` dataset is already well-formatted, so it will pass validation:
```{r validate-pass}
# Default behavior is to return the original dataset if checks pass
# For this example, return TRUE instead
dct_validate(dct_filmies, on_success = "logical")
```
For demonstration purposes, let's mess up the data:
```{r make-dirty-filmies}
# Start by duplicating some data
filmies_dirty <- rbind(head(dct_filmies), head(dct_filmies, 2))
# Replace some values of `acceptedNameUsageID` with random letters
filmies_dirty$acceptedNameUsageID[sample(1:8, 5)] <- sample(letters, 5)
```
By default, `dct_validate()` will stop with an error on the first check that fails:
```{r validate-error, error = TRUE}
dct_validate(filmies_dirty)
```
But it may be useful to get an overview of all the checks that failed. This can be done by setting `on_fail` to `"summary"`:
```{r validate-summary-show, eval = FALSE, echo = TRUE}
dct_validate(filmies_dirty, on_fail = "summary")
```
```{r validate-summary-print, echo = FALSE, message = FALSE}
dct_validate(filmies_dirty, on_fail = "summary") |>
dplyr::mutate(error = stringr::str_trunc(error, 40, "right"))
```
### Piping
All the functions in dwctaxon take a dataframe as their first argument and return a dataframe by default, so they are "pipe-friendly" and can be chained together:
```{r pipe}
dct_filmies |>
dct_modify_row(
taxonID = "54133783",
taxonomicStatus = "accepted"
) |>
dct_add_row(
scientificName = "Hymenophyllum dwctaxonense Nitta",
taxonomicStatus = "accepted"
) |>
dct_validate()
```
It's often a good idea to include `dct_validate()` at the end of a chain to make sure the modified taxonomic database is still correctly formatted.
## Citing this package
If you use this package, please cite it!
Nitta, JH and Iwasaki, W (2024). dwctaxon, an R package for editing and validating taxonomic data in Darwin Core format. Journal of Open Source Software, 9(93), 6215, https://doi.org/10.21105/joss.06215
## Contributing
Contributions to this package are welcome! Please see the [Contribution Guide](https://github.com/ropensci/dwctaxon/blob/main/.github/CONTRIBUTING.md) and [Code of Conduct](https://ropensci.org/code-of-conduct/).
## 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 License](https://github.com/ropensci/dwctaxon/blob/main/LICENSE.md)
Data:
- [`dct_filmies`](https://docs.ropensci.org/dwctaxon/reference/dct_filmies.html): Modified from data downloaded from the [Catalog of Life](https://www.catalogueoflife.org/) under the [Creative Commons Attribution (CC BY) 4.0](https://creativecommons.org/licenses/by/4.0/) license.
- [`dct_terms`](https://docs.ropensci.org/dwctaxon/reference/dct_terms.html): Modified from data downloaded from [TDWG Darwin Core](https://dwc.tdwg.org/) under the [Creative Commons Attribution (CC BY)4.0](https://creativecommons.org/licenses/by/4.0/) license.
Images:
- [DwC archive components image](https://docs.ropensci.org/dwctaxon/articles/dwca.png): Copied from [GBIF Integrated Publishing Toolkit (IPT)](https://github.com/gbif/ipt/) under the [Apache license](https://github.com/gbif/ipt/blob/master/LICENSE.txt)
```{r, include = FALSE}
# Reset options
options(old)
```