-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
236 lines (156 loc) · 10.1 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
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
---
output: github_document
editor_options:
chunk_output_type: console
---
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
message = FALSE,
warning = FALSE,
comment = "#>",
fig.path = "man/figures/README-"
)
```
# ggFishPlots
**Visualise and calculate life history parameters for fisheries science using ggplot2. R package version `r packageVersion("ggFishPlots")`**
<!-- badges: start -->
[](https://doi.org/10.32614/CRAN.package.ggFishPlots)
[](https://github.com/DeepWaterIMR/ggFishPlots/actions)
[](https://CRAN.R-project.org/package=ggFishPlots)
<!-- badges: end -->
## Overview
The [ggFishPlots](https://deepwaterimr.github.io/ggFishPlots/) package for [R](https://www.r-project.org/) allows quickly plotting and calculating life history parameters required by stock assessment models. The package uses [ggplot2](https://ggplot2.tidyverse.org/reference) for plotting and the [tidyverse](https://www.tidyverse.org/) packages for calculations.
The ggOceanMaps package has been developed by the [Institute of Marine Research](https://www.hi.no/en). Note that the package comes with absolutely no warranty. Any [bug reports and code fixes](https://github.com/DeepWaterIMR/ggFishPlots/issues) are warmly welcomed. See [*Contributions*](#contributions) for further details.
If you are looking for other similar packages, make sure to check out the [AquaticLifeHistory](https://jonathansmart.github.io/AquaticLifeHistory/articles/Maturity_analyses.html), [FSA](https://CRAN.R-project.org/package=FSA), and [fishmethods](https://CRAN.R-project.org/package=fishmethods) packages, as well as the [FishR webpage](https://fishr-core-team.github.io/fishR/pages/packages.html).
## Installation
The most up to date version of the package can always be found from [GitHub](https://github.com/DeepWaterIMR/ggFishPlots). If the [CRAN version](https://CRAN.R-project.org/package=ggFishPlots) does not work as shown in the examples on this website, try installing the GitHub version. You can do this by using the [devtools](https://cran.r-project.org/web/packages/devtools/index.html) or [remotes](https://cran.r-project.org/web/packages/remotes/index.html) packages.
```{r eval = FALSE}
remotes::install_github("DeepWaterIMR/ggFishPlots")
```
## Usage
The package has a [website](https://deepwaterimr.github.io/ggFishPlots/). At the time of writing, the package produces four kinds of plots: [growth curves](#growth-curves), [maturity plots](#maturity-plots), [length-weight relationships](#length-weight-relationships), and [catch curves](#catch-curves-to-estimate-instantaneous-total-mortality-z). Each function returns a ggplot2 plot and the estimated parameters as a text string that can be used in Rmarkdown and Shiny applications as well as a data frame for further use of the parameters. The elements are returned as a list. The package contains example data to illustrate the functionality.
### Growth curves
Note how the `text` and `params` are returned as a list together with `plot`.
```{r}
library(ggFishPlots)
data(survey_ghl) # example data
head(survey_ghl)
plot_growth(survey_ghl, length = "length", age = "age")
```
The `text` object can be rendered to R markdown documents using the `results = 'asis'` setting in the code chunk header (i.e. `{r, results = 'asis'}`) and the `cat()` function after replacing `"\n"` by `"\ n"`:
```{r, results='asis'}
htmlcat <- function(text){
cat(gsub(pattern = "\n", replacement = " \n", x = text))
}
htmlcat(plot_growth(survey_ghl)$text)
```
#### Split by sex
Specifying `length`, `age` and `sex` arguments have been omitted since they are the argument names by default and the same than in the example data. Only the `plot` element is returned this time.
```{r}
plot_growth(survey_ghl, split.by.sex = TRUE)$plot
```
The dashed lines are $S_{inf}$. Data behind the growth curves are shown as box plots by default. It is possible to plot the data as points by defining `boxplot = FALSE`. We can also force zero group into the curves if know the length of it. Assumed as 14 cm here. Zero group forcing strength is 10 % of number of observations by default and can be adjusted using the `force.zero.group.strength` argument.
```{r}
plot_growth(survey_ghl, force.zero.group.length = 14, boxplot = FALSE)$plot
```
### Maturity plots
#### L50 plots
Maturity ogives are estimated using a logistic (`family = binomial(link = "logit")`) [`glm()`](https://www.rdocumentation.org/packages/stats/versions/3.6.2/topics/glm)
```{r}
plot_maturity(survey_ghl, length = "length", maturity = "maturity")
```
The error bars represent 95% confidence intervals calculated from the model object using the [`confint()`](https://stat.ethz.ch/R-manual/R-devel/library/MASS/html/confint.html) function and back-transformed to the original scale. The grey stepped line is a binned average defined using the `length.bin.width` argument.
The function also contains an option to bootstrap the confidence intervals (CIs) which will produce narrower CIs. Bootstrapping is probably a more correct way of estimating CIs in this application. Using only 10 replicates here to save processing time. In real application use at least 1000.
```{r}
plot_maturity(survey_ghl, bootstrap.n = 10)
```
#### Split by sex
```{r}
plot_maturity(survey_ghl, split.by.sex = TRUE)$plot
```
#### A50 plots
The same principle can be used to produce A50 (50% maturity at age) plots:
```{r}
plot_maturity(survey_ghl, length = "age", length.unit = "years",
xlab = "Age", length.bin.width = 1, split.by.sex = TRUE)$plot
```
#### Addition of juveniles
Also the `plot_maturity()` function has the option to add juveniles (zero group fish). The addition of juveniles can be necessary for to make the `glm()` to converge if small immature fish are scarce in the dataset.
```{r}
plot_maturity(survey_ghl, length = "age", length.unit = "years",
xlab = "Age", length.bin.width = 1,
force.zero.group.length = 0,
force.zero.group.strength = 100,
split.by.sex = TRUE)$plot
```
Note how the addition increases the estimate for males because the dataset did not contain a sufficient number of young males which the number of females seems sufficient because females mature older in this species.
One option can be to estimate the number of added juveniles using the [`plot_catchcurve()`](#catchcurvesep) function:
```{r}
plot_maturity(survey_ghl, length = "age", length.unit = "years",
xlab = "Age", length.bin.width = 1,
force.zero.group.length = 0,
force.zero.group.n = c("F" = exp(11.363), "M" = exp(11.885)),
split.by.sex = TRUE)$plot
```
### Length-weight relationships
#### Log-linearized models
Simple plot using log-transformation and linear models by default.
```{r}
plot_lw(survey_ghl, length = "length", weight = "weight")
```
The dashed lines represent 95% confidence intervals.
#### Non-linear least square models
Use non-linear least squares instead:
```{r}
plot_lw(survey_ghl, use.nls = TRUE)
```
#### Split by sex
The decimal point of a and b estimates depends on the length and weight units. [FishBase](https://www.fishbase.se/manual/english/FishBaseThe_LENGTH_WEIGHT_Table.htm) uses centimeters and grams. The function can correct for the units when asked (but `length.unit` and `weight.unit` parameters have to be defined correctly).
```{r}
plot_lw(survey_ghl, split.by.sex = TRUE, correct.units = TRUE)
```
You can also transform the parameters according to the formulas given in the FishBase.
```{r}
plot_lw(survey_ghl %>% dplyr::mutate(weight = weight*1000), weight.unit = "g")$params
```
#### Log-log axes to see differences
```{r}
plot_lw(survey_ghl, split.by.sex = TRUE, log.axes = TRUE)$plot
```
#### Outlier removal
```{r}
plot_lw(survey_ghl, outlier.percentile = 99.5, annotate.coefficients = TRUE)$plot
```
### Catch curves to estimate instantaneous total mortality (Z)
Catch curves were added to the version 0.2.3 and may not be available in the CRAN version. [A FishR tutorial written by Ogle (2013)](https://www.fishbase.se/manual/english/FishBaseThe_LENGTH_WEIGHT_Table.htm) contains a nice explanation of catch curves. At the time of writing ggFishPlots calculates only the simple log-linearised regression.
```{r}
plot_catchcurve(survey_ghl)
```
The ages to be included to the Z estimation can be adjusted using the `age.range` argument.
```{r}
plot_catchcurve(survey_ghl, age.range = c(10,26))$plot
```
In the plot above, -b is Z (i.e. Z = 0.356) and exp(a) (i.e. 68391) is the number of 0 age fish assuming constant mortality.
#### Split by sex {#catchcurvesep}
```{r}
plot_catchcurve(survey_ghl, age.range = c(10,26), split.by.sex = TRUE)$plot
```
Use a named list to use separate age ranges for females and males.
```{r}
tmp <- plot_catchcurve(survey_ghl,
age.range = list("F" = c(13,26), "M" = c(10,26)),
split.by.sex = TRUE)
tmp$plot
```
Parameter estimates for the catch curve above:
```{r, results='asis'}
htmlcat(tmp$text)
```
## Citations and data sources
The data used in the package are a property of the Institute of Marine Research and the Norwegian Government. They are distributed under the Creative Commons ([CCBY](https://creativecommons.org/licenses/by/4.0/) or [NLOD](https://data.norge.no/nlod/no/1.0/)) licenses allowing free use as long as the source (IMR) is cited. We ask any user to refer to the package if plots or estimates are used in reports or scientific articles. For up-to-date citation information, please use:
```{r}
citation("ggFishPlots")
```
## Contributions
Any contributions to the package are more than welcome. Please contact the package maintainer Mikko Vihtakari (<[email protected]>) to discuss your ideas on improving the package. Bug reports and corrections should be submitted directly to [the GitHub site](https://github.com/DeepWaterIMR/ggFishPlots/issues). Please include a [minimal reproducible example](https://en.wikipedia.org/wiki/Minimal_working_example). Considerable contributions to the package development will be credited with an authorship.