---
title: '**secrdesign** - sampling design for spatially explicit capture--recapture'
author: "Murray Efford"
date: '`r Sys.Date()`'
output: 
  pdf_document:
    toc: true
vignette: >
  %\VignetteIndexEntry{Sampling design for spatially explicit capture--recapture}
  %\VignetteEngine{knitr::rmarkdown} 
  \usepackage[utf8]{inputenc}
---

```{r, eval = TRUE, echo=FALSE, message=FALSE}
## setwd('d:/density secr 3.1/secrdesign/vignettes')
load('runsims1.RData')
load('runsims2.RData')
options(width = 85)
```

\vspace{15pt}

The R package **secrdesign** is a set of tools to assist the
design of studies using spatially explicit capture--recapture
(SECR). It provides convenient wrappers for simulation and model
fitting functions in package **secr** to emulate many features of
the 'Simulator' module of Density 5.0 (Efford 2012). 

This document is a technical guide to the simulation aspects of **secrdesign**. 
Functions that do not rely on simulation are described in [secrdesign-tools.pdf].

We assume an understanding of estimator properties such as bias, precision, and
confidence interval coverage, and the use of Monte Carlo simulation to
predict the performance of different sampling designs. Using **secrdesign** can 
be daunting because it allows for many different combinations of data generation, 
model fitting and summary statistics. Several examples are given to indicate the
range of possibilities.

#Introduction

When designing a study you should have in mind --

(i) a population parameter you want to measure (probably density or
population size),

(ii) one or more design variables over which you have some control
(number and spacing of detectors, number of sampling occasions etc.),

(iii) some pilot data, or parameter estimates from published studies, and

(iv) a criterion by which to evaluate different designs. This is most likely
the precision of the estimates, as this in turn determines your ability
(power) to recognise changes. Cost or effort may be an explicit criterion, or
the designs may be constructed to allocate constant effort in
different ways.

We use 'relative standard error' (RSE) for the relative precision of
an estimate. This is sometimes called the coefficient of variation
(CV) of the estimate, but RSE is more appropriate. We use `accuracy'
in the sense of Williams et al. (2002 p.45) and other authors from the
United States. Accuracy combines both systematic error (bias) and
precision: one measure is the square root of the mean squared
difference between the true value and the estimate (RMSE).

Once you have sorted out (i)--(iv) you are ready to define and compare sampling scenarios. Scenarios are specified in a dataframe that is usually constructed with `make.scenarios` (see [The scenarios dataframe](#the-scenarios-dataframe)). Each scenario has an integer 'trapsindex' code that identifies a particular detector array; a list of detector arrays is constructed separately, possibly using functions such as `make.grid`.

Scenarios may be investigated in two ways --

* tabulation of expected counts etc. with `scenarioSummary`

* Monte Carlo simulation with `run.scenarios`.

Monte Carlo simulation is ultimately the more reliable and comprehensive route, but it is much slower.


\vspace{10pt}

Fig. 1 shows the sequence of steps taken in
**secrdesign** to conduct simulations and summarise the
results. Each step is described in detail in a later
section. Typically, you will use `run.scenarios()` to generate
data and fit SECR models, select some statistics with
`select.stats()`, and summarise and plot the results.

\setkeys{Gin}{height=125mm, keepaspectratio=true, trim = 0mm 0mm 0mm 10mm, clip=true} 
![fig1][fig1]  

**Fig. 1.** Core functions in **secrdesign** (yellow) and their
    main inputs and outputs. Output from the simulation function
    `run.scenarios()` may be saved as whole fitted models,
    predicted values (parameter estimates), or selected
    statistics. Each form of output requires different subsequent
    handling. The default path is shown by solid blue arrows.

##A simple example

For an introductory example we construct a simple set of
scenarios and perform some simulations. The trap layout is a default 6
x 6 grid of multi-catch traps at 20-m spacing. Density takes one of
two levels (5/ha or 10/ha) and detection parameters sigma and lambda0 are
fixed.

```{r simpex, cache = TRUE, eval = TRUE, warning = FALSE}
library(secrdesign)
scen1 <- make.scenarios(D = c(5,10), sigma = 25, g0 = 0.2)
traps1 <- make.grid(8, 8, spacing = 25)
scenarioSummary(scen1, traps1) 
```

The initial summary includes the expected number of individuals (En) and recaptures (Er), and an approximate rule-of-thumb relative standard error for estimated density (rotRSE). `scenarioSummary` approximates the default detection function (HN) by a hazard-based detection function (HHN) with a warning that is not shown here. See `?scenarioSummary` and [secrdesign-tools.pdf] for further details.

```{r simpex2, cache = TRUE}
sims1 <- run.scenarios(nrepl = 50, trapset = traps1, scenarios =
     scen1, seed = 345, fit = TRUE, fit.args = list(detectfn = 'HHN'))
```
The simulation output is an object of class `c( "estimatetables", "secrdesign", "list")`.
We use the summary method for estimatetables
to view results, and here display only the summary output (omitting a
header that describes the simulations).

```{r simpex3, eval = TRUE}
summary(sims1)$OUTPUT
```

In this example there is close agreement between the fast rule-of-thumb RSE and the simulation results.

Later sections show how to customize the summary and plot results.

# Defining scenarios

## Detector layouts

Detector layouts are specified as **secr** 'traps' objects. These
may be input from text files using `read.traps` or constructed
according to a particular geometry and spacing with functions such as
`make.grid`, `make.circle`, `make.systematic` or
`trap.builder`. See the help files for these **secr**
functions for further details. The detector type (multi-catch trap,
proximity detector etc.) is stored as an attribute of each 'traps'
object, which may also include detector-level covariates and detector 
'usage' by occasion.

Multiple layouts are combined in a single list object; component
names ('grid6x6' etc.) will be used to annotate the output.

```{r, eval = TRUE}
library(secrdesign)
mydetectors <- list(grid6x6 = make.grid(6,6),
                    grid8x9 = make.grid(8,9),
                    grid12x12 = make.grid(12,12))
```

This creates square grids with the default detector type 'multi' and
default spacing 20 m. See `?secr::make.grid` for other options.

## The scenarios dataframe

The function `make.scenarios()` constructs a dataframe in which each row
defines a simulation scenario. Its arguments (with defaults) are:

```{r,eval=FALSE}
make.scenarios (trapsindex = 1, noccasions = 3, nrepeats = 1, D, g0,
    sigma, lambda0, detectfn = 0, recapfactor = 1, popindex = 1,
    detindex = 1, fitindex = 1, groups, crosstraps = TRUE)
