-
Notifications
You must be signed in to change notification settings - Fork 0
/
user_manual.Rmd
159 lines (101 loc) · 13.8 KB
/
user_manual.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
---
title: ""
author: "Josh Nowak & Paul Lukacs"
output:
html_document:
toc: true
toc_depth: 4
toc_float:
collapsed: true
smooth_scroll: true
theme: flatly
---
<br>
<br>
## PopR User Manual
### Overview
SpeedGoat is a one-stop shop for maximizing information gained from hard-earned data. We listen to wildlife professionals so we can build customized tools that provide the information needed to make difficult decisions, automate tedious tasks and defend management actions. We emphasize data accessibility, transparency and repeatable analyses. PopR is the realization of this vision. We consider PopR a workflow management system. PopR manages all data transactions and manipulations while allowing cutting-edge statistical tools to act on data.
### Use Cases
1. How many animals should be harvested to achieve management objectives?
+ After opening PopR and navigating to the IPM Setup sub-item the user would set the Analysis Years to the desired range where the last year represents the year in which the goal should be achieved. The user can then choose a model structure to evaluate, for example time-varying reproduction with constant survival of older age classes. Next, the user would navigated to the harvest inputs and propose a harvest prescription that they think would achieve the desired goal. Finally, click the run button and wait for the model to be evaluated. When the model finishes the user can move to the Plots sub-item and evaluate whether all defining characteristics of the objective are being met. The total population is one metric that could be evaluated, but it would also be prudent to evaluate the number of females in the population to ensure that harvest had the desired effect on the population's ability to grow. Then too, the number of males in the population might be of interest if harvest opportunity is to be maintained during the population manipulation. To better understand the effects of harvest Survival and Ratio plots fill gaps in our knowledge as to how growth occurred.
2. How many animals were harvested in 2012? How many of those were female?
+ The user would simply open PopR and navigate to the IPM Setup sub-item. The bottom-box on this page shows tabular model inputs including harvest. To Find out the total number of animals killed click in filter box directly below the Year column heading and move the sliders to 2012. The table will automatically update and only the 2012 data will be shown to the user. We can now see the harvest in that year.
There are many uses for the webiste beyond running the integrated population models and more tools are being developed all the time. For example, many of the plots and tables can be downloaded to aid in custom report building. If you have an idea of a tool you would like to see in PopR please post your idea to our issue tracker detailed in the Help section of this document.
### Location
PopR is a collection of web based tools that can be accessed through [www.speedgoat.io](https://www.speedgoat.io). The tool can be accessed by any web browser with an internet connection.
### Navigation
Once the user arrives at their PopR website a sidebar will appear. The sidebar allows users to navigate among screens by simple mouse clicks. The structure of this document follows the structure of the website using sidebar tabs and sub-tabs as section headings. Please note that each site is unique and this document is general, so tabs may or may not be present in your particular implementation.
### Home
This is a simple landing page that has no function at this time.
### IPM
The IPM tab is where the majority of work will be done. Clicking on this tab will cause sub-items to appear or disappear, but does not perform a function beyond making the sub-items visible.
#### Setup
Once a user has clicked on the IPM tab the Setup sub-item will be available for selection. Clicking on Setup brings the user to the IPM setup screen. On this screen the user will see three major boxes of information. The top left box is reserved for user inputs while the top right box holds graphical displays of data and the lower box shows tabular data inputs. All information on the screen are *inputs* to the IPM.
##### Top-Left Box
The box in the top left of the screen holds widgets the user can manipulate to change model inputs and structure. The user is required to navigate through each of the box items (denoted by numbers 1 through 4).
1. Overview - Basic model setup inputs
+ Species - Choose the species to model, if only one option appears then that is all the species available
+ DAU - Data Analysis Unit, this is a generic term that allows for different spatial units to be analyzed. In some cases only a single option exists.
+ IPM Database - The source of data inputs such as population size, harvest and demographic rates. In some cases it may be desirable to withhold data or add data to the model inputs. The IPM Database dropdown widget maintains the flexibility necessary to accomodate multiple databases, if desired.
+ Analysis Years - The years of data to include. Generally it is a good idea to run models for long periods, but when data quality varies it may be desirable to start model runs at some more recent date. The slider also controls the number of years predictions will be made into the future. Running models with less than 5-10 years of data is not advised.
2. Structure - Define model structure
+ Reproduction - Reproduction can be considered constant or time varying. For Bison we generally think that Time-Varying reproduction is a reasonable assumption.
+ Juvenile Survival - Survival of animals 6 months to 18 months of age, which can be considered Constant or Time-Varying. Bison life history and other studies suggest that survival of young animals quickly rises to parity with adults and for this reason setting this widget to Constant seems a reasonable assumption.
+ SubAdult - For some species
+ Adult Survival - Adult survival in large long-lived animals is generally considered to be a relatively constant rate, in the absence of harvest. The options for this widget are Constant or Time-Varying. A strong argument can be made for assuming that Adult Survival be set to Constant.
3. Harvest - Manipulate future harvest
+ Female Future Harvest - This input widget allows the user to define future harvest of female animals.
+ Male Future Harvest - Similar to the Female widget, but for Males.
4. Run - MCMC Controls
+ Burnin Length - Models fit using [MCMC methods](https://en.wikipedia.org/wiki/Markov_chain_Monte_Carlo) use a burnin period. This slider controls the length of the burnin. If the run is purely for demonstration purposes then a short burnin is just fine, but for critical decisions and the best inference it is recommended that the user move the slider to 10,000.
+ MCMC Iterations - MCMC techniques explore parameter space for a set number of iterations before stopping. This slider controls the number of iterations to conduct. In addition, the "answer" to any problem is simply a summary statistic (say the mean) of the iterations. When running a model for decision making purposes it is important that the model run for a relatively long time (e.g. 20,000+).
+ Thinning Rate - The thinning rate simply keeps every nth iteration. If the MCMC Iterations slider is set to 10,000 and the thinning rate is 2 then 5,000 values will be used to summarize the answer. The user does not need to worry about this slider as it has no effect on model output.
+ Automate Convergence - When clicked the number of iterations the user specified will run and then convergence tests will be conducted. If any of the convergence tests fail the model will run for more iterations and then convergence tests will run again. This pattern will continue until the model converges or 1,000,000 iterations have been run. Using this feature can dramatically increase run time and is generally not necessary.
+ When the user is ready to run a model simply click on the Fit Model button and a progress bar will appear in the lower right corner of the screen. When the progress bar leaves the screen the user will be notified that the model has finished running.
##### Top-Right Box
The top-right box shows the user models inputs as plots.
* Harvest - The harvest plot shows age by sex observed and future harvest.
* Abundance - Shows the total number of animals counted each year.
* Survival - No plot because no survival estimates were available for display.
* Ratios - A plot of the ratio of young to adult animals observed each year
* Priors - The prior plot is an interactive plot that allows the user to view the initial guess formed via the literature and/or expert opinion. The model combines the prior and the data to arrive at the final solution.
##### Bottom Box
The box at the bottom of the screen shows model inputs in a tabular fashion. Note the tables can be manipulated in a number of ways. Columns can be sorted by clicking on the small arrows to the right of the column label. Columns can be filtered to certain values by typing in the space below the column heading. Rows may be selected by clicking on the desired entry. The buttons above and to the right of the table provide a means of copying the table to the user's clipboard, printing the table and hiding columns to customize the appearance of the table.
* Tabular model inputs mimic the order and definition of the plots described in the top-right box.
#### Plots
A screen to visually display the estimates from the model. The screen is organized by 4 major types of parameter estimates. The top-left box displays abundance estimates. Ratio estimates appear at top-right of the screen. Survival estimates for Females and Males can be viewed in the bottom-left of the screen. The bottom-right box shows miscellaneous plots such as population growth rate.
##### Top-Left Box (Abundance)
* Total - The total tab shows plots of the total number of animals estimated in the population. Smaller light brown dots represent field counts.
* Female/Male - When the female or male tab is selected a plot of just the selected sex can be viewed. The age of the animals being displayed is controlled by the dropdown widget at the top-left.
##### Top-Right Box (Ratios)
* Age - A plot of age ratios derived from the model estimates.
* Sex - A plot of the sex ratios derived from the model estimates.
##### Bottom-Left (Survival)
* Female - A time-series plot of female survival. The dropdown widget above the plot allows for each age group to be shown individually.
* Male - Same as the female plots.
##### Bottom-Right (Misc)
* Growth Rate - A time-series plot of population growth rate.
#### Tables
Clicking on the Tables tab will display a table of all the model parameters. Note the tables can be manipulated in a number of ways. Columns can be sorted by clicking on the small arrows to the right of the column label. Columns can be filtered to certain values by typing in the space below the column heading. Rows may be selected by clicking on the desired entry. The buttons above and to the right of the table provide a means of copying the table to the user's clipboard, printing the table and hiding columns to customize the appearance of the table.
##### Column Descriptions
* Parameter - The name of the estimated parameter
* DAU - The spatial area of the analysis, Data Analysis Unit
* Year - The year of the estimate, note that constant parameters are reported for each year despite being the same value
* Age - The ageclass to which the estimate refers. The Ages always follow YOY (Y), Juvenile (J), SubAdult (S), Adult (A), but the meaning of the age is species specific. Typically Y is 0-6 months, J is 6-18 months and S is 18-30 months and A is greater than 30 months of age.
* Sex - F or M for female and male respectively
* Mean - The mean of the parameter estimate. Models fit in a Bayesian context return a distribution for each parameter of interest and the mean is one summary statistic of that distribution.
* SD - Standard deviation of the posterior distribution. Similar to the Mean this is a summary statistic of the distribution representing the parameter.
* LCL - Lower Credible Limit
* UCL - Upper Credible Limit
+ The probability that the true value of the parameter is between the LCL and UCL is 0.95. However, unlike a likelihood based solution values closer to the mean are more likely than values near the tails of the distribution.
* Rhat - A diagnostic that attempts to quantify whether the model has found a reliable solution. When values of Rhat are below 1.1 the rule of thumb is to say that the model has converged.
* Rhat_UCL - The upper confidence limit of the diagnostic. Because there is uncertainty in everything that is estimated the upper confidence limit of Rhat is reported. The same rules apply here as for Rhat, but note that it may be difficult to get all of these values below 1.1.
### Help
The primary means of getting help with PopR problems, enhancements and changes is through our issue tracking system. More information can be found clicking on the Issue Tracker link above. To create a new issue you may need to create a free GitHub account first. Once you have an account simple click the large green New Issue button to get started. When you click on the button the Title and Leave a comment boxes allow you to describe your issue or idea. Please be as thorough as you possibly can when describing issues. The issue tracker also uses Markdown if you happen to be familiar. If your needs are more immediate you can contact us by via the links below or through your website by clicking on the lifering in the top-right of the page.
***
Developed by Josh Nowak, [SpeedGoat](https://www.speedgoat.io)
<img src = "./www/SG_Horizontal_Transparent_RGB.png" height = "122" width = "162">
<br>
***
<br>
<div style="padding-bottom:100px"></div>