-
Notifications
You must be signed in to change notification settings - Fork 3
Expand file tree
/
Copy pathREADME.Rmd
More file actions
93 lines (67 loc) · 5.52 KB
/
README.Rmd
File metadata and controls
93 lines (67 loc) · 5.52 KB
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
---
title: "suwo: access nature media repositories"
output: github_document
editor_options:
chunk_output_type: console
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
<!-- badges: start -->
[](https://lifecycle.r-lib.org/articles/stages.html)
<!-- [](https://cran.r-project.org/package=suwo) -->
[](https://www.repostatus.org/#active)
[](https://www.gnu.org/licenses/gpl-3.0.en.html)
<!-- [![minimal R version](https://img.shields.io/badge/R%3E%3D-`r strsplit(gsub("depends: R \\(|\\)", "", grep("^DEPENDS", ignore.case = TRUE, readLines(con = "./DESCRIPTION"), value = TRUE), ignore.case = TRUE), ",")[[1]][1]`-6666ff.svg)](https://cran.r-project.org/) -->
<!-- [![packageversion](https://img.shields.io/badge/Package%20version-`r gsub("version: |version:", "", grep("^version", ignore.case = TRUE, readLines(con = "./DESCRIPTION"), value = TRUE), ignore.case = TRUE)`-orange.svg?style=flat-square)](commits/develop) -->
[)`-yellowgreen.svg)](https://github.com/ropensci/suwo/commits/main)
[](https://app.codecov.io/gh/ropensci/suwo?branch=main)
[](https://github.com/ropensci/suwo/actions?query=workflow%3Apkgcheck)
<!-- [](https://cran.r-project.org/package=suwo) -->
<!-- [](https://cranlogs.r-pkg.org/badges/grand-total/suwo) -->
[](https://github.com/ropensci/suwo/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->
The [suwo](https://docs.ropensci.org/suwo/) package aims to simplify the
retrieval of nature media (mostly photos, audio files and videos) across
multiple online biodiversity databases. The five major media repositories
accessed by this package (GBIF, iNaturalist, Macaulay Library, WikiAves,
and Xeno-Canto) collectively host more than 250 million media files. Such media
are increasingly used in diverse fields, ranging from ecology and evolutionary
biology (e.g., trait evolution) to wildlife monitoring and conservation
(e.g., for training species detection models). The ability to access and
download large amounts of media files and their associated metadata from a
single interface thus provides a uniquely powerful resource for facilitating
research and conservation efforts.
The main features of the package are:
- Obtaining media metadata from online repositories
- Downloading associated media files
- Updating data sets with new records
## Installing suwo
<!-- Install the package from CRAN (: -->
<!-- ```{r, eval = FALSE} -->
<!-- # install from CRAN -->
<!-- install.packages("suwo") -->
<!-- # load package -->
<!-- library(suwo) -->
<!-- ``` -->
To install the latest developmental version from
[github](https://github.com/) run:
```{r, eval = FALSE}
install.packages("suwo", repos = c(
'https://ropensci.r-universe.dev',
'https://cloud.r-project.org'
))
#load package
library(suwo)
```
# Basic workflow for obtaining nature media files
Obtaining nature media using [suwo](https://docs.ropensci.org/suwo/) follows a basic
sequence. The following diagram illustrates this workflow and the main functions
involved:
<center><img src="./vignettes/workflow_diagram.png" alt="Flowchart of the suwo workflow for obtaining nature media files. Step 1, 'Get metadata', includes multiple boxes representing queries to different repositories, such as query_wikiaves() and query_xenocanto(), plus additional possible query_() calls. Arrows from all these queries converge into Step 2, 'Combine metadata', using merge_metadata() and 'Remove duplicates', using find_duplicates() and remove_duplicates(). The last step is 'Download media', using download_media(). Finally, user can update previous queries using update_metadata()" width="100%"></center>
Take a look at the [package vignette](https://docs.ropensci.org/suwo/articles/suwo.html) for an overview of the workflow and the core querying functions.
## Intended use and responsible practices
The [suwo](https://docs.ropensci.org/suwo/) package is designed exclusively for non-commercial, scientific purposes, including research, education, and conservation. **Commercial use of data or media retrieved through this package is the user’s responsibility and is allowed only when the applicable license of the source database explicitly permits such use, or when explicit, separate permission has been obtained directly from the original source platforms or rights holders**. Users must comply with the specific terms of service and data-use policies of each source database, which may require attribution and may further restrict commercial application. The package developers assume no liability for misuse of the retrieved data or for violations of third-party terms of service.
## Citation
Please cite [suwo](https://docs.ropensci.org/suwo/) as follows:
```{r citation, echo = FALSE}
cat(format(citation("suwo"), style = "text"))
```