```

Each argument except for 'groups' and 'crosstraps' may be used to specify a range
of values for a parameter. Four ('trapsindex', 'popindex', 'detindex',
'fitindex') are actually surrogate numerical indices; the index is
used to select one component from a list of possibilities later
provided as input to `run.scenarios()`.

By default, a scenario is formed from each unique combination of the
input values (trapsindex, noccasions, nrepeats, D, g0, sigma, lambda0,
detectfn, recapfactor, popindex, and fitindex) using
`expand.grid`. For example,

```{r, eval = TRUE}
make.scenarios (trapsindex = 1:3, noccasions = 4, D = 5, g0 = 0.2, sigma = c(20,30))
```

In this case three different grids (possibly differing in number of
traps) are trapped for the same number of occasions. A more
interesting possibility is to vary the number of occasions inversely
with the number of traps. However, if we naively set e.g., `noccasions =
c(8, 4, 2)`, this would generate all combinations of grid and number of
occasions (18 different scenarios).

The alternative is to set `crosstraps = FALSE`. Then the
vectors 'trapsindex', 'noccasions', and 'nrepeats' are locked together
(if fewer values are provided in one of the vectors then it is re-used
as required), and only the combination is crossed with the remaining
parameter scenarios:

```{r, eval = TRUE}
make.scenarios (trapsindex = 1:3, noccasions = c(8,4,2), D = 5, g0 = 0.2,
                sigma = c(20,30), crosstraps = FALSE)
