-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
152 lines (95 loc) · 6.56 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
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
<p align="center">
<img width="240" height="278" src="https://raw.githubusercontent.com/Ischi94/cpnr/master/man/figures/logo.png">
</p>
<!-- badges: start -->
[](https://github.com/Ischi94/cpnr/actions)
[](https://www.tidyverse.org/lifecycle/#maturing)
<!-- badges: end -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
```
```{r setup, include = FALSE}
```
# cpnr: Interactive tutorials for conservation paleobiology
The [Conservation Paleobiology Network](https://conservationpaleorcn.org/) (CPN) aims to transform conservation paleobiology into an applied science that informs conservation and restoration efforts. The project is envisioned as a grass-roots effort to develop strategies for communicating geohistorical data to stakeholder groups.
To facilitate interdisciplinary conservation work, the CPN now offers tutorials. These will cover various topics starting at an introductory level and aim to show students and scientists how to process geohistorical data. This document shows how to use the `cpnr` package and how to start a tutorial.
Please view our [antiracism statement and call for action](https://conservationpaleorcn.org/anti-racism-statement-and-call-for-action/) before proceeding.
The `cpnr`package builds on the amazing `learnr` [package](https://rstudio.github.io/learnr/).
## Requirements
All tutorials are deposited in a R package called `cpnr`, which is currently hosted on [github](https://github.com/Ischi94/cpnr). To access these tutorials, one needs to have R installed on their local device. You can download and install R [here](https://cran.r-project.org/). Note that we recommend the usage of Rstudio, which you can download [here](https://rstudio.com/products/rstudio/download/). R and Rstudio is free and open source, and the R community is welcoming and very inclusive.
### New to R
Here are some additional useful links if you are new to the R programming environment:
* [Introduction to R (manual)](https://cran.r-project.org/doc/manuals/r-release/R-intro.pdf)
* [R for data science (book)](https://r4ds.had.co.nz/index.html)
* [Data visualisations with R (book)](https://ggplot2-book.org/)
### Why Github?
You might be familiar with installing packages from CRAN (the Comprehensive R Archive Network) in R. To install this package, you need to go a different route, as you will see below. Github allows us to provide real time access to our tutorials, as you will access the development version of the `cpnr` package.
## How to start
The `cpnr` package provides interactive tutorials that can be accessed via R. For this, one needs to have the package installed and read into memory. To install the package from github, we can use the `devtools` package:
### Install devtools
The `devtools` package is a tool that can be used to access packages from Github. It needs to be installed in order to access the `cpnr` package. You can check whether `devtools` is already installed by running the following command:
```{r check devtools, eval=FALSE}
"devtools" %in% rownames(installed.packages())
```
If the previous command returned `TRUE`, you're ready to go. If `devtools` is not installed, it will return `FALSE` and we need to install it from CRAN with the following command:
```{r install devtools, eval=FALSE}
install.packages("devtools")
```
### Install cpnr
With `devtools` installed to your local device, we are now ready to install the `cpnr` package from Github using the `devtools::install_github()` function:
```{r install, eval=FALSE}
devtools::install_github("Ischi94/cpnr")
```
To load the package into memory, use the `library` call.
```{r library}
library(cpnr)
```
Now you can access functions within the `cpnr` package.
## Functions
### See what is there
The training-series group of the CPN will add new tutorials to the package from time to time. To see all interactive tutorial currently available, you can use the `show_tutorials` function:
```{r show_tutorials}
show_tutorials()
```
There is currently one tutorial in the package. The `show_tutorials` call returns a dataframe with the title of the tutorial and a short description. To get further information on the tutorial, and to subsequently run it, the title of the tutorial is needed.
### Further details
If the short description returned from `show_tutorials` is not sufficient for you to see what the tutorial contains, you can access a more detailed description via `show_description`. As mentioned above, we need the tutorial name as an argument for the function:
```{r show_description}
show_description(tutorial = "divdyn")
```
### What you need
Each tutorial relies on various packages that might not be installed on your device. Running the tutorial without these packages will fail. It is therefore necessary to check which packages are needed to run the tutorial, and to install them if necessary.
```{r show_dependencies}
show_dependencies(tutorial = "divdyn")
```
To load all these dependencies needed to run a tutorial, and to install the missing ones, you can run `load_depencies`:
```{r load_dependencies, eval=FALSE}
# get dependencies
packages <- show_dependencies(tutorial = "divdyn")
# load or install them
load_dependencies(packages = packages)
```
### Access the tutorial
Now you should know the name of the tutorial you want to run and what it does based on the description. Further, you have loaded and installed all dependencies needed to run the tutorial. Now you are ready to run it. The `start_tutorial` function will initiate the interactive tutorial and open it in a browser:
```{r start_tutorial, eval=FALSE}
start_tutorial(tutorial = "divdyn")
```
### End the tutorial
When you are done with a tutorial, close the tab in your browser and return to RStudio. Here you can just press the Esc button to end the tutorial. You could also click on the red Stop button in the upper right corner of the console.