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
- 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.
- 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. 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).
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.
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.
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.
Run - MCMC Controls
- Burnin Length - Models fit using MCMC
methods 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