```

All arguments except 'fitindex' control the generation of data. Note
that 'g0' and 'lambda0' are alternatives: use the one appropriate to
the detection function specified with `detectfn' (see `?secr::detectfn` for
codes). 'D' is omitted if an inhomogeneous Poisson distribution is
specified using a mask covariate (see [Non-uniform populations](#non-uniform-populations)). D is
in animals / hectare (1 ha = $0.01 \mbox{km}^2$) and sigma is in
metres, as in **secr**.

The 'nrepeats' column refers to the number of notional
independent replicates of the particular detector layout. Notional
replicates are simulated by (invisibly) multiplying density (D) by
this factor, and ultimately dividing it into the estimate. Think of 5
grids of automatic cameras so widely separated that no animal moves
between the grids. As detections of different animals are ordinarily
modelled as independent, the entire design is equivalent to 5 times
the density of animals interacting with one grid. This breaks down, of
course, if animals compete for traps (as with single-catch traps), and
should not be used in that case except as a rough approximation.

Just as `trapsindex` serves as a placeholder for entire
detector arrays, `popindex`, `detindex` and
`fitindex` tell `run.scenarios()` which set of arguments
to select from `pop.args`, `det.args` and `fit.args` for
`sim.popn`, `sim.capthist` and `secr.fit`
respectively. These are for more advanced use: you may not need them.

When a vector of group identifiers is provided in 'groups', the population in each scenario is a set of independently sampled groups, each defined on a separate row. Groups are initially assigned the same parameter values and other settings: it is up to the user to insert group-specific values (example at [Grouped populations](#grouped-populations)).

#Running simulations

The function `run.scenarios()` generates multiple datasets and,
if requested, fits an SECR model to each one. In this section we
describe its main arguments, with additional detail on habitat masks
and customizing the output.

##Arguments of `run.scenarios()`
```{r, eval = FALSE}
run.scenarios (nrepl, scenarios, trapset, maskset, xsigma = 4,
    nx = 32, pop.args, det.args, fit = FALSE, fit.args, extractfn =
    NULL, multisession = FALSE, ncores = 1, seed = 123)
```

`nrepl` determines the number of replicate simulations. Make
this large enough that the summary statistics have enough precision to
answer your question. This is usually a matter for experimentation,
remembering that precision (SE) is proportional to the square root of
`nrepl`.

`scenarios` is the dataframe constructed with `make.scenarios()` as
described in the last section.

`trapset` is a single 'traps' object or a list of traps
objects, as described in 'Detector layouts' above.

`maskset` is an optional set of habitat masks, usually one per
detector layout. If not specified, then masks will be constructed 'on
the fly' using `secr::make.mask` with a 'buffer' of width `xsigma`
$\times$ `scenarios$sigma` and `nx` cells in the x dimension.

`pop.args` provides additional control over `sim.popn`
(see `?secr::sim.popn` for more). You may wish, for example, to set
`pop.args = list(Ndist = "fixed")` to override the default of
Poisson variation in the total number of simulated animals.

`det.args` provides additional control over
`sim.capthist` (see `?secr::sim.capthist` for more). One use is to
retain the simulated population as an attribute of the capthist object
by setting `det.args = list(savepopn = TRUE)`; another is to
set the `binomN` argument for count detectors. The
`sim.capthist` arguments `traps`, `popn`, `detectpar`,
  `detectfn` and `noccasions` are defined in the scenario or
`pop.args` and cannot be overridden by setting
`det.args`.

Use `fit = FALSE` to generate and summarise detection data without
fitting SECR models. This lets you check that your scenarios result in
reasonable numbers of detected individuals (n), detections (ndet), and
movements (nmov), before launching a full-blown simulation.

`fit.args` lets you specify how SECR models will be fitted to
the simulated data. Most default arguments of `secr.fit` may be
overridden by including them in `fit.args`. For example, to
specify a negative exponential detection function use `fit.args
  = list(detectfn =  "EX")`. If you wish to compare nspec different
model specifications then `fit.args` should be a list of lists,
one per specification, with `fitindex` taking values in the
range 1:nspec.

The use of `multisession` and `ncores` is discussed under [Additional topics](#additional-topics).

##Customising run.scenarios()

The output from `run.scenarios()` is controlled by its argument
`extractfn`. This is a short function that is applied either
(i) to each simulated raw dataset (capthist object) (`fit =
  FALSE`), or (ii) to each fitted model (`fit = TRUE`).

The default (builtin) `extractfn` (below) behaves appropriately for either
data type. It is mostly concerned with summarising raw counts when fit = FALSE.
A dataframe with no rows is returned when a model fails to fit. 
```{r}
extractfn <- function(x) {
    if (inherits(x, 'capthist')) {
        ## summarised raw data
        counts <- function(CH) {
            ## for single-session CH
            if (nrow(CH)==0) 
                c(n=0, ndet=0, nmov=0, dpa = NA)
            else {
                nmoves <- sum(unlist(sapply(moves(CH), function(y) y>0)))
                ## detectors per animal
                dpa <- if (length(dim(CH)) == 2)
                    mean(apply(abs(CH), 1, function(y) length(unique(y[y>0]))))
                else
                    mean(apply(apply(abs(CH), c(1,3), sum)>0, 1, sum))
                c(n=nrow(CH), ndet=sum(abs(CH)>0), nmov=nmoves, dpa = dpa)
            }
        }
        if (ms(x)) 
            unlist(lapply(x, counts))
        else {
            gp <- covariates(x)$group
            if (is.null(gp)) 
                counts(x)
            else 
                unlist(lapply(split(x,gp,dropnullocc=TRUE), counts))
        }            
    }
    else if (inherits(x,'secr') & (!is.null(x$fit)))
        ## fitted model:
        ## default predictions of 'real' parameters
        predict(x)
    else
        ## null output: dataframe of 0 rows and 0 columns
        data.frame()   
}
```
When `fit = FALSE`, the default output from each replicate is a vector
of 4 summary statistics:

* n - number of different individuals
* ndet - total number of detections ('captures' and 'recaptures')
* nmov - total number of detections at a detector other than the
  one where an animal was last detected
* dpa - detectors per animal (average number of detectors at which
  each animal was recorded)

When `fit = TRUE`, the default output from each replicate is
the result of applying `predict` to the fitted model, i.e. a dataframe
of 'real' parameter estimates and their standard errors etc. (an empty
dataframe is returned if model fitting fails). Nearly the same is
achieved by setting `extractfn = predict` for the 'beta'
coefficients set `extractfn = coef`. For a conditional
likelihood fit it may be appropriate to set `extractfn =
  derived`. To focus on population size in the masked region, set
`extractfn = region.N`.

The user may also choose to save the entire dataset (`fit =
  FALSE`) or the entire fitted model (secr object; `fit =
  TRUE`) for each replicate by setting `extractfn =
  identity`. For a large analysis there is a risk of exceeding memory
limits in R, and saving everything is generally not a good idea. For
most purposes it is sufficient to save a trimmed version of the fitted
model `extractfn = trim` (note **secr** defines the
function trim). However, the full model is needed for
`derived.SL` or `regionN.SL` (see [Extracting estimate tables from fitted models](#extracting-estimate-tables-from-fitted-models)).

`run.scenarios()` sets the class[^1] of its output to distinguish
among fitted models ("fittedmodels"), estimate tables from predict,
coef etc. ("estimatetables"), and numeric values ready for
summarisation ("selectdstatistics"). Simulated data saved with `fit =
FALSE, extractfn = identity` have class c("rawdata", "secrdesign",
"list"). An attribute 'outputtype' is used to make finer distinctions
among these types of output ("secrfit", "predicted", "coef",
"capthist", or "numeric"). Output from `extractfn = derived` is
treated as "predicted".

When `fit = TRUE`, analyses are performed with
`secr.fit`. Other analyses may be specified by setting
`fit = FALSE` and providing the analysis function as the value for
`extractfn`. The function should accept a `capthist' object as
input. For example, conventional closed-population estimates may be
obtained with
```{r, eval = FALSE}
closedNsim <- run.scenarios (nrepl = 10, scenarios = scen1, trapset = traps1,
     extractfn = closedN, estimator = c("null", "chao", "chaomod"))
```

This applies various *nonspatial* estimators to simulated
*spatial* samples. Named arguments of `extractfn` may be
included (here, 'estimator'); these are used for all scenarios, unlike
`fit.args` which may vary among scenarios. Summarisation of
alternative analyses will usually require careful selection of
'parameter' and 'statistics' in `select.stats`
(see [Choosing the statistics to summarise](#choosing-the-statistics-to-summarise)).

An alternative is to write your own code along these lines:
```{r, eval = FALSE}
sum1 <- function(out) {
    require(abind)
    ## collapse replicates to an array, omitting non-numeric column
    out <- do.call(abind, c(out, along = 3))[,-1,,drop = FALSE]
    ## convert array from character to numeric
    mode(out) <- "numeric"
    ## take the average over replicates (meaningless for some fields)
    apply(out, 1:2, mean, na.rm = TRUE)
    }
lapply(closedNsim$output, sum1)
```
## More on masks

A habitat mask in **secr** is a raster representation of the
region near the detectors in which the centres of detected animals may
lie. This excludes both nearby non-habitat, and habitat that is so
distant that it is implausible any animal centred there would reach a
detector. It is often convenient to define a mask to include all cells
whose centre is within a certain distance of a detector - the buffer
radius.

Within **secrdesign**, a mask is used both when generating
populations of animals with `sim.popn` and when fitting SECR
models with `secr.fit`. The extent of the mask used to generate
populations is important if you are concerned with population size
(for example, if you set `extractfn = region.N`). Then the size
of the region determines the true value of the parameter of interest
($N$), and influences its sampling variance. The extent of the mask is
less critical when density is the parameter of interest.

The default behaviour of `run.scenarios()` is to use a concave
buffer of width `xsigma` $\times$ sigma around the particular
detector layout. The 'coarseness' of the mask is determined by
`nx`; note that the default for `run.scenarios` (`nx = 32`) is
coarser than the default for `secr::make.mask` (`nx = 64`). This makes
for speed, and is fairly safe when the buffer width is well matched to
the scale of movement (we know sigma, so the default buffer
width *is* well-matched). The same mask is used both for
generating populations and fitting models.

Users may specify their own masks in the 'maskset' list argument. If
the number of masks in maskset is one or a number equal to the
number of detector layouts, then a column 'maskindex' is added
automatically to the scenarios dataframe (all 1, or equal to
trapsindex, in the two cases). Otherwise, the user must have manually
added a maskindex column to scenarios to clarify which mask should
be used with which scenario.

#Summarising simulation output

`run.scenarios` usually takes a long time to run, but having
saved its output you can quickly extract and summarise the results in
many different ways.

We saw in the previous section and Fig. 1 that the
output from `run.scenarios` for each replicate may be a fitted
model, a table of parameter estimates, or a numeric
vector. Summarisation across replicates (the `summary` method)
requires output in 'selected statistics' form, so each of the other
forms must be processed first[^2]

Look again at Fig. 1: you will see that the primary input to the
`summary` function is in the form of selected statistics. A secondary
route is to automatically extract statistics from estimates tables, as
shown by the dashed line in Fig.  1 -- we used this in [A simple
example](#a-simple-example). We now address how other forms of output
from `run.scenarios` can be processed into 'selected statistics'
form.

## Extracting estimate tables from fitted models

The methods `predict` and `coef` for the 'fittedmodels'
class and the function `derived.SL` are provided to extract
estimates of 'real' parameters from each fitted model. These are
direct analogues of `predict`, `coef` and
`derived` in **secr**. Here, they apply across all
replicates of all scenarios and return an object of class
`estimatetables`. `regionN.SL` is another possibility.

In each case, the result is a dataframe or list of dataframes for each
replicate. Rows correspond to estimated parameters (or 'R.N' and 'E.N'
for `regionN.SL`) and columns to the respective estimates,
standard errors, and confidence limits (with some variations).

The \dots argument of the functions `predict`, `coef`, `derived.SL` and `regionN.SL` lets you pass arguments such as `alpha` to the corresponding **secr** function (e.g., `predict.secr` or `derived`).

We can skip this step for the output from our simple example as it is
already in `estimatetables' form.

## Choosing the statistics to summarise

Given tabular output from `predict()` or `derived.SL()`,
we must select replicate-specific numerical quantities for further
summarisation.[^3] This is the role of `select.stats()`, which has arguments --

```{r, eval=FALSE}
select.stats(object, parameter = "D", statistics)
```

The parameter of interest defaults to density ("D"); others such as
"g0" or "sigma" may be substituted,so long as they appear in the input
object. To check which parameters are available use
```{r, eval=FALSE}
find.param(object)
```

The task of `select.stats()` is to reduce each replicate to a vector
of numeric values - we can think of the result as a replicate $\times$
values matrix for each scenario (Fig. 2). A later step (see [Summary method](#summary-method))
computes statistics (`fields') such as mean and SE for each column in
the matrix.

\vspace{20pt} 

\setkeys{Gin}{height = 120mm, keepaspectratio=true}
![fig2][fig2]

**Fig. 2.** Operation of `select.stats` for one scenario. Each replicate contributes one row to a replicates $\times$ statistics matrix.

\vspace{20pt}

\pagebreak

Here we describe the replicate-specific statistics that form the
numeric vector. These may be simply 'estimate', 'SE.estimate', 'lcl' and
'ucl' as output from `predict.secr`. Additionally, when `fit = TRUE`, we 
can include statistics derived from the estimates of a parameter (Table 1).
 To describe these we use 'true' to stand for the known value of a real
 parameter, and 'estimate' for the estimate from a particular replicate.

\vspace{6pt}

**Table 1.** Computed statistics available in `select.stats()`

| Statistic | Short name | Value |
|------:|:-----|---------|
|  Relative bias$^1$ | RB |  (estimate -- true) / true |
|  Relative SE$^2$ | RSE | SE.estimate / estimate |
|  Absolute deviation | ERR | abs(estimate -- true) |
|  Coverage indicator | COV | (estimate $>$ lcl) \& (estimate $<$ ucl) |

1. Also called 'normalized bias'

2. Also called 'coefficient of variation'

We use ('lcl', 'ucl') to represent a confidence interval for
'estimate'. Usually these are 95\% intervals, but the level may be
varied by setting the argument 'alpha' in `predict` (e.g.,
alpha = 0.1 for a 90\% interval). Intervals from `predict.secr`
are symmetrical on the link scale, and hence asymmetrical on the
natural scale. Note also the argument `loginterval` in
`derived`; the default `loginterval = TRUE` gives an
asymmetrical interval on the natural scale.

The coverage indicator COV is a binary value (0/1); this becomes
interesting later when averaged over a large number of replicates to
give a coverage proportion. The absolute deviation ERR also comes into its
own later as the basis for RMSE. In a sense the same is true of
replicate-specific RB: RB should be reported only as an average over a
large number of replicates.

Returning to our simple example, we apply `select.stats()` to
focus on the density parameter "D".

```{r, eval = TRUE}
stats1 <- select.stats(sims1, parameter = "D", statistics = c("estimate",
   "lcl", "ucl", "RB", "RSE", "COV"))
lapply(stats1$output, head, 4)
```
The two scenarios yield two replicates $\times$ statistic matrices,
from which we display the first 4 rows.

## Disposing of rogue values

Simulation output may contain rogue values due to idiosyncracies of
model fitting. For example, nonidentifiability due to inadequate data
can result in spurious extreme estimates of the sampling
variance. The median (chosen as a field value in `summary`)
is recommended as a robust alternative to the mean when there are some
extreme estimates. Another way to deal with the problem is to set statistics to NA when a
simulation fails. The function `validate` sets selected 'target'
statistics to NA for replicates in which another test statistic is
out-of-range or NA:

```{r,eval=FALSE}
x <- validate (x, test, validrange = c(0, Inf), targets = test)
```

The permissable bounds are usually arbitrary, and
the method should be used with care. The keyword "all" may be used
for `targets` to indicate all columns.

`validate` accepts a selectedstatistics object (x) as input
and returns a modified selectedstatistics object as output. See
[Learned trap response](#learned-trap-response) for an application.

##Summary method

The `summary` method for 'selectedstatistics' objects reports both
header information on the simulation scenarios and user-selected
summaries of the pre-selected statistics.

```{r,eval=FALSE}
summary (object, dec = 5, fields = c("n", "mean", "se"), alpha = 0.05,
    type = c("list", "dataframe", "array"), ...)
```

Here the summary statistics are called 'fields' to distinguish them
from the 'statistics' in each column of the numeric replicate $\times$
value matrix for each scenario (see [Choosing the statistics to
summarise](#choosing-the-statistics-to-summarise)). The task of the
summary method is to compute the `field' value for each 'statistic',
summarising across replicates to give a 'statistic' $\times$ 'field'
matrix for each scenario. The choice of 'fields' is shown in Table 2.

**Table 2.** Statistic fields available in the `summary` method
  for selectedstatistics objects.
  
| Field | Description |
|------:|:-----|
| n | number of non-missing values |
|  mean | mean |
|  se | standard error |
|  sd | sample standard deviation |
|  min | minimum |
|  max | maximum |
|  lcl | lower $100(1 - \alpha)$ \% confidence limit|
|  ucl | upper $100(1 - \alpha)$ \% confidence limit|
|  rms | root mean square |
|  median | median |
|  qxxx | xxx/1000 quantile |
|  qyyy | yyy/1000 quantile |


The summary fields 'lcl' and 'ucl' are for a simple Wald interval
($\hat \mu + z_{\alpha/2} \widehat{\mbox{SE}}(\hat \mu), \hat \mu + z_{1 -\alpha/2}
\widehat{\mbox{SE}}(\hat \mu)$) where $z_\alpha$ is the $100\alpha$-percentile of a
standard normal distribution (e.g., $z_{0.975} = 1.96$). [Do not confuse
these with the confidence limit statistics of the same name that are
symmetrical only on the link scale].

Quantiles are specified as 'qxxx' and 'qyyy' where xxx and yyy are
integers between 1 and 999 corresponding to quantiles 0.001 to
0.999. For example, 'q025' refers to the 2.5\% quantile.

Applying the 'rms' field to the absolute deviation of an estimate
(ERR) provides the root-mean-square-error 'RMSE'.

To recap -- a summary value is reported for each combination of a
selected statistic, computed for each replicate, and a 'field' that
summarises the statistic across replicates, potentially resulting in a
table with this structure:

```{r,echo=FALSE, comment=''}
bullet <-  '*' ## rawToChar(as.raw(149))
tmp <- matrix(bullet, nr=8, ncol=12)
dimnames(tmp) <- list(Statistics = c("estimate","SE.estimate","lcl","ucl","RB","RSE","ERR","COV"),
Fields = c("n","mean","se","sd","min","max","lcl","ucl","rms","median","q025","q975"))
tmp[1:6,9] <- ""
tmp[3:5,7:8] <- ""
tmp[8,7:12] <- ""
print(tmp, qu=F)
```

Cells are left blank for combinations that are unlikely to be
meaningful. 'rms' is useful with ERR (i.e. RMSE), but not when
applied to other statistics. 'n', 'mean' and 'se' summarise the COV
indicator, but other potential summaries are (almost) meaningless.

Apply this to the selected statistics from our simple example:
```{r, eval = TRUE}
summary(stats1, c('n', 'mean', 'se', 'median'))
```

## Plot method

Use the plot method to visualize the distributions of
'selectedstatistics' that you have simulated. You may plot either (i)
histograms of the selected statistics (`type = "hist"`) or (ii) the
estimate and confidence interval for each replicate (`type = "CI"`). One
histogram is plotted for each combination of scenario and statistic --
you may want to select a subset of scenarios and statistics, and use
the graphics options mfcol or mfrow to control the layout.  For `type =
"CI"` the statistics must include 'estimate', 'lcl' and 'ucl' (or
'beta', 'lcl' and 'ucl' if `outputtype = "coef"`).

```{r, eval=FALSE}
par(mfrow = c(2,2))
plot(stats1, type = "hist", statistic = "estimate")
plot(stats1, type = "CI")
```
```{r, echo=FALSE, eval=FALSE}
png(file='d:/density secr 2.10/secrdesign/vignettes/secrdesign-fig3.png',
    width = 850, height = 800)
par(mfrow = c(2,2), cex=1.2)
plot(stats1, type = "hist", statistic = "estimate")
plot(stats1, type = "CI")
dev.off()
```

\setkeys{Gin}{height=120mm, keepaspectratio=true, trim = 0mm 5mm 5mm 5mm, clip = true}
![fig3][fig3]

**Fig. 3.** Plot method applied to a 2-scenario 'selectedstatistics' object with
    `type = "hist"` (top) and `type = "CI"` (bottom)
    
# Additional topics

## Parallel processing

Setting `ncores > 1` causes `run.scenarios()` to run
separate scenarios on separate cores. This uses the R package
**parallel**. Technically, it relies on Rscript, and
communication between the master and worker processes is via
sockets. As stated in the R **parallel** documentation "Users of
Windows and Mac OS X may expect pop-up dialog boxes from the firewall
asking if an R process should accept incoming connections". It appears
to be safe to accept these.

Use `parallel::detectCores()` to get an idea of how many cores
are available on your machine; this may (in Windows) include virtual
cores over and above the number of physical cores. If you use the
maximum available cores for `run.scenarios()` then expect any
other processes on the machine to slow down!

Running one scenario per core is suboptimal if scenarios differ widely
in how long they take to run: the system waits for the slowest. There
is no way around this limitation in **secrdesign**.

Random number generation for multiple cores uses the "L'Ecuyer-CMRG""
random number generator as described in `?RNG`.

## Shortcut evaluation of precision

The asymptotic variance (and hence RSE) of a maximum likelihood
estimate is typically obtained from the curvature of the likelihood
computed numerically at the fitted value of the parameter(s) (i.e., at
the MLE). Fitting SECR models is slow. An alternative estimate of
the RSE that is sufficient for most purposes may be got from the
curvature of the likelihood computed at the known 'true' value(s) of
the parameter(s). This is much faster as it does not require the model
to be fitted.

`secr.fit` may be 'tricked' into providing this variance
estimate by setting `method = "none"` and providing the true
values as the `start` vector. `run.scenarios()` makes this
easy by assuming that if you specify `method = "none"` you wish
to use `start = "true"`. However, this works only when there is
a 1:1 relationship between 'beta' and 'real' parameters; it does
not work when 'recapfactor' is specified.

```{r, eval = FALSE}
sims2 <- run.scenarios(nrepl = 50, trapset = traps1, scenarios = scen1,
    fit = TRUE, fit.args = list(method = "none"))
```
```{r, eval = TRUE}
summary(sims2)
```

Each estimate of RSE is essentially the same as before (see `summary(stats1)` in [Summary method](#summary-method)), but the run time is reduced by nearly 80\%. Note the true value of density appears
as a constant 'estimate' in the summary. Care is needed with this
method as its performance in extreme cases has not been investigated
fully.

## Non-uniform populations

The simulated population by default has a uniform (homogeneous) Poisson
distribution. To generate and sample from a spatially inhomogeneous
population we use the 'IHP' option for argument `model2D` in
`secr::sim.popn`. This involves three steps:

1. Create a habitat mask object with the desired extent.
2. Add to the mask a covariates dataframe with one or more columns
  defining pixel-specific densities.
3. In `run.scenarios()` specify a list of pop.args including
  `model2D = "IHP"` and `D = "XX"` where XX is the
  name of the particular mask covariate you wish to use for density,
  and name your mask in the `maskset' argument.

A full demonstration is given in the Appendix ([Non-uniform possums](#non-uniform-possums)).

To visualize simulated populations you should set `savepopn =
  TRUE` in det.args and later extract the popn attribute from the
capthist object (for example, with a custom extractfn).

To compare several inhomogeneous distributions, specify several
pop.args lists and use the popindex argument in
`make.scenarios()`. The distribution may be varied simply by
using the `sim.popn()` argument `D` to select different
covariates of one mask.

The columns 'nrepeats' and 'D' in the scenarios argument of `run.scenarios` are
ignored when `model2D = "IHP"`. 'D' is replaced by the average
density over the mask, which is used as the 'true' value of density in
computing RB, RSE etc. in summaries. For stratified analyses you will
have to define your own extractfn.

## Linear habitat

**secrdesign** may be used to simulate sampling of populations in
linear habitats as implemented in R package **secrlinear**. The
procedure is similar to that for non-uniform (inhomogeneous Poisson)
populations as described in the previous section: one or more masks must
be provided, but in this case they will be of type 'linearmask'.

The steps are:

1. Create linear habitat mask objects with the desired extent.
2. Create detector layouts and a scenario dataframe as usual.
3. Add a `maskindex' column to the scenarios dataframe identifying which mask is
  to be used in each scenario (may be omitted for a single mask).
4. In `run.scenarios()` specify your mask(s) in the
  `maskset` argument.

Density may be specified in the scenario dataframe as a constant
number of animals per km, and in this case the 'nrepeats' column is respected.

Density also may be modelled as inhomogeneous, i.e. varying along the
length of the linear mask. The mechanism for this is like that for two
dimensions: use a list of pop.args including `model2D =
  "linear"` and `D = "XX"` where XX is the name of the
particular mask covariate you wish to use for density. In this case, the
columns 'nrepeats' and 'D' in the scenarios dataframe are
ignored, as for the 'IHP' option.

With a linear mask, `run.scenarios` defaults to
`secrlinear::networkdistance` for the distance function
(`secr.fit` argument `details$userdist`).

##Splitting data generation and model fitting

Each new detector layout or new model specification (in a
`fit.args` list) defines a new scenario. The default procedure
is to generate new data (both animal locations and simulated detection
histories) for each scenario. To compare different models applied to
the same dataset, save raw data from an initial call to
`run.scenarios()` with `fit = FALSE, extractfn =
  identity`, and separately fit a list of models with
`fit.models`. You can also peek at the raw data with the
`summary` method.

```{r, eval = FALSE}
scen3 <- make.scenarios(D = c(5,10), sigma = 25, g0 = 0.2)
traps3 <- make.grid()
raw3 <- run.scenarios(nrepl = 50, trapset = traps3, scenarios =
    scen3, fit = FALSE, extractfn = identity)
summary(raw3)
## fit and summarise models
sims3 <- fit.models(raw3, fit.args = list(list(model = g0~1),
    list(model = g0~T)), fit = TRUE, ncores = 4)
summary(sims3)
```

Here, `scen3` describes two scenarios, and in the call to
`fit.models` each of these is split into two new scenarios, one
for each component of `fit.args`. 

The arguments 'scen' and 'repl' of `fit.models` let you select particular 
scenarios and replicates for fitting (**secrdesign** $\ge$ 2.3.0).

It is not possible within **secrdesign** precisely to evaluate
the application to the same animal distribution (population) of
differing detector layouts or specifications for the fitted model (cf
Fewster and Buckland 2004). Comparisons inevitably include variance
from the varying number and placement of animals, and the sampling
process; this variance may be reduced by fixing the number of
individuals (`pop.args = list(Ndist = "fixed")`).

##Populations with sub-classes or multiple sessions

Simulation of structured populations is introduced in **secrdesign** 2.2.0 and is still experimental. 

The 'groups' argument of `make.scenarios` replicates rows so that within a scenario there is one row for each group. Group-specific parameter values are inserted by the user. 

Rows sharing the same scenario number are recognised by `run.scenarios` as subclasses (groups). Each subclass is generated as a separate capthist object. The argument `multisession` determines whether the capthist objects corresponding to subclasses are pooled for analysis (using `secr::rbind.capthist`) or treated as multiple distinct sessions (using `secr::MS.capthist`).

The original sub-class of each individual is recorded as an individual covariate named "group". This is a factor. It may ignored in the fitted model, or used in such `secr.fit` arguments as 'groups' and 'hcov', or included in models directly as an individual covariate when `CL = TRUE`. (If the output from `predict.secr` is not a single dataframe then you will have to write a custom `extractfn`).

An example is given in the Appendix ([Grouped populations](#grouped-populations)).

#Limitations, tips and troubleshooting

**secrdesign** has some limitations (Surprise!).

1. A progress message is output only on the completion of each
  scenario, which can be annoying, and when using multiple cores even
  this message is lost. It is strongly recommended that you start by
  generating summaries of raw data only (`run.scenarios()` with
  `fit = FALSE`), and confirm that your scenarios are realistic
  by reviewing the simulated number of detected individuals, total
  number of detections, etc. If these are inadequate or
  unrealistically large then there's no point going on. Then, try
  fitting with just a few replicates on one core to be sure you have specified the
  model you intended and to assess the likely run time. Only then
  submit a run with a large number of replicates on multiple cores.

2. Only 2-parameter detection functions are allowed for data
  generation. This excludes the hazard-rate function, the
  cumulative gamma, and some others.

3. The default `extractfn` does does not handle models that
  produce more than one estimates table per replicate (e.g., finite
  mixture models). A custom `extractfn` is needed; it should
  either produce a numeric vector of 'selected statistics' or mimic
  single-dataframe output from `predict()`.

4. The function `secr::sim.capthist` that generates
detection histories for **secrdesign** has limited capacity for
simulating temporal, behavioural or other heterogeneity in detection
probability. Heterogeneity may be simulated as discrete subclasses (see preceding section). Only a simple permanent learned response is allowed in `run.scenarios` ('recapfactor'). 

5. As noted before, the same mask is used for generating
  populations and fitting models. It would be possible to replace the
  maskset component of a 'rawdata' object before running
  `fit.models`, but this is not recommended.

6. It is easy to forget the random number seed. Consider replacing
  the default value.

7. The method for fitting a fixed-N model (`distribution =
    binomial`) is somewhat fragile: it can fail when given a start
  value for D that is less than the minimum density observed (i.e.
  the number of distinct individuals divided by the mask area). This
  can easily happen when a population is simulated with
  `pop.args = list(Ndist = "poisson")` (the default) and
  sampled with high detection probability, but `secr.fit` is
  called with (`distribution = "binomial"`). The solution is to
  use `pop.args = list(Ndist = "fixed")`.

8. If your summaries do not include enough significant digits, increase
the 'dec' argument of `summary.selectedstatistics`!

#References

Borchers, D. L. and Efford, M. G. (2008) Spatially explicit
   maximum likelihood methods for capture--recapture
   studies. *Biometrics* **64**, 377--385.

Cooch, E. and White, G. (eds) (2014) *Program MARK: A
    Gentle Introduction*. 13th edition. Available online at
  \url{http://www.phidot.org/software/mark/docs/book/}.

Efford, M. G. (2012) DENSITY 5.0: software for spatially
    explicit capture--recapture}.  Department of Mathematics and
  Statistics, University of Otago, Dunedin, New Zealand
  \url{http://www.otago.ac.nz/density}.

Efford, M. G., Borchers D. L. and Byrom, A. E. (2009) Density
  estimation by spatially explicit capture--recapture:
  likelihood-based methods. In: D. L. Thomson, E. G. Cooch,
  M. J. Conroy (eds) *Modeling Demographic Processes in Marked
    Populations*. Springer. Pp 255--269.

Efford, M. G., Dawson, D. K. and Borchers, D. L. (2009)
  Population density estimated from locations of individuals on a
  passive detector array. *Ecology* **90**, 2676--2682.

Efford, M. G. and Fewster, R. M. (2013) Estimating population
  size by spatially explicit capture--recapture. *Oikos*
  **122**, 918--928.

Fewster, R. M. and Buckland, S. T. (2004) Assessment of
   distance sampling estimators. In: S. T. Buckland,
   D. R. Anderson, K. P. Burnham, J. L. Laake, D. L. Borchers and
   L. Thomas (eds) *Advanced distance sampling*. Oxford
   University Press, Oxford, U. K. Pp. 281--306.

Williams, B. K., Nichols, J. D. and Conroy, M. J. (2002)
  *Analysis and management of animal populations*. Academic
  Press, San Diego

\pagebreak

#Appendix. Examples

Here we give some annotated examples of simulation code and selected
output. Running this code with reduced `nrepl`, and viewing the
output, will give you an idea of how `secrdesign` works.

## Multiple grids, varying number of occasions

This is the example from the main text, slightly extended
```{r, eval = FALSE}
traps4 <- list(grid6x6 = make.grid(6,6),
               grid8x9 = make.grid(8,9),
               grid12x12 = make.grid(12,12))
scen4 <- make.scenarios (trapsindex = 1:3, noccasions = c(8,4,2), D = 5,
    g0 = 0.2, sigma = c(20,30), crosstraps = FALSE)

sims4 <- run.scenarios(nrepl = 500, trapset = traps4, scenarios =
     scen4, fit = FALSE, ncores = 3)
```
```{r, eval = TRUE}
class(sims4)        ## just peeking
find.stats(sims4)   ## just peeking
summary(sims4)
```
```{r, eval = FALSE}
par(mfrow=c(4,3))
plot(sims4, statistic = "n", breaks = seq(0,80,5))      ## animals
plot(sims4, statistic = "nmov", breaks = seq(0,140,5))  ## movements
```
```{r, eval=FALSE, echo=FALSE}
png(file='d:/density secr 2.10/secrdesign/vignettes/secrdesign-fig4.png',
    width = 850, height = 800)
par(mfrow = c(4,3), cex=1)
plot(sims4, statistic = "n", breaks = seq(0,80,5))  ## number of animals
plot(sims4, statistic = "nmov", breaks = seq(0,140,5))
dev.off()
```
\setkeys{Gin}{height=140mm, keepaspectratio=true}
![fig4][fig4]

**Fig. 4.** Numbers of individuals (n) and movements (nmov) from six scenarios differing in trap number, number of sampling occasions and scale of movement. 

##Learned trap response

Here we assess the bias in $\hat D$ caused by ignoring a learned trap response.

```{r,eval = FALSE}
## set up and run simulations
traps5 <- list(grid6x6 = make.grid(6,6),
               grid10x10 = make.grid(10,10))
scen5 <- make.scenarios (trapsindex = 1:2, noccasions = 5, D = 5,
    g0 = 0.2, sigma = 25, recapfactor = c(0.5, 1, 2), fitindex = 1:2)
sims5 <- run.scenarios(nrepl = 500, trapset = traps5, scenarios =
    scen5, fit = TRUE, fit.args = list(list(model = g0 ~ 1),
    list(model = g0 ~ b)), ncores = 6)
```
```{r, eval = TRUE}
## select statistics and throw out any replicates with SE > 100
## (there is one -- see reduced n in output for scenario 11)
stats5 <- select.stats(sims5)
stats5 <- validate(stats5, "SE.estimate", c(0,100), "all")
sum5 <- summary(stats5, fields = c("n","mean","se","lcl","ucl", "median"))
```
```{r, eval = FALSE}
## plot
plot(c(0.5,6.5), c(-0.2,0.4), type = "n", xlab = "Scenario", ylab = "RB(D-hat)")
for (i in 1:12) {
    xv <- if (i<=6) i else (i-6)+0.05
    segments (xv, sum5$OUTPUT[[i]]["RB","lcl"], xv, sum5$OUTPUT[[i]]["RB","ucl"])
    ptcol <- if (i<=6) "white" else "black"
    points(xv, sum5$OUTPUT[[i]]["RB","mean"], pch = 21, bg = ptcol)
}
abline(h = 0, col="red")
text(c(1.5,3.5,5.5), rep(0.38,3), paste("recapfactor", c(0.5,1,2), sep = " = "))
```

```{r, eval = FALSE, echo=FALSE}
## plot
png(file='d:/density secr 2.10/secrdesign/vignettes/secrdesign-fig5.png',
    width = 850, height = 500)
par(mar = c(4,4,1,1), cex = 1.4)
plot(c(0.5,6.5), c(-0.2,0.4), type = "n", xlab = "Scenario", ylab = "RB(D-hat)")
for (i in 1:12) {
    xv <- if (i<=6) i else (i-6)+0.05
    segments (xv, sum5$OUTPUT[[i]]["RB","lcl"], xv, sum5$OUTPUT[[i]]["RB","ucl"])
    ptcol <- if (i<=6) "white" else "black"
    points(xv, sum5$OUTPUT[[i]]["RB","mean"], pch = 21, bg = ptcol)
}
abline(h = 0, col="red")
text(c(1.5,3.5,5.5), rep(0.38,3), paste("recapfactor", c(0.5,1,2), sep = " = "))
dev.off()
```
\setkeys{Gin}{height=90mm, keepaspectratio=true}
![fig5][fig5]

**Fig. 5** Relative bias of SECR density estimate from null model
    (filled circles) and g0$\sim$b model (open circles) when
    data were generated with negative, zero, or positive learned response.

```{r, eval = TRUE}
## look at extended output
sum5
```

##Non-uniform possums

Code to illustrate the use of homogeneous and inhomogeneous density models.

```{r, eval = FALSE}

## add covariates to builtin secr object possummask
## D1 is homogeneous density
## D2 is artificial SW - NE gradient in density

xy <- apply(possummask,1,sum) / 500
covariates(possummask)[, "D1"] <- 2
covariates(possummask)[, "D2"] <- xy - mean(xy) + 2.5

## Note that this object already had a covariates dataframe
## -- if it didn't we would use
## covariates(possummask) <- data.frame ( D1 = ..., D2 = ...)

## specify scenarios
## anticipate two different sets of arguments for sim.popn
## with popindex = 1:2

scen6 <- make.scenarios (g0 = 0.2, sigma = 45, noccasions = 5,
    popindex = 1:2)

## specify alternate models for distribution of animals

poplist <- list(list(model2D = "IHP", D = "D1"),
                list(model2D = "IHP", D = "D2"))

## run scenarios and summarise
## we use the trap layout from the builtin secr object possumCH

sims6 <- run.scenarios (500, scen6, traps(possumCH), possummask,
    pop.args = poplist)
```
```{r, eval = TRUE}
summary(sims6)
```

To visualize individual realisations of the distribution of animals,
use `fit = FALSE` (the default), `det.args = list(savepopn = TRUE)`, 
and save the entire capthist object (`extractfn = identity`). Here we
create a single replicate.

```{r,eval = FALSE}
sims6a <- run.scenarios (1, scen6, traps(possumCH), possummask,
    pop.args = poplist, det.args = list(savepopn = TRUE),
    extractfn = identity)
```
```{r, eval = FALSE}
## sims6a$output is now a list (one component per scenario) of lists
## (one component per replicate) of simulated capthist objects, each
## with its 'popn' object embedded as an attribute

pop1 <- attr(sims6a$output[[1]][[1]], "popn")
pop2 <- attr(sims6a$output[[2]][[1]], "popn")
par(mfrow = c(1,2), mar=c(1,1,1,6))
plot(possummask, covariate = "D1", dots = FALSE, breaks = 0:6)
plot(traps(possumCH), detpar = list(col = 'green', pch = 15), add = TRUE)
plot(pop1, frame = FALSE, add = TRUE, col = "blue", pch = 16, cex = 0.6)
plot(possummask, covariate = 'D2', dots = FALSE, breaks = 0:6)
plot(traps(possumCH), detpar = list(col = 'green', pch = 15), add = TRUE)
plot(pop2, frame = FALSE, add = TRUE, col = "blue", pch = 16, cex = 0.6)
```
```{r, eval = FALSE}
## click on map to display height; Esc to exit
spotHeight(possummask, prefix = "D2")
```
```{r, eval = FALSE}
pop1 <- attr(sims6a$output[[1]][[1]], "popn")
pop2 <- attr(sims6a$output[[2]][[1]], "popn")
png(file='d:/density secr 2.10/secrdesign/vignettes/secrdesign-fig6.png',
    width=850, height=400)
par(mfrow = c(1,2), mar=c(1,1,1,6), cex=1.25)
plot(possummask, covariate = "D1", dots = FALSE, breaks = 0:6)
plot(traps(possumCH), detpar = list(col = 'green', pch = 15), add = TRUE)
plot(pop1, frame = FALSE, add = TRUE, col = "blue", pch = 16, cex = 0.6)
plot(possummask, covariate = 'D2', dots = FALSE, breaks = 0:6)
plot(traps(possumCH), detpar = list(col = 'green', pch = 15), add = TRUE)
plot(pop2, frame = FALSE, add = TRUE, col = "blue", pch = 16, cex = 0.6)
dev.off()
```

\setkeys{Gin}{height=90mm, keepaspectratio=true, trim = 5mm 5mm 5mm 10mm, clip=true}
![IHPpossums][fig6]

**Fig. 6.** Simulated homogeneous (left) and inhomogeneous (right)
    distributions of brushtail possums at Waitarere, New
    Zealand. Traps in green (each hollow grid 180 m square).
    
    
##Code for linear habitat

Code to illustrate the use of linear habitat models. This assumes you
have the package **secrlinear**, which is not yet on CRAN.

```{r, eval = FALSE}
library(secrlinear)

## create a habitat geometry
x <- seq(0, 4*pi, length = 200)
xy <- data.frame(x = x*100, y = sin(x)*300)
linmask <- read.linearmask(data = xy, spacing = 5)

## define two possible detector layouts
trp1 <- make.line(linmask, detector = 'proximity', n = 80,
                  startbuffer = 200, endbuffer = 200, by = 30)
trp2 <- make.line(linmask, detector = 'proximity', n = 40,
                  startbuffer = 200, endbuffer = 200, by = 60)
trplist <- list(spacing30 = trp1, spacing60 = trp2)

## create a scenarios dataframe
scen7 <- make.scenarios(D = c(50,200), trapsindex = 1:2,
                        sigma = 25, g0 = 0.2)

## we specify a mask, rather than construct it 'on the fly',
## and must manually add column 'maskindex' to the scenarios
scen7$maskindex <- c(1,1)

## we will use a non-Euclidean distance function...
det.arg <- list(userdist = networkdistance)

## run the scenarios and summarise results
sims7 <- run.scenarios(nrepl = 500, trapset = trplist,
    maskset = linmask, det.args = list(det.arg),
    scenarios = scen7, seed = 345, fit = FALSE)
```
```{r, eval = TRUE}
summary(sims7)
```

##Grouped populations

This example demonstrates the simulation of a structured population - nominally females and males with a 2:1 sex ratio.

First we form a scenarios dataframe with 2 groups and two levels of 'noccasions', and manually adjust the 'male' parameter values:

```{r, eval = TRUE}
scen8 <- make.scenarios (D = 8, g0 = 0.3, sigma = 30, noccasions = c(4,8), groups = c('F','M'))
male <- scen8$group == 'M'
scen8$D[male] <- 4
scen8$g0[male] <- 0.2
scen8$sigma[male] <- 40
scen8[,1:8]
```

Next we set up a trapping grid, a habitat mask, and a customized extract function for multi-class output from a hybrid mixture model:
```{r, eval = TRUE}
grid <- make.grid(8, 8, spacing = 30)
mask <- make.mask(grid, buffer = 160, type = 'trapbuffer')
## extracts total density and proportion from output for the first group (F)
exfn <- function(x) {    
    if (inherits(x, 'secr') & !is.null(x$fit)) {
        pred <- predict(x)
        pred[[1]][c('D','pmix'),]
    }
    else data.frame()
}
```
It is desirable to check the raw simulations. We specify the mask, rather than relying on one constructed automatically, to ensure the same mask is used for both females and males.
```{r, eval = 2}
raw8 <- run.scenarios(20, scen8, trapset = list(grid), fit = FALSE, maskset = list(mask))
summary(raw8)
```
Now fit the models and check the summary output for density ('D') and sex ratio (proportion female 'pmix') without repeating the header information.
```{r, eval = FALSE}
sims8 <- run.scenarios(20, scen8, trapset = list(grid), fit = TRUE, extractfn = exfn,
                       fit.args = list(model = list(g0~h2, sigma~h2), hcov = 'group'),
                       maskset = list(mask))
```

```{r, eval = TRUE}
summary(select.stats(sims8,'D'))$OUTPUT
summary(select.stats(sims8,'pmix'))$OUTPUT
```

```{r, eval = FALSE, echo = FALSE}
save(sims1, sims2, 
     file = 'd:/density secr 2.10/secrdesign/vignettes/runsims1.RData')
```
```{r, eval = FALSE, echo = FALSE}
save(raw3, sims3, sims4, sims5, sims6, sims6a, sims7, raw8, sims8,
     file = 'd:/density secr 2.10/secrdesign/vignettes/runsims2.RData')
```
[fig1]:secrdesign-fig1.png
[fig2]:secrdesign-fig2.png
[fig3]:secrdesign-fig3.png
[fig4]:secrdesign-fig4.png
[fig5]:secrdesign-fig5.png
[fig6]:secrdesign-fig6.png

[^1]:the full class is actually c(x, "secrdesign"", "list") where x is as described.

[^2]:Processing happens silently using default settings of
`select.stats()` when `summary` is applied directly to 'estimate
tables' output.

[^3]: If `run.scenarios()` has been used with `fit = FALSE`, then the
output from each replicate is probably already in the form of selected
statistics (the default raw data summaries 'n', 'ndet','nmov' and
'dpa') and `select.stats()` is not relevant. The same may also apply
with a user-provided `extractfn` when `fit = TRUE`.

[secrdesign-tools.pdf]: http://www.otago.ac.nz/density/pdfs/secrdesign-tools.pdf
