Movatterモバイル変換

Type:	Package
Title:	Spatially Explicit Capture-Recapture
Version:	5.3.0
Date:	2025-09-27
Description:	Functions to estimate the density and size of a spatially distributed animal population sampled with an array of passive detectors, such as traps, or by searching polygons or transects. Models incorporating distance-dependent detection are fitted by maximizing the likelihood. Tools are included for data manipulation and model selection.
Depends:	R (≥ 3.5.0), methods
Imports:	abind, graphics, grDevices, MASS, mgcv, mvtnorm, nlme,parallel, raster (≥ 3.5-15), Rcpp (≥ 0.12.14), RcppNumerical,RcppParallel (≥ 5.1.1), sf, stats, stringr, terra (≥ 1.5-12),tools, utils
Suggests:	gdistance, igraph, knitr, readxl, rmarkdown, sp, spatstat (≥3.3-3), spatstat.geom, spatstat.random, spcosa, spsurvey (≥5.3.0), testthat
LinkingTo:	BH, Rcpp, RcppEigen, RcppNumerical, RcppParallel
VignetteBuilder:	knitr
License:	GPL-2 |GPL-3 [expanded from: GPL (≥ 2)]
LazyData:	yes
LazyDataCompression:	xz
SystemRequirements:	GNU make
URL:	https://www.otago.ac.nz/density/,https://github.com/MurrayEfford/secr/
NeedsCompilation:	yes
Packaged:	2025-09-27 10:31:58 UTC; murra
Author:	Murray Efford [aut, cre], Philipp Jund [ctb] (faster transect search and spacing), David Fletcher [ctb] (overdispersion), Yan Ru Choo [ctb] (goodness-of-fit)
Maintainer:	Murray Efford <murray.efford@otago.ac.nz>
Repository:	CRAN
Date/Publication:	2025-09-27 21:20:02 UTC

Spatially Explicit Capture–Recapture Models

Description

Functions to estimate the density and size of a spatiallydistributed animal population sampled with an array of passivedetectors, such as traps, or by searching polygons or transects.

Details

Spatially explicit capture–recapture is a set of methods for studyingmarked animals distributed in space. Data comprise the locations ofdetectors (traps, searched areas, etc. described in an object of class‘traps’), and the detection histories of individually markedanimals. Individual histories are stored in an object of class‘capthist’ that includes the relevant ‘traps’ object.

Models for population density (animals per hectare) and detection aredefined insecr using symbolic formula notation. Density modelsmay include spatial or temporal trend. Possible predictors for detectionprobability include both pre-defined variables (t, b, etc.)corresponding to ‘time’, ‘behaviour’ and other effects), anduser-defined covariates of several kinds. Habitat is distinguished fromnonhabitat with an object of class ‘mask’.

Models are fitted insecr by maximizing either the full likelihoodor the likelihood conditional on the number of individuals observed(n). Conditional likelihood models allow continuous individual covariates fordetection. A model fitted withsecr.fit is an objectof classsecr. Generic methods (plot, print, summary, etc.) areprovided for each object class.

A link at the bottom of each help page takes you to the help index. Some vignettes complement the help pages:

This reference includes material previously covered in separate vignettes:

Efford, M. G. (2025) The SECR book. A handbook of spatially explicit capture–recapture methods. Version 1.0.https://murrayefford.github.io/SECRbook/ and Zenododoi:10.5281/zenodo.15109937.

The datasetscaptdata andovenbird include examples of fittedmodels. For models fitted to other datasets seesecr-version4.pdf Appendix 2.

Add-on packages extend the capability ofsecr and aredocumented separately.secrlinear enables the estimation of lineardensity (e.g., animals per km) for populations in linear habitats suchas stream networks(secrlinear-vignette.pdf).secrdesignenables the assessment of alternative study designs by Monte Carlosimulation; scenarios may differ in detector (trap) layout, samplingintensity, and other characteristics(secrdesign-vignette.pdf).ipsecr fits some awkward models (e.g., for single-catch traps) by simulation and inverse prediction (ipsecr-vignette.pdf).openCR fits open population models, both non-spatial and spatial(openCR-vignette.pdf).

The analyses insecr extend those available in the softwareDensity (seewww.otago.ac.nz/density/for the most recent version of Density). Help is available on the‘DENSITY | secr’ forum at www.phidot.org andthe Google groupsecrgroup. Feedbackon the software is also welcome, including suggestions for additionaldocumentation or new features consistent with the overall design.

Author(s)

Murray Effordmurray.efford@otago.ac.nz

References

Borchers, D. L. and Efford, M. G. (2008) Spatially explicit maximumlikelihood methods for capture–recapture studies.Biometrics64, 377–385.

Borchers, D. L. and Fewster, R. M. (2016) Spatial capture–recapture models.Statistical Science31, 219–232.

Efford, M. G. (2004) Density estimation in live-trapping studies.Oikos106, 598–610.

Efford, M. G. (2011) Estimation of population density by spatiallyexplicit capture–recapture with area searches.Ecology92, 2202–2207.

Efford, M. G., Borchers D. L. and Byrom, A. E. (2009) Density estimationby spatially explicit capture-recapture: likelihood-based methods. In:D. L. Thomson, E. G. Cooch and M. J. Conroy (eds)ModelingDemographic Processes in Marked Populations. Springer, New York. Pp.255–269.

Efford, M. G., Borchers D. L. and Mowat, G. (2013) Varying effort incapture–recapture studies.Methods in Ecology and Evolution4, 629–636.

Efford, M. G., Dawson, D. K. and Borchers, D. L. (2009) Populationdensity estimated from locations of individuals on a passive detectorarray.Ecology90, 2676–2682.

Efford, M. G., Dawson, D. K. and Robbins C. S. (2004) DENSITY: softwarefor analysing capture-recapture data from passive detector arrays.Animal Biodiversity and Conservation27,217–228.

Efford, M. G. and Fewster, R. M. (2013) Estimating populationsize by spatially explicit capture–recapture.Oikos122, 918–928.

Efford, M. G. and Hunter, C. M. (2017) Spatial capture–mark–resightestimation of animal population density.Biometrics74, 411–420.

Efford, M. G. and Mowat, G. (2014) Compensatory heterogeneity incapture–recapture data.Ecology95, 1341–1348.

Royle, J. A., Chandler, R. B., Sollmann, R. and Gardner, B. (2014)Spatial capture–recapture. Academic Press.

Royle, J. A. and Gardner, B. (2011) Hierarchical spatialcapture–recapture models for estimating density from trappingarrays. In: A.F. O'Connell, J.D. Nichols and K.U. Karanth (eds)Camera Traps in Animal Ecology: Methods and Analyses. Springer,Tokyo. Pp. 163–190.

See Also

read.capthist,secr.fit,traps,capthist,mask

Examples

## Not run: ## generate some data & plotdetectors  <- make.grid (nx = 10, ny = 10, spacing = 20,    detector = "multi")plot(detectors, label = TRUE, border = 0, gridspace = 20)detections <- sim.capthist (detectors, noccasions = 5,    popn = list(D = 5, buffer = 100),    detectpar = list(g0 = 0.2, sigma = 25))session(detections) <- "Simulated data"plot(detections, border = 20, tracks = TRUE, varycol = TRUE)## generate habitat maskmask <- make.mask (detectors, buffer = 100, nx = 48)## fit model and display resultssecr.model <- secr.fit (detections, model = g0~b, mask = mask)secr.model## End(Not run)

Compare SECR Models

Description

Terse report on the fit of one or more spatially explicitcapture–recapture models. Models with smaller values of AIC (Akaike'sInformation Criterion) are preferred. Extraction ([) and logLik methodsare included.

Usage

## S3 method for class 'secr'AIC(object, ..., sort = TRUE, k = 2, dmax = 10, criterion = c("AIC","AICc"), chat = NULL)## S3 method for class 'secrlist'AIC(object, ..., sort = TRUE, k = 2, dmax = 10, criterion = c("AIC","AICc"), chat = NULL)## S3 method for class 'secr'logLik(object, ...)secrlist(..., names = NULL)## S3 method for class 'secrlist'x[i]

Arguments

Details

Models to be compared must have been fitted to the same data and use thesame likelihood method (full vs conditional). From version 4.1 a warning is issued ifAICcompatible reveals a problem.

AIC is given by

\mathrm{AIC} = -2\log(L(\hat{\theta})) + 2K

whereK is the number of "beta" parameters estimated.

AIC with small sample adjustment is given by

\mathrm{AIC}_c = -2\log(L(\hat{\theta})) + 2K +\frac{2K(K+1)}{n-K-1}.

The sample sizen is the number of individuals observed at least once (i.e. thenumber of rows incapthist).

Model weights are calculated as

w_i = \frac{\exp(-\Delta_i / 2),}{\sum{\exp(-\Delta_i / 2)}}

where\Delta refers to differences in AIC or AICc depending on theargument ‘criterion’ (see Notes).

Models for which delta >dmax are given a weight of zero and areexcluded from the summation. Model weights may be used to formmodel-averaged estimates of real or beta parameters withmodelAverage (see also Buckland et al. 1997, Burnham andAnderson 2002).

The argumentk is included for consistency with the generic methodAIC.

secrlist forms a list of fitted models (an object of class‘secrlist’) from the fitted models in .... Arguments may includesecrlists. If secr components are named the model names will be retained unless ‘names’ is specified.(see Examples).

If chat (\hat c) is provided then quasi-AIC values are computed (secr >= 4.6.0):

\mathrm{QAIC} = -2\log(L(\hat{\theta}))/ \hat c + 2K.

Value

A data frame with one row per model. By default, rows are sorted by ascending 'criterion' (default AIC see Notes).

And depending oncriterion:

or

logLik.secr returns an object of class ‘logLik’ that hasattributedf (degrees of freedom = number of estimatedparameters).

If the variance inflation factor 'chat' is provided then outputs AIC, AICc etc. are replaced by the corresponding quasi-AIC values labelled QAIC, QAICc etc.

Note

It is not be meaningful to compare models by AIC if they relate todifferent data (seeAICcompatible).

Specifically:

• an ‘secrlist’ generated and saved to file bymask.checkmay be supplied as the object argument ofAIC.secrlist, but theresults are not informative

• models fitted by the conditional likelihood (CL = TRUE) andfull likelihood (CL = FALSE) methods cannot be compared

• hybrid mixture models (using hcov argument of secr.fit) should notbe compared with other models

• grouped models (using groups argument of secr.fit) should not becompared with other models

• multi-session models should not be compared with single-sessionmodels based on the same data.

A likelihood-ratio test (LR.test) is a more direct way tocompare two models.

The issue of goodness-of-fit and possible adjustment of AIC foroverdispersion has yet to be addressed (cf QAIC in MARK).

The user may select between AIC and AICc for comparing models. AICc is widely used, but AIC may be better for model averaging even when samples are small (Turek and Fletcher 2012; Fletcher 2019, p. 60). The default was changed to AIC in version 5.0.0).

References

Buckland S. T., Burnham K. P. and Augustin, N. H. (1997) Model selection: an integral part of inference.Biometrics53, 603–618.

Burnham, K. P. and Anderson, D. R. (2002)Model Selection and Multimodel Inference: A Practical Information-Theoretic Approach. Second edition. New York: Springer-Verlag.

Fletcher, D. (2019) Model averaging. SpringerBriefs in Statistics. Berlin: Springer-Verlag.

Hurvich, C. M. and Tsai, C. L. (1989) Regression and time series model selection in small samples.Biometrika76, 297–307.

Turek, D. and Fletcher, D. (2012) Model-averaged Wald confidenceintervals.Computational statistics and data analysis56,2809–2815.

See Also

AICcompatible,modelAverage,AIC,secr.fit,print.secr,score.test,LR.test,deviance.secr

Examples

## Compare two models fitted previously## secrdemo.0 is a null model## secrdemo.b has a learned trap responseAIC(secrdemo.0, secrdemo.b)## Form secrlist and pass to AIC.secrtemp <- secrlist(null = secrdemo.0, learnedresponse = secrdemo.b)AIC(temp)

Model Compatibility

Description

Determine whether models can be compared by AIC. Incompatibility may be due to difference in the data or the specifications of the groups, hcov or binomN arguments tosecr.fit,

Usage

## S3 method for class 'secr'AICcompatible(object, ...)## S3 method for class 'secrlist'AICcompatible(object, ...)

Arguments

Details

The capthist objects are checked for strict identity with the functionidentical.

All elements in the output must be TRUE for valid AIC comparison or model averaging using AIC or AICc.

Value

Named logical vector with elements ‘data’, ‘CL’, ‘groups’, ‘hcov’ and ‘binomN’.

See Also

AIC.secr,modelAverage

Examples

AICcompatible(secrdemo.0, secrdemo.CL)## Not run: ## A common application of AICcompatible() is to determine ## the compatibility of models fitted with and without the ## fastproximity option.ovenCHp1 <- reduce(ovenCHp, by = 'all', outputdetector = 'count')ob1 <- secr.fit(ovenCHp, buffer = 300, details = list(fastproximity = TRUE))ob2 <- secr.fit(ovenCHp1, buffer = 300, details = list(fastproximity = FALSE))ob3 <- secr.fit(ovenCHp1, buffer = 300, details = list(fastproximity = FALSE), binomN = 1)AICcompatible(ob1,ob2)AICcompatible(ob1,ob3)## End(Not run)

Convert Data To Or From BUGS Format

Description

Convert data between ‘capthist’ and BUGS input format.

Usage

read.DA(DAlist, detector = "polygonX", units = 1, session = 1,    Y = "Y", xcoord = "U1", ycoord = "U2", xmin = "Xl",    xmax = "Xu", ymin = "Yl", ymax = "Yu", buffer = "delta",    verify = TRUE)write.DA(capthist, buffer, nzeros = 200, units = 1)

Arguments

Details

Data for OpenBUGS or WinBUGS called from R using the packageR2WinBUGS (Sturtz et al. 2005) take the form of anR list.

These functions are limited at present to binary data from a squarequadrat such as used by Royle and Young (2008). Marques et al. (2011)provide anR functioncreate.data() for generating simulateddatasets of this sort (seesim.capthist for equivalentfunctionality).

When reading BUGS data –

The character valuesY,xcoord,ycoord,xmin etc. are used to locate the data withinDAlist,allowing for variation in the input names.

The number of sampling occasions is taken from the number of columnsinY. Each value inY should be 0 or 1. Coordinates maybe missing

A numeric value forbuffer is the distance (in the originalunits) by which the limits Xl, Xu etc. should be shrunk to give theactual plot limits. Ifbuffer is character then a component ofDAlist contains the required numeric value.

Coordinates in the output will bemultiplied by the scalarunits.

Augmentation rows corresponding to ‘all-zero’ detection histories inY,xcoord, andycoord are discarded.

When writing BUGS data –

Null (all-zero) detection histories are added to the matrix ofdetection historiesY, and missing (NA) rows are added to thecoordinate matricesxcoord andycoord.

Coordinates in the output will bedivided by the scalarunits.

Value

Forread.DA, an object of class ‘capthist’.

Forwrite.DA, a list with the components

U1 and U2 are ‘NA’ where animal was not detected.

References

Marques, T. A., Thomas, L. and Royle, J. A. (2011) A hierarchical modelfor spatial capture–recapture data: Comment.Ecology92,526–528.

Royle, J. A. and Young, K. V. (2008) A hierarchical model for spatialcapture–recapture data.Ecology89, 2281–2289.

Sturtz, S., Ligges, U. and Gelman, A. (2005) R2WinBUGS: a package forrunning WinBUGS from R.Journal of Statistical Software12, 1–16.

See Also

hornedlizardCH,verify,capthist

Examples

write.DA (hornedlizardCH, buffer = 100, units = 100)## In this example, the input uses Xl, Xu etc.## for the limits of the plot itself, so buffer = 0.## Input is in hundreds of metres.## First, obtain the list lzdataolddir <- setwd (system.file("extdata", package="secr"))source ("lizarddata.R")setwd(olddir)str(lzdata)## Now convert to capthisttempcapt <- read.DA(lzdata, Y = "H", xcoord = "X",    ycoord = "Y", buffer = 0, units = 100)## Not run: plot(tempcapt)secr.fit(tempcapt, trace = FALSE)## etc.## End(Not run)

Coefficient of Variation

Description

The coefficient of variation of effective sampling area predicts thebias in estimated density (Efford and Mowat 2014). These functionsassist its calculation from fitted finite mixture models.

Usage

CV(x, p, na.rm = FALSE)CVa0(object, ...)CVa(object, sessnum = 1, ...)

Arguments

Details

CV computes the coefficient of variation ofx. Ifp is provided then the distribution is assumed to bediscrete, with supportx and class membership probabilitiesp (scaled automatically to sum to 1.0).

CVa computes CV(a) wherea is the effectivesampling area of Borchers and Efford (2008).

CVa0 computes CV(a0) where a0 is the single-detector samplingarea defined asa_0 = 2 \pi \lambda_0 \sigma^2 (Efford and Mowat 2014); a0 is a convenientsurrogate fora, the effective sampling area. CV(a0) useseither the fitted MLE of a0 (if the a0 parameterization has beenused), or a0 computed from the estimates of lambda0 and sigma.

CVa andCVa0 do not work for models with individualcovariates.

Value

Numeric

Note

Do not confuse the function CVa with the estimated relative standarderror of the estimate of a fromderived, also labelled CVain the output. The relative standard error RSE is often labelled CVin the literature on capture–recapture, but this can cause unnecessary confusion. See alsoRSE.

References

Borchers, D. L. and Efford, M. G. (2008) Spatially explicit maximumlikelihood methods for capture–recapture studies.Biometrics64, 377–385.

Efford, M. G. and Mowat, G. (2014) Compensatory heterogeneity incapture–recapture data.Ecology95, 1341–1348.

See Also

CVpdot,derived,details,RSE

Examples

## Not run: ## housemouse modelmorning <- subset(housemouse, occ = c(1,3,5,7,9))msk <- make.mask((traps(morning)), nx = 32) morning.h2   <- secr.fit(morning, buffer = 20, model = list(g0~h2), mask = msk,     trace = FALSE)CVa0(morning.h2 )## End(Not run)

Construct Density Design Data

Description

Internal function used bysecr.fit,confint.secr, andscore.test.

Usage

D.designdata (mask, Dmodel, grouplevels, sessionlevels, sessioncov =NULL, meanSD = NULL)

Arguments

Details

This is an internalsecr function that you are unlikely ever touse. Unlikesecr.design.MS, this function doesnotcallmodel.matrix.

Value

Dataframe with one row for each combination of mask point, group andsession. Conceptually, we use a 3-D rectangular array with enough rowsto accommodate the largest mask, so some rows in the output may merelyhold space to enable easy indexing. The dataframe has an attribute‘dimD’ that gives the relevant dimensions: attr(dframe, "dimD") =c(nmask, ngrp, R), wherenmask is the number of mask points,ngrp is the number of groups, andR is the number ofsessions. Columns correspond to predictor variables in Dmodel.

The number of valid rows (points in each session-specific mask) isstored in the attribute ‘validMaskRows’.

For a single-session mask,meanSD is a 2 x 2 matrix of mean andSD (rows) for x- and y-coordinates. For a multi-session mask, a list ofsuch objects. Ordinarily these values are from the meanSD attribute ofthe mask, but they must be specified when applying a new mask to anexisting model.

See Also

secr.design.MS

Density Surfaces

Description

S3 class for rasterized fitted density surfaces. A Dsurface is a typeof ‘mask’ with covariate(s) for the predicted density at each point.

Usage

## S3 method for class 'Dsurface'print(x, scale = 1, ...)## S3 method for class 'Dsurface'summary(object, scale = 1, ...)

Arguments

Details

A Dsurface will usually have been constructed withpredictDsurface.

The ‘scale’ argument may be used to change the units of density from the default(animals / hectare) to animals / km^2 (scale = 100) or animals / 100km^2(scale = 10000).

A virtual S4 class ‘Dsurface’ is defined to allow the definition of a method for the generic functionraster from theraster package.

See Also

predictDsurface,plot.Dsurface

Frequently Asked Questions, And Others

Description

A place for hints and miscellaneous advice.

How do I install and start secr?

Follow the usual procedure for installing from CRAN archive (see menuitem Packages | Install package(s)... in Windows). You also need to getthe packageabind from CRAN.

Like other contributed packages,secr needs to be loaded beforeeach use e.g.,library(secr).

You can learn about changes in the current version withnews(package = "secr").

How can I get help?

There are three general ways of displaying documentation from withinR.Firstly, you can bring up help pages for particular functions from thecommand prompt. For example:

?secror?secr.fit

Secondly, help.search() lets you ask for a list of the help pages on avague topic (or just use ?? at the prompt). For example:

?? "linear models"

Thirdly, you can display varioussecr documents listed insecr-package.

Tip: to search all secr help pages open the pdf version of the manual inAcrobat Reader (secr-manual.pdf; see also ?secr) and use<ctrl> F.

There is a support forum at www.phidot.org/forum under‘DENSITY|secr’ and another atsecrgroup. See below formoreR tips. Some specific problems withsecr.fit are covered inTroubleshooting.

How should I report a problem?

If you get really stuck or find something you think is a bug then pleasereport the problem to one of the online lists.

You may be asked to send an actual dataset - ideally, the simplest onethat exhibits the problem. Usesave to wrapseveralR objects together in one .RData file, e.g.,save("captdata", "secrdemo.0", "secrdemo.b", file ="mydata.RData"). Also, paste into the text of your message the outputfrompackageDescription( "secr" ).

Why do I get different answers from secr and Density?

Strictly speaking, this should not happen if you have specified the samemodel and likelihood, although you may see a little variation due to thedifferent maximization algorithms. Likelihoods (and estimates) maydiffer if you use different integration meshes (habitat masks), whichcan easily happen because the programs differ in how they set up themesh. If you want to make a precise comparison, save the Density meshto a file and read it intosecr, or vice versa.

Extreme data, especially rare long-distance movements, may be handleddifferently by the two programs. The ‘minprob’ component of the‘details’ argument ofsecr.fit sets a lower threshold ofprobability for capture histories (smaller values are all set tominprob), whereas Density has no explicit limit.

How can I speed up model fitting and model selection?

There are many ways - seeSpeed tips andsecr-troubleshooting.pdf.

Keep the number of mask points to a minimum and avoid detection covariates with many levels.

Does secr use multiple cores?

Some computations can be run in parallel on multiple processors (most desktops these days have multiple cores). Likelihood calculations insecr.fit assign capture histories to multiple parallel threads whenever possible.

The number of threads (cores) is controlled by an environment variable set bysetNumThreads or the 'ncores' argument of some functions.

Can a model use detector-level covariates that vary overtime?

Yes. See ?timevaryingcov. However, a more direct way to control forvarying effort is provided - see the 'usage' atribute, whichnow allows a continuous measure of effort(secr-varyingeffort.pdf).

A tip: covariate models for detection fit more quickly when the covariate takes only a few different values. UsebinCovariate to bin values.

Things You Might Need To Know AboutR

The functionfindFn in packagesos lets you search CRAN forR functions by matching text in their documentation.

There is now a vast amount ofR advice available on the web. For theterminally frustrated, ‘R inferno’ by Patrick Burns is recommended(https://www.burns-stat.com/pages/Tutor/R_inferno.pdf). "If you are usingR and you think you're in hell, this is a map for you".

Method functions for S3 classes cannot be listed in the usual way bytyping the function name at theR prompt because they are ‘hidden’ in anamespace. Get around this with getAnywhere(). For example:

getAnywhere(print.secr)

R objects have ‘attributes’ that usually are kept out of sight.Important attributes are ‘class’ (all objects), ‘dim’ (matrices andarrays) and ‘names’ (lists).secr hides quite a lot of useful dataas named ‘attributes’. Usually you will use summary and extractionmethods (traps,covariates,usage etc.) to view and changethe attributes of the various classes of object insecr. If you'recurious, you can reveal the lot with ‘attributes’. For example, withthe demonstration capture history data ‘captdata’:

traps(captdata) ## extraction method for `traps'

attributes(captdata) ## all attributes

Also, the functionstr provides a compact summary of any object:

str(captdata)

References

Claeskens, G. and Hjort N. L. (2008)Model Selection and ModelAveraging. Cambridge: Cambridge University Press.

Estimate overdispersion

Description

General function for estimating a variance inflation factor (\hat c) from observed counts.

Usage

Fletcher.chat (observed, expected, np, verbose = TRUE,     type = c('Fletcher', 'Wedderburn', 'both'), multinomial = FALSE)

Arguments

Details

Fletcher.chat applies the overdispersion formula of Fletcher (2012) or computes the conventional (Wedderburn 1974) variance inflation factorX^2/df. It is used bychat.nj.

A conventional variance inflation factor due to Wedderburn (1974) is\hat c_X = X^2/(K-p) whereK is the number of detectors,p is the number of estimated parameters, and

X^2 = \sum_k (n_k - E (n_k))^2/ E(n_k).

Fletcher's\hat c is an improvement on\hat c_X that is less affected by small expected counts. It is defined by

\hat c = c_X / (1+ \bar s),

where\bar s = \sum_k s_k / K ands_k = (n_k - E(n_k)) / E(n_k).

The inputs ‘observed’ and ‘expected’ are vectors of counts (e.g., number of distinct individuals per detector); ‘observed’ may also be a list of such vectors, possibly simulated.

Value

Output depends on ‘verbose’, ‘observed’ and ‘type’:

– if ‘observed’ is a list of nk vectors (usually generated by simulation) then the output is a vector of (Fletcher or Wedderburn)\hat c values, one element for each component of ‘observed’, unless type = "both" when the output is a list of two such vectors. Argument ‘verbose’ is ignored.

– if ‘observed’ is a simple vector then ‘verbose’ output is a list comprising input values, various summary statistics, and the computed Fletcher overdispersion (‘chat’). The statistic ‘cX2’ is the conventional variance inflation factor of Wedderburn (1974) –X^2/df. Forverbose = FALSE, a single estimate of\hat c is returned whentype = "Fletcher" ortype = "Wedderburn", otherwise a vector of the two estimates.

References

Fletcher, D. (2012) Estimating overdispersion when fitting a generalized linear model to sparse data.Biometrika99, 230–237.

Wedderburn, R. W. M. (1974) Quasi-likelihood functions, generalized linear models, and the Gauss-Newtonmethod.Biometrika61, 439–47.

See Also

chat.nj,adjustVarD

Internal Functions

Description

Functions called internally bysecr and exported but not usually called by users.

Usage

boundarytoSF (poly)Dfn2(designD, beta = NULL, ...)

Arguments

Details

The functionboundarytoSF converts various possible polygon input formats to a standard form (sfc).

Possible inputs are:

Matrix input defines a single polygon.

Dfn2 is supplied automatically as 'details' argument Dfn insecr.fit when the switch Dlambda is set to TRUE for the multi-session trend reparameterization of density.Dfn2 uses beta = NULL to return the required number of density coefficients (beta parameters) in the model.

Value

boundarytoSF – Spatial object ofsf class sfc, containing a geometry set of type POLYGON or MULTIPOLYGON. NULL input results in NULL output.

Dfn2 – Vector of density values on the link scale, suitable for the internal array (mask x groups x sessions).

References

Hijmans, R. J. (2022) terra: Spatial Data Analysis. R package version 1.5-14. https://rspatial.org/terra/

Pebesma, E. (2018) Simple features for R: standardized support for spatial vector data.The R Journal10(1), 439–446.doi:10.32614/RJ-2018-009

Pebesma, E.J. and Bivand, R. S. (2005) Classes and methods for spatial data in R.R News5(2), 9–13.https://cran.r-project.org/doc/Rnews/Rnews_2005-2.pdf.

See Also

pointsInPolygon,secr-spatialdata.pdf,

predictDlambda,secr-trend.pdf,

Examples

poly <- cbind(x = c(0,6,6,0,0), y = c(0,0,6,6,0))  boundarytoSF(poly)

Plot Likelihood Surface

Description

LLsurface is a generic function to calculate log likelihood over a grid of values of two coefficients (beta parameters) from a fitted model and optionally make an approximate contour plot of the log likelihood surface.

A method is provided for secr objects.

Usage

LLsurface(object, ...)## S3 method for class 'secr'LLsurface(object, betapar = c("g0", "sigma"), xval = NULL,    yval = NULL, centre = NULL, realscale = TRUE, plot = TRUE,    plotfitted = TRUE, ncores = NULL, ...)

Arguments

Details

centre is set by default to the fitted values of the betaparameters inobject. This has the effect of holding parametersother than those inbetapar at their fitted values.

Ifxval oryval is not provided then 11 values are set atequal spacing between 0.8 and 1.2 times the values incentre (onthe ‘real’ scale ifrealscale = TRUE and on the ‘beta’ scaleotherwise).

Contour plots may be customized by passing graphical parameters throughthe ... argument.

Settingncores = NULL uses the existing value from the environment variable RCPP_PARALLEL_NUM_THREADS (seesetNumThreads).

Value

A matrix of the log likelihood evaluated at eachgrid point (rows x, columns y), invisibly ifplot = TRUE. Failed evaluations return NA.

Note

LLsurface works for named ‘beta’ parameters rather than‘real’ parameters. The defaultrealscale = TRUE only works forbeta parameters that share the name of the real parameter to whichthey relate i.e. the beta parameter for the base level of the realparameter. This is because link functions are defined for realparameters not beta parameters.

The contours are approximate because they rely oninterpolation. See Examples for a more reliable way to compare thelikelihood at the MLE with nearby points on the surface.

Examples

## Not run: LLsurface(secrdemo.CL, xval = seq(0.16,0.40,0.02),    yval = 25:35, nlevels = 20)## now verify MLE## click on MLE and apparent `peak'if (interactive()) {    xy <- locator(2)    LLsurface(secrdemo.CL, xval = xy$x, yval = xy$y, plot = FALSE)}## End(Not run)

Likelihood Ratio Test

Description

Compute likelihood ratio test to compare two fitted models, one nested within the other.

Usage

LR.test(model1, model2)

Arguments

Details

The fitted models must be of a class for which there is a logLikmethod (e.g., ‘secr’ or ‘lm’). Check withmethods("logLik").

The models must be nested (no check is performed - this is up to theuser), but either model1 or model2 may be the more general model.

The models must also be compatible by the criteria ofAICcompatible.

The test statistic is twice the difference of the maximizedlikelihoods. It is compared to a chi-square distribution with df equalto the number of extra parameters in the more complex model.

Value

Object of class ‘htest’, a list with components

See Also

AICcompatible,AIC.secr,score.test

Examples

## two pre-fitted modelsAIC (secrdemo.0, secrdemo.b)LR.test  (secrdemo.0, secrdemo.b)

Monte Carlo Goodness-of-fit for SECR Models

Description

MCgof implements and extends the Monte Carlo resampling method of Choo et al. (2024) to emulate Bayesian posterior predictive checks (Gelman et al. 1996, Royle et al. 2014). Initial results suggest the approach is more informative than the deviance-based test proposed by Borchers and Efford (2008) and implemented insecr.test. However, the tests have limited power.

MCgof is under development. The structure of the output may change and bugs may be found. See Warning below for exclusions.

Usage

## S3 method for class 'secr'MCgof(object, nsim = 100, statfn = NULL, testfn = NULL, seed = NULL,     ncores = 1, clustertype = c("PSOCK", "FORK"), usefxi = TRUE,     useMVN = TRUE, Ndist = NULL, quiet = FALSE, debug = FALSE, ...)## S3 method for class 'secrlist'MCgof(object, nsim = 100, statfn = NULL, testfn = NULL, seed = NULL,     ncores = 1, clustertype = c("PSOCK", "FORK"), usefxi = TRUE,     useMVN = TRUE, Ndist = NULL, quiet = FALSE, debug = FALSE, ...)

Arguments

Details

At each replicate parameter values are sampled from the multivariate-normal sampling distribution of the fitted model. The putative location of each detected individual is drawn from the spatial distribution implied by its observations and the resampled parameters (seefxi); locations of undetected individuals are simulated from the complement of pdot(x) times D(x).

New detections are simulated under the model for individuals at the simulated locations, along with the expected numbers. Detections form a capthist object, a 3-D array with dimensions for individuali, occasionj and detectork*. Thus for each replicate and detected individual there are the original observationsy_{ijk}, simulated observationsY_{ijk}, and expected counts\mathrm E (y_{ijk}). Two discrepancy statistics are calculated for each replicate – observed vs expected counts, and simulated vs expected counts – and a record is kept of which of these discrepancy statistics is the larger (indicating poorer fit).

* Notation differs slightly from Choo et al. (2024), usingj for occasion andk for detector to be consistent with usage insecr and elsewhere (e.g., Borchers and Fewster 2016).

The default discrepancy (testfn) is the Freeman-Tukey statistic as in Choo et al. (2024) and Royle et al. (2014) (see also Brooks, Catchpole and Morgan 2000). The statistic has this general form forM countsy_m with expected value\mathrm E(y_m):

T = \sum_{m=1}^{m=M} \left(\sqrt {y_m} - \sqrt{E(y_m)}\right)^2.

The key output ofMCgof is the proportion of replicates in which the simulated discrepancy exceeds the observed discrepancy. For perfect fit this will be about 0.5, and for poor fit it will approach zero.

By default, tests are performed separately for three types of count: the numbers of detections of each individual (yi), at each detector (yk), and for each individual at each detector (yik) extracted by the defaultstatfn from the margins of the observed and simulated capture histories.

Parallel processing is offered using multiple cores (CPUs) through the packageparallel when ncores > 1. This differs from the usual multithreading paradigm insecr and does not rely on the environment variable set bysetNumThreadsexcept that, if ncores = NULL, ncores will be set to the value fromsetNumThreads. The cluster type "FORK" is available only on Unix-like systems; it can require large amounts of memory, but is generally fast. A small value of ncores>1 may be optimal, especially with cluster type "PSOCK".

‘usefxi’ and ‘useMVN’ may be used to drop key elements of the Choo et al. (2024) approach - they are provided for demonstration only.

‘Ndist’ refers to the distribution of the number of unobserved AC, conditional on the expected numberq = D^*A - n whereD^* is the resampled density,A the mask area, andn the number of detected individuals. By default ‘Ndist’ depends on the distribution component of the ‘details’ argument of the fitted model (“poisson" for Poissonn, “fixed"" for binomialn).

‘debug’ may be used to view intermediate data at certain points in MCgof() numbered 1 to 5. Examine the code of secr:::MCgof.secr or secr:::simfxiAC for these points. Debugging requires ‘ncores = 1’.

TheRNGkind of the random number generator is set internally for consistency across platforms.

The ... argument may be used to pass 'np' and 'verbose' to ‘Fletcher.chat' used as ’testfn'.

Value

Invisibly returns an object of class ‘MCgof’ with components -

For secrlist input the value returned is a list of ‘MCgof’ objects.

Warning

Not all models are covered and some are untested. These models are specifically excluded -

1. multi-session models

2. models with groups

3. conditional likelihood

4. polygon, transect, telemetry or signal detectors

5. non-binary behavioural responses

Notes

This implementation extends the work of Choo et al. (2024) in these respects -

1. detector types ‘multi’ and ‘count’ are allowed

2. the model may include variation among detectors

3. the model may include behavioural responses

4. 2-class finite mixture and hybrid mixture models are both allowed.

Author(s)

Murray Efford and Yan Ru Choo

References

Borchers, D. L. and Efford, M. G. (2008) Spatiallyexplicit maximum likelihood methods for capture–recapture studies.Biometrics64, 377–385.doi:10.1111/j.1541-0420.2007.00927.x

Borchers, D. L. and Fewster, R. M. (2016) Spatial capture–recapture models.Statistical Science31, 219–232.doi:10.1214/16-sts557

Brooks, S. P., Catchpole, E. A. and Morgan, B. J. T. (2000) Bayesian animal survival estimation.Statistical Science15, 357–376.

Choo, Y. R., Sutherland, C. and Johnston, A. (2024) A Monte Carlo resampling framework for implementing goodness-of-fit tests in spatial capture-recapture modelMethods in Ecology and Evolution15,doi:10.1111/2041-210X.14386.

Gelman, A., Meng, X.-L., and Stern, H. (1996) Posterior predictive assessment of model fitness via realized discrepancies.Statistica Sinica6, 733–807.

Royle, J. A., Chandler, R. B., Sollmann, R. and Gardner, B. (2014)Spatial capture–recapture. Academic Press.

See Also

Parallel,secr.test,plot.MCgof,hist.MCgof,summary.MCgof

Examples

tmp <- MCgof(secrdemo.0)summary(tmp)par(mfrow = c(1,3), pty = 's')plot(tmp)

Orongorongo Valley Brushtail Possums

Description

A dataset from long-term capture-recapture trapping of brushtail possumsTrichosurus vulpecula in New Zealand.

Usage

OVpossumCH

Format

A multi-session capthist object of 6 sessions. Sessions are labeled49–54, corresponding to February 1996, June 1996, September 1996,February 1997, June 1997 and September 1997.

Details

Brushtail possums are 2-4 kg largely arboreal marsupials that havebecome pests of forests and farmland in New Zealand since theirintroduction from Australia in the nineteenth century. Their populationdynamics in mixed native forest have been studied by capture-recapturein the Orongorongo Valley near Wellington since 1966 (e.g. Crawley 1973,Efford 1998, Efford and Cowan 2004).

From 1996 to 2006, a grid of 167 traps set on the ground at 30-m spacingwas operated in an area of about 14 ha for 5 consecutive days threetimes each year (Efford and Cowan 2004). Each trap could catch only oneanimal, with rare exceptions when a young ‘backrider’ entered the trapwith its mother. All animals were tagged and tattooed for individualidentification and released at the site of capture.

A broad shingle riverbed forms a natural boundary on two sides of thestudy grid. Much of the grid lies on a gently sloping old alluvial fanand recent terraces, but to the southeast the valley side rises steeplyand, except where cut by streams, supports beech forest(Nothofagus truncata andNothofagus solandri solandri)rather than the mixed broadleaf forest of the valley floor.

This dataset relates to six five-day trapping sessions in 1996 and 1997,a time of high and declining density. Possums are long-lived (up toabout 15 years) and as adults restrict their movements to a home rangeof 1-10 ha. Breeding is seasonal, resulting in an influx of newlyindependent juveniles in the first trapping of each calendar year.

The dataset includes individual covariates not provided by Efford (2012):‘Sex’ (F or M) and ‘Ageclass’ (1 for first year, 2 for older).

A coarse habitat map is provided for the immediate vicinity of thetrapping grid as the shapefile ‘OVforest.shp’ in the package ‘extdata’folder. This distinguishes two forest classes (‘beech’ and ‘non-beech’),and leaves out the shingle riverbed. The distinction between ‘beech’ and‘non-beech’ is mapped only to a distance of about 120 m from theoutermost traps. A text file 'leftbank.txt' in the same folder contains the x- and y- coordinates of the adjoining bank of the Orongorongo River. All coordinates relate to the old New Zealand Map Grid (NZMG), since replaced by the New Zealand Transverse Mercator grid (NZTM2000).

The example code shows how to import the shapefile as asf‘simple features’ object and use it to construct a mask forsecr.fit.

Source

Efford (2012) and unpublished data.

References

Crawley, M. C. (1973) A live-trapping study of Australian brush-tailedpossums,Trichosurus vulpecula (Kerr), in the OrongorongoValley, Wellington, New Zealand.Australian Journal ofZoology21, 75–90.

Efford, M. G. (1998) Demographic consequences of sex-biased dispersal ina population of brushtail possums.Journal of Animal Ecology67, 503–517.

Efford, M. G. (2012) DENSITY 5.0: software for spatially explicitcapture-recapture. Department of Mathematics and Statistics,University of Otago, Dunedin, NewZealand.https://www.otago.ac.nz/density/

Efford, M. G. and Cowan, P. E. (2004) Long-term population trend ofTrichosurus vulpecula in the Orongorongo Valley, NewZealand. In:The Biology of Australian Possums andGliders. Edited by R. L. Goldingay and S. M. Jackson. SurreyBeatty & Sons, Chipping Norton. Pp. 471–483.

Ward, G. D. (1978) Habitat use and home range of radio-tagged opossumsTrichosurus vulpecula (Kerr) in New Zealand lowland forest. In:The ecology of arboreal folivores. Edited by G. G. Montgomery. Smithsonian Institute Press. Washington, D.C. Pp. 267–287.

Examples

## Not run: library(sf)summary(OVpossumCH, terse = TRUE)ovtrap <- traps(OVpossumCH[[1]])## retrieve and plot the forest mapOVforest <- st_read(system.file("extdata/OVforest.shp", package = "secr"))## omit forest across the river by selecting only 1,2OVforest <- OVforest[1:2,]forestcol <- terrain.colors(6)[c(4,2)]plot(st_as_sfc(OVforest), col = forestcol)plot(ovtrap, add = TRUE)## construct a maskovmask <- make.mask(ovtrap, buffer = 120, type = 'trapbuffer',    poly = OVforest, spacing = 7.5, keep.poly = FALSE)ovmask <- addCovariates(ovmask, OVforest)## display maskpar(mar = c(0,0,0,8))plot(ovmask, covariate = 'forest', dots = FALSE, col = forestcol)plot(ovtrap, add = TRUE)## add the left bank of the Orongorongo Riverlines(read.table(system.file("extdata/leftbank.txt", package = "secr")))## End(Not run)

Telemetry Fixes in Polygons

Description

For a telemetry dataset, either as a standalone capthist object withdetector type ‘telemetryonly’ or the xylist attribute of a combined capthistobject resulting fromaddTelemetry, determine the proportion offixes of each individual that lie within a set of polygons. Typicallyused to obtain the proportion of fixes on a trapping grid, hence‘proportion on grid’.

Usage

PG(CH, poly = NULL, includeNULL = FALSE, plt = FALSE, ...)

Arguments

Details

By defaultpoly is obtained by applyingbufferContour with arguments ... to the trapsattribute ofCH. Note that either a positivebufferargument orconvex = TRUE is needed for the polygon to havearea > 0.

Ifplt = TRUE,bufferContour is used to plotpoly and the points are overplotted (open circles outside,filled circles inside). To control the framing of the plot, create aninitial plot (e.g., with plot.traps, setting theborderargument) and useadd = TRUE (see Examples).

Value

Numeric vector of proportions. IfincludeNULL = TRUE lengthequal to number of animals (rows) inCH; otherwise length isthe number of animals for which there is telemetry data (becausexylist may cover only a subset of animals inCH).

References

Grant, T. J. and Doherty, P. F. (2007) Monitoring of the flat-tailedhorned lizard with methods incorporating detectionprobability.Journal of Wildlife Management71, 1050–1056

See Also

addTelemetry,bufferContour,pointsInPolygon

Examples

## Not run: olddir <- setwd('d:/density communication/combining telemetry and secr/possums')CvilleCH <- read.capthist('CVILLE summer captures 4occ.txt',                          'CVILLE detectors summer 4occ.txt',                          detector = 'single')CvilleGPS <- read.telemetry('CVILLE GPS Combined 4occ.txt')CvilleGPSnew <- read.telemetry('CVILLE summer GPS New occasions.txt')setwd(olddir)CvilleBoth <- addTelemetry(CvilleCH, CvilleGPSnew)plot(CvilleBoth, border = 400)PG(CvilleBoth, buffer = 100, convex = TRUE, plt = TRUE, add = TRUE,     col = 'red')##################################################################### this code computes an area-adjusted density estimate## cf Grant and Doherty 2007PGD <- function (CH, estimator = 'h2', ...) {    pg <- PG(CH, ...)    PGbar <- mean(pg)    N <- closedN(CH, estimator)    A <- polyarea(bufferContour(traps(CH), ...)[[1]])    Dhat <- N$Nhat / A * PGbar    varDhat <- (N$Nhat^2 * var(pg) + PGbar^2 * N$seNhat^2) / A^2     c(Dhat = Dhat, seDhat = sqrt(varDhat))}plot(traps(CvilleBoth), border = 400)PGD(CvilleBoth, buffer = 0, convex = TRUE, plt = TRUE, add = TRUE)PGD(CvilleBoth, est='null', buffer = 0, convex = TRUE, plt = FALSE)##################################################################### this code generates a PG summary for telemetry records randomly## translated and rotated, keeping the centres within a habitat maskrandomPG <- function(CH, poly = NULL, mask, reorient = TRUE, nrepl = 1,                     seed = 12345, ...) {    moveone <- function(xy, newcentre) {        xy <- sweep(xy,2,apply(xy,2,mean))        if (reorient)  ## random rotation about centre            xy <- rotate(xy, runif(1)*360)        sweep(xy,2,unlist(newcentre), "+")    }    onerepl <- function(r) {   ## r is dummy for replicate        centres <- sim.popn(D = D, core = mask, model2D = "IHP",                            Ndist = "fixed")        xyl <- mapply(moveone, xyl, split(centres, rownames(centres)))        attr(CH, 'xylist') <- xyl  ## substitute random placement        PG(CH = CH , poly = poly, plt = FALSE, ...)    }    set.seed(seed)    if (!requireNamespace('sf')) stop ("requires package sf")    if (is.null(poly)) {        poly <- bufferContour (traps(CH), ...)        poly <- lapply(poly, as.matrix)        poly <- sf::st_sfc(sf::st_polygon(poly))    }    xyl <- telemetryxy(CH)    D <- length(xyl) / maskarea(mask)    sapply(1:nrepl, onerepl)}mask <- make.mask (traps(CvilleBoth), buffer = 400, type = "trapbuffer")pg <- randomPG (CvilleBoth, mask = mask, buffer = 100, convex = TRUE,    nrepl = 20)apply(pg, 1, mean)##################################################################### End(Not run)

Multi-core Processing

Description

From version 4.0secr uses multi-threading in C++ (packageRcppParallel, Allaire et al. 2021) to speed likelihood evaluation and hence model fitting insecr.fit. Detection histories are distributed over threads. Settingncores = NULL in functions with multi-threading uses the existing value from the environment variable RCPP_PARALLEL_NUM_THREADS (seesetNumThreads).

These functions use multi-threading and callsetNumThreads internally:

These functions use multi-threading without callingsetNumThreads:

Other functions may use multithreading indirectly through a call to one of these functions. Examples aresuggest.buffer (autoini),esaPlot (pdot), andbias.D (pdot).

NOTE: The mechanism for setting the number of threads changed between versions 4.1.0 and 4.2.0. The default number of cores is now capped at 2 to meet CRAN requirements. Settingncores = NULL previously specified one less than the maximum number of cores.

Earlier versions ofsecr made more limited use of multiple cores (CPUs)through the packageparallel. The functionspar.secr.fit,par.derived, andpar.region.N are now deprecated because they were too slow.list.secr.fit replacespar.secr.fit

‘Unit’ refers to the unit of work sent to each worker process. As a guide, a ‘large’ benefit means >60% reduction in process time with4 CPUs.

parallel offers several different mechanisms, bringing togetherthe functionality ofmulticore andsnow. The mechanism usedbysecr is the simplest available, and is expected to work across alloperating systems. Technically, it relies on Rscript and communicationbetween the master and worker processes isvia sockets. As statedin theparallel documentation "Users of Windows and Mac OS X mayexpect pop-up dialog boxes from the firewall asking if an R processshould accept incoming connections". You may possibly get warnings from R about closing unused connections. These can safely be ignored.

Useparallel::detectCores() to getan idea of how many cores are available on your machine; this may (inWindows) include virtual cores over and above the number of physicalcores. See RShowDoc("parallel", package = "parallel") in core R forexplanation.

Insecr.fit the output component ‘proctime’ misrepresents theelapsed processing time when multiple cores are used.

Warning

It appears that multicore operations insecr usingparallel may fail if the packagessnow andsnowfall are also loaded. The error message is obscure:

“Error in UseMethod("sendData") : no applicable method for 'sendData' applied to an object of class "SOCK0node"”

References

Allaire, J. J., Francois, R., Ushey, K., Vandenbrouck, G., Geelnard, M. and Intel (2021)RcppParallel: Parallel Programming Tools for 'Rcpp'. R package version 5.1.2.https://CRAN.R-project.org/package=RcppParallel.

Examples

## Not run: sessionInfo()# R version 4.3.0 (2023-04-21 ucrt)# Platform: x86_64-w64-mingw32/x64 (64-bit)# Running under: Windows 11 x64 (build 22621)# on Dell-XPS 8950 Intel i7-12700K# ...# see stackoverflow suggestion for microbenchmark list argument# https://stackoverflow.com/questions/32950881/how-to-use-list-argument-in-microbenchmarklibrary(microbenchmark)options(digits = 4)## benefit from multi-threading in secr.fitjobs <- lapply(seq(2,8,2), function(nc)     bquote(suppressWarnings(secr.fit(captdata, trace = FALSE, ncores = .(nc)))))microbenchmark(list = jobs, times = 10, unit = "seconds")# [edited output]# Unit: seconds# expr     min      lq   mean median     uq    max neval# ncores = 2 1.75880 2.27978 2.6680 2.7450 3.0960 3.4334    10# ncores = 4 1.13549 1.16280 1.6120 1.4431 2.0041 2.4018    10# ncores = 6 0.88003 0.98215 1.2333 1.1387 1.5175 1.6966    10# ncores = 8 0.78338 0.90033 1.5001 1.0406 1.2319 4.0669    10## sometimes (surprising) lack of benefit with ncores>2msk <- make.mask(traps(ovenCH[[1]]), buffer = 300, nx = 25)jobs <- lapply(c(1,2,4,8), function(nc)     bquote(secr.fit(ovenCH, trace = FALSE, ncores = .(nc), mask = msk)))microbenchmark(list = jobs, times = 10, unit = "seconds")# [edited output]# Unit: seconds# expr     min      lq   mean median     uq    max neval# ncores = 1 12.5010 13.4951 15.674 15.304 16.373 21.723    10# ncores = 2 10.0363 11.8634 14.407 13.726 16.782 22.966    10# ncores = 4  8.6335 10.3422 13.085 12.449 15.729 17.914    10# ncores = 8  8.5286  9.9008 10.751 10.736 10.796 14.885    10## and for simulation...jobs <- lapply(seq(2,8,2), function(nc)    bquote(sim.secr(secrdemo.0, nsim = 20, tracelevel = 0,  ncores = .(nc))))microbenchmark(list = jobs, times = 10, unit = "seconds")# [edited output]# Unit: seconds# expr    min     lq   mean median     uq     max neval# ncores = 2 48.610 49.932 59.032 52.485 54.730 119.905    10# ncores = 4 29.480 29.996 30.524 30.471 31.418  31.612    10# ncores = 6 22.583 23.594 24.148 24.354 24.644  25.388    10# ncores = 8 19.924 20.651 25.581 21.002 21.696  51.920    10## and log-likelihood surfacejobs <- lapply(seq(2,8,2), function(nc)     bquote(suppressMessages(LLsurface(secrdemo.0,  ncores = .(nc)))))microbenchmark(list = jobs, times = 10, unit = "seconds")# [edited output]# Unit: seconds# expr    min     lq   mean median     uq    max neval# ncores = 2 20.941 21.098 21.290 21.349 21.471 21.619    10# ncores = 4 14.982 15.125 15.303 15.263 15.449 15.689    10# ncores = 6 13.994 14.299 14.529 14.342 14.458 16.515    10# ncores = 8 13.597 13.805 13.955 13.921 14.128 14.353    10## End(Not run)

Convert Data to RMark Input Format

Description

A single-session capthist object is formed by RMarkInput into a dataframe that may bepassed directly to RMark.

Usage

RMarkInput(object, grouped = FALSE, covariates = TRUE)unRMarkInput(df, covariates = TRUE)

Arguments

Details

To convert a multi-session object first collapse the sessions withjoin.

Ifcovariates is TRUE then all columns of individual covariatesin the input are appended as columns in the output. Ifcovariates is a character-valued vector then only the specifiedcovariates will be appended.

If bothgrouped andcovariates are specified inRMarkInput,grouped will be ignored, with a warning.

Value

For RMarkInput –

Dataframe with fields ch and freq. ‘ch’ is a character string of 0'sand 1's. Ifgrouped = FALSE the rownames are retained and thevalue of ‘freq’ is 1 or -1. Negative values of ‘freq’ indicateremoval.

The dataframe also includes individual covariates specified withcovariates.

The attribute ‘intervals’ is copied from ‘object’, if present;otherwise it is set to a vector of zeros (indicating aclosed-population sample).

For unRMarkInput –

A single-session capthist object with no traps attribute and hence nodetector type (i.e. non-spatial capture histories). Covariates arecopied as requested.

Fromsecr 4.6.6, missing values (.) in input capture histories are converted to NA in the output, with a warning. The resulting capthist is unusable until the NAs are removed.

Note

In versions before 2.4.0, a spurious occasion was added byRMarkInput when grouped = FALSE. Thanks to Jeff Stetz forspotting this.

The default value forgrouped changed to FALSE in secr 2.4.0.

References

Laake, J. and Rexstad E. (2008) Appendix C. RMark - an alternativeapproach to building linear models in MARK. In: Cooch, E. and White,G. (eds) Program MARK: A Gentle Introduction. 6th edition. Most recent edition available at www.phidot.org/software/mark/docs/book/.

See Also

join

Examples

## ovenCH is a 5-year mist-netting datasetovenRD <- RMarkInput (join(ovenCH))head(ovenRD)unRMarkInput(ovenRD)RMarkInput(deermouse.ESG, covariates = FALSE, grouped = TRUE)RMarkInput(deermouse.ESG, covariates = TRUE)## Not run: ## fit robust-design model in RMark (MARK must be  installed)library(RMark)MarkPath <- 'c:/MARK'    ## adjust for your installationovenRD.data <- process.data(ovenRD, model = "Robust",    time.interval = attr(ovenRD, "intervals"))ovenRD.model <- mark(data = ovenRD.data, model = "Robust",    model.parameters = list(p = list(formula = ~1, share = TRUE),    GammaDoublePrime = list(formula = ~1),    GammaPrime = list(formula = ~1),    f0 = list(formula = ~1)))   cleanup(ask = FALSE)## End(Not run)

RSE from Fitted Model

Description

Precision of parameter estimates from an SECR model, expressed as relative standard error.

Usage

RSE(fit, parm = NULL, newdata = NULL)

Arguments

Details

The relative standard error (RSE) of parameter\theta isRSE(\hat \theta) = \widehat{SE} (\theta) / {\hat \theta}.

For a parameter estimated using a log link with single coefficient\beta, the RSE is also\mathrm{RSE}(\hat \theta) = \sqrt {\exp( \mathrm{var}(\beta))-1}.This formula is used wherever applicable.

Value

Named vector of RSE, or matrix if newdata has more than one row.

Note

The less explicit abbreviation CV has been used for the same quantity (sometimes expressed as a percentage). CV is used also for the relative standard deviation of a distribution.

References

Efford, M. G. and Boulanger, J. 2019. Fast evaluation of study designs for spatially explicit capture–recapture.Methods in Ecology and Evolution10, 1529–1535.

See Also

CV

Examples

RSE(secrdemo.0)

Smoothed Resource Surface

Description

Creates a smoothed resource surface from a covariate of amask. Smoothing entails summing the value in each pixel weighted by adetection kernel centred on the focal pixel. The detection kernelrepresents home-range utilization with spatial scale sigma. Theresulting surface is equivalent to the denominator used by Royle etal. (2013) to normalize site-specific detection.

Usage

Rsurface(mask, sigma, usecov = NULL, alpha2 = 1, detectfn = 'HHN', z = 1, inverse = FALSE, scale = TRUE)

Arguments

Details

detectfn may be uniform (‘UN’) or one of thecumulative-hazard functions (‘HHN’, ‘HHR’, ‘HEX’,‘HAN’, ‘HCG’) (or integer codes 4, 14:18; seedetectfn).

The default ‘HHN’ corresponds to a halfnormal function on the hazardscale, or a bivariate circular normal home range.

Ifusecov is not named then it takes the value 1.0 for all pointson the mask and zero otherwise.

The Rsurface can be used implicitly to normalize detection probability whenfitting a model with detector-specific covariate equal tousecov (seedetails, but the process is intricate and notfully documented).

Value

An object with class c(‘Rsurface’, ‘mask’, ‘data.frame’) and covariate ‘Resource’(other covariates are retained from the input mask). The attribute‘scale’ is 1.0 ifscale = FALSE; otherwise it is the average of theresource over the masked area.

Note

Consider a focal pixels and another point in the habitat maskx, with distanced = |x - s|. Weights are given by a kernelf(d). Typically the kernelwill be halfnormalf(d) = \exp(-d^2/(2\sigma^2)) (detectfn = ‘HHN’) or exponentialf(d) = \exp(-d/\sigma) (detectfn =‘HEX’) (seedetectfn for other possibilities).

Ifz(x) represents the covariate value at pointx, the summed resource availability ats is given by

R(s) = \sum_x f(d)\, \exp(\alpha_2 \, z(x)).

This corresponds to the denominator of eqn 4 in Royle et al. (2013).

By default, the numerical values reported byRsurface are not rawR values. Ifscale = TRUE, values are standardized bydividing by the mean:R'(s) = R(s) / (\sum_s R(s) / n) wheren is the number ofpixels. Values ofR'(s) are centred on 1.0.

Ifinverse = TRUE, the numeric values are1 / R'(s)or1 / R(s) as determined byscale.

References

Royle, J. A., Chandler, R. B., Sun, C. C. and Fuller, A. K. (2013)Integrating resource selection information with spatialcapture–recapture.Methods in Ecology and Evolution4,520–530.

See Also

mask,plot.Rsurface,spotHeight,details

Examples

## create binary covariate (0 outside habitat)msk <- make.mask(traps(possumCH), buffer = 800)covariates(msk) <- data.frame(z = as.numeric(pointsInPolygon    (msk,possumarea)))## derive and plot "resource availability"Rs <- Rsurface(msk, sigma = 100, usecov = 'z')plot(Rs, plottype = 'contour', col = topo.colors(10))lines(possumarea)if (interactive()) {    spotHeight(Rs, dec = 2)}

Density Trend

Description

Functions for multi-session density trend analysis.

Usage

predictDlambda(object, alpha = 0.05)

Arguments

Details

Usage is described insecr-trend.pdf. Briefly, setting details argument 'Dlambda' in 'secr.fit causes the density model (D~xxx) to be interpreted as a session-specific trend model with parameters for the initial density (D1) and each subsequent session-on-session change in density\lambda[t] = D[t+1]/D[t].

Value

A table of session-specific estimates (initial D, subsequent\lambda[t]) with SE and confidence intervals.

See Also

predictDsurface,secr.fit

Examples

# a model with constant lambdamsk <- make.mask(traps(ovenCH[[1]]), buffer = 300, nx = 25)fit <- secr.fit(ovenCH, model = D~1, mask = msk, trace = FALSE,                  details = list(Dlambda = TRUE), ncores = 2)predictDlambda(fit)

Problems in Fitting SECR Models

Description

Althoughsecr.fit is quite robust, it does not alwayswork. Inadequate data or an overambitious model occasionally causenumerical problems in the algorithms used for fitting the model, orproblems of identifiability, as described for capture–recapture modelsin general by Gimenez et al. (2004). Here are some tips that may helpyou.

This page has largely been superceded bysecr-troubleshooting.pdf.

The log-likelihood values shown with trace = TRUE are all NA

Most likely you have infeasible starting values for theparameters. try some alternatives, specifying them manually with thestart argument.

secr.fit finishes, but some or all of the variances are missing

This usually means the model did not fit and the estimates should notbe trusted. Extremely large variances or standard errors also indicateproblems.

• Try another maximization method (method = "Nelder-Mead"is more robust than the default). The same maximum likelihood shouldbe found regardless of method, so AIC values are comparable acrossmethods.

• Repeat the maximization with different starting values. You can usesecr.fit(..., start = last.model) wherelast.model is apreviously fitted secr object.

• If you think the estimates are right but there was a problemin computing the variances, try re-running secr.fit() with theprevious model as starting values (see preceding) and setmethod = "none". This bypasses maximization and computes thevariances afresh usingfdHess fromnlme.

• Try a finer mask (e.g., vary argumentnx inmake.mask). Check that the extent of the mask matches yourdata.

• The maximization algorithms work poorly when the beta coefficientsare of wildly different magnitude. This may happen when usingcovariates: ensure beta coefficients are similar (within a factor of5–10 seems adequate, but this is not based on hard evidence) by scalingany covariates you provide. This can be achieved by setting thetypsize argument ofnlm or theparscalecontrol argument ofoptim.

• Examine the model. Boundary values (e.g., g0 near 1.0) may giveproblems. In the case of more complicated models you may gain insight byfixing the value of a difficult-to-estimate parameter (argumentfixed).

See also the section ‘Potential problems’ insecr-densitysurfaces.pdf.

secr.fit finishes with warning nlm code 3

This condition does not invariably indicate a failure of modelfitting. Proceed with caution, checking as suggested in the precedingsection.

secr.fit crashes part of the way through maximization

A feature of the maximization algorithm used by default innlmis that it takes a large step in the parameter space early on in themaximization. The step may be so large that it causes floating pointunderflow or overflow in one or more real parameters. This can becontrolled by passing the ‘stepmax’ argument ofnlm in the... argument ofsecr.fit (see first example). See also theprevious point about scaling of covariates.

secr.fit demands more memory than is available

This is a problem particularly when using individual covariates in amodel fitted by maximizing the conditional likelihood. The memoryrequired is then roughly proportional to the product of the number ofindividuals, the number of occasions, the number of detectors and thenumber of latent classes (for finite-mixture models). When maximizingthe full-likelihood, substitute ‘number of groups’ for 'number ofindividuals'. [The limit is reached in external C used for thelikelihood calculation, which uses the R function ‘R_alloc’.]

Themash function may be used to reduce the number ofdetectors when the design uses many identical and independentclusters. Otherwise, apply your ingenuity to simplify your model,e.g., by casting ‘groups’ as ‘sessions’. Memory is less often an issueon 64-bit systems (see link below).

Estimates from mixture models appear unstable

These modelshave known problems due to multimodality of the likelihood. Seesecr-finitemixtures.pdf.

References

Gimenez, O., Viallefont, A., Catchpole, E. A., Choquet, R. and Morgan, B. J. T. (2004)Methods for investigating parameter redundancy.Animal Biodiversity andConservation27, 561–572.

See Also

secr.fit,Memory-limits

Add Covariates to Mask or Traps

Description

Tools to construct spatial covariates for existing mask or traps objectsfrom a spatial data source.

Usage

addCovariates(object, spatialdata, columns = NULL, strict = FALSE, replace = FALSE)

Arguments

Details

The goal is to obtain the value(s) of one or more spatial covariatesfor each point (i.e. row) inobject. The procedure depends onthe data sourcespatialdata, which may be either a spatialcoverage (raster or polygon) or an object with covariate values atpoints (another mask or traps object). In the first case, anoverlay operation is performed to find the pixel orpolygon matching each point. In the second case, a search is conductedfor the closest point inspatialdata.

Ifspatialdata is a character value then it is interpreted asthe name of a polygon shape file (excluding ‘.shp’).

Ifspatialdata is a SpatialPolygonsDataFrame, SpatialGridDataFrame or 'sf' object fromsf then it will be used in an overlay operation as described.

If packageterra has been installed thenspatialdata may also be a RasterLayer from packageraster or SpatRaster fromterra. If providedcounts should be a single name that will be used for the values (otherwise 'raster' will be used).

Ifspatialdata is amask ortraps object then itis searched for the closest point to each point inobject, andcovariates are drawn from the corresponding rows incovariates(spatialdata). By default (strict = FALSE),values are returned even when the points lie outside any cell of the mask.

Value

An object of the same class asobject with new or augmentedcovariates attribute. Column names and types are derived from the input.

Warning

Use of a SpatialGridDataFrame forspatialdata is untested.

See Also

make.mask,read.mask,read.traps

Examples

## In the Lake Station skink study (see ?skink), habitat covariates were## measured only at trap sites. Here we extrapolate to a mask, taking## values for each mask point from the nearest trap.LSmask <- make.mask(LStraps, buffer = 30, type = "trapbuffer")tempmask <- addCovariates(LSmask, LStraps)## show first few lineshead(covariates(tempmask))

Mark-resight Data

Description

Add sighting data on unmarked individuals and/or unidentified markedindividuals to an existing capthist object.

Usage

addSightings(capthist, unmarked = NULL, nonID = NULL, uncertain = NULL, verify = TRUE,    ...)

Arguments

Details

The capthist object for mark-resight analysis comprises distinct marking and sighting occasions, defined in the markocc attribute oftraps(capthist). Add this attribute totraps(capthist) withmarkocc before using 'addSightings'. See alsoread.traps andread.capthist.

Mark-resight data may be binary (detector type ‘proximity’) or counts (detector types ‘count’, 'polygon' or 'transect'). The detector type is an attribute oftraps(capthist). Values inunmarked andnonID should be whole numbers, and may be greater than 1 even for binary proximity detectors because multiple animals may be detected simultaneously at one place.

Argumentsunmarked,nonID,uncertain provide data for attributes‘Tu’, ‘Tm’, ‘Tn’ respectively. They may take several forms

• a single integer, the sum of all counts*

• a matrix of the count on each occasion at each detector (dimensions K x S, where K is the number of detectors and S is the total number of occasions). Columns corresponding to marking occasions should be all-zero.

• for multi-session data, a list with components as above

• a character value with the name of a text file containing the data; the file will be read withread.table. The ... argument allows some control over how the file is read. The data format comprises at least S+1 columns. The first is a session identifier used to split the file when the data span multiple sessions; it should be constant for a single-session capthist. The remaining S columns contain the counts for occasions 1:S, one row per detector. Further columns may be present; they are ignored at present.

* although this is convenient, the full matrix of counts provides more flexibility (e.g., when you wish to subset by occasion), and enables modelling of variation across detectors and occasions.

Value

A capthist object with the same structure as the input, but with new sighting-related attributes Tu (sightings of unmarked animals) and/or Tm (unidentified sightings of marked animals). Input values, including NULL, overwrite existing values.

Warning

** Mark-resight data formats and models are experimental and subject to change **

See Also

markocc,read.capthist,read.traps,sim.resight,Tm,Tu,Tn,secr-markresight.pdf

Examples

## construct capthist object MRCH from text files provided in ## 'extdata' folder, assigning attribute 'markocc' and add unmarked## and marked sightings from respective textfilesdatadir <- system.file("extdata", package = "secr")captfile <- paste0(datadir, '/MRCHcapt.txt')trapfile <- paste0(datadir, '/MRCHtrap.txt')Tufile <- paste0(datadir, '/Tu.txt')Tmfile <- paste0(datadir, '/Tm.txt')MRCH <- read.capthist(captfile, trapfile, detector = c("multi",     rep("proximity",4)), markocc = c(1,0,0,0,0))MRCH1 <- addSightings(MRCH, Tufile, Tmfile)## alternatively (ignoring marked, not ID sightings)MRCH <- read.capthist(captfile, trapfile, detector = c("multi",     rep("proximity",4)), markocc = c(1,0,0,0,0))Tu <- read.table(Tufile)[,-1]  # drop session columnMRCH2 <- addSightings(MRCH, unmarked = Tu)summary(MRCH2)

Combine Telemetry and Detection Data

Description

Animal locations determined by radiotelemetry can be used to augmentcapture–recapture data. The procedure insecr is first to form acapthist object containing the telemetry data and then to combine thiswith true capture–recapture data (e.g. detections from hair-snag DNA)in another capthist object.secr.fit automatically detects thetelemetry data in the new object.

Usage

addTelemetry (detectionCH, telemetryCH, type = c('concurrent','dependent','independent'),    collapsetelemetry = TRUE, verify = TRUE) xy2CH (CH, inflation = 1e-08)telemetrytype (object) <- valuetelemetrytype (object, ...)

Arguments

Details

It is assumed that a number of animals have been radiotagged, and their telemetry data(xy-coordinates) have been input totelemetryCH, perhaps usingread.capthist withdetector = "telemetryonly" andfmt = "XY", or withread.telemetry.

A new capthist object is built comprising all the detectionhistories indetectionCH, plus empty (all-zero) histories forevery telemetered animal not indetectionCH. Telemetry is associated with new sampling occasions and a new detector (nominally at the same point as the first indetectionCH). The number of telemetry fixes of each animal is recorded in the relevant cell of the new capthist object (CH[i, s, K+1] for animal i and occasion s if there were K detectors in detectionCH).

The new sampling occasion(s) are assigned the detector type ‘telemetry’ in the traps attribute of the output capthist object, and the traps attributetelemetrytype is set to the value provided. The telemetry type may be “independent” (no matching of individuals in captured and telemetered samples), “dependent” (telemetered animals are a subset of captured animals) or “concurrent” (histories may be capture-only, telemetry-only or both capture and telemetry).

The telemetry locations are carried over from telemetryCH as attribute ‘xylist’ (eachcomponent of xylist holds the coordinates of one animal; usetelemetryxy to extract).

The default behaviour of 'addTelemetry' is to automatically collapse all telemetry occasions into one. This is computationally more efficient than the alternative, but closes off some possible models.

xy2CH partly reversesaddTelemetry: the locationinformation in the telemetryxy attribute is converted back to a capthist withdetector type ‘telemetry’.

Value

A single-session capthist object with the same detector type asdetectionCH, but possibly with empty rows and an ‘telemetryxy’ attribute.

Note

Telemetry provides independent data on the location and presence of asample of animals. These animals may be missed in the main sampling thatgives rise to detectionCH i.e., they may have all-zero detectionhistories.

The ‘telemetry’ detector type is used for telemetry occasions in a combined dataset.

See Also

capthist,make.telemetry,read.telemetry,telemetryxytelemetered

Examples

## Not run: # Generate some detection and telemetry data, combine them using# addTelemetry, and perform analyses# detectorste <- make.telemetry()tr <- make.grid(detector = "proximity")# simulated population and 50% telemetry sampletotalpop <- sim.popn(tr, D = 20, buffer = 100)tepop <- subset(totalpop, runif(nrow(totalpop)) < 0.5)# simulated detection histories and telemetry# the original animalID (renumber = FALSE) are needed for matchingtrCH <- sim.capthist(tr,  popn = totalpop, renumber = FALSE, detectfn = "HHN")teCH <- sim.capthist(te, popn = tepop, renumber=FALSE, detectfn = "HHN",    detectpar = list(lambda0 = 3, sigma = 25))combinedCH <- addTelemetry(trCH, teCH)# summarise and displaysummary(combinedCH)plot(combinedCH, border = 150)ncapt <- apply(combinedCH,1,sum)points(totalpop[row.names(combinedCH)[ncapt==0],], pch = 1)points(totalpop[row.names(combinedCH)[ncapt>0],], pch = 16)# for later comparison of precision we must fix the habitat maskmask <- make.mask(tr, buffer = 100)fit.tr <- secr.fit(trCH, mask = mask, CL = TRUE, detectfn = "HHN")  ## trapping alonefit.te <- secr.fit(teCH, mask = mask, CL = TRUE, start = log(20),   ## telemetry alone    detectfn = "HHN") fit2   <- secr.fit(combinedCH, mask = mask, CL = TRUE,              ## combined    detectfn = "HHN")                                 # improved precision when focus on realised population# (compare CVD)derived(fit.tr, distribution = "binomial")derived(fit2, distribution = "binomial")# may also use CL = FALSEsecr.fit(combinedCH, CL = FALSE, detectfn = "HHN", trace = FALSE)## End(Not run)

Coerce capthist to Data Frame or Array

Description

Method for genericas.data.frame function that partially reversesmake.capthist.

Usage

## S3 method for class 'capthist'as.data.frame(x, row.names = NULL, optional = FALSE, covariates = FALSE,                                     fmt = c("trapID", "XY"), ...)## S3 method for class 'traps'as.data.frame(x, row.names = NULL, optional = FALSE, usage = FALSE,                               covariates = FALSE, ...)## S3 method for class 'capthist'as.array(x, ...)

Arguments

Details

By default individual covariates are not exported. When exported theyare repeated for each detection of an individual.

Value

A data frame or list of data frames (in the case of a multisession input).

For capthist objects –

The core columns are (Session, ID, Occasion, TrapID) or (Session, ID, Occasion, x, y), depending on the value offmt. Additional columns for covariates and signal strength (detector ‘signal’) are appended to the right.

For traps objects –

The core columns are (x, y). Usage columns are named u1, u2, ..., uS where S is the number of occasions.

Theas.array method for capthist objects returns an object with the same dimensions and dimnames but different class, or a list of such objects in the case of multisession input.

Examples

  as.data.frame (captdata)  as.data.frame (traps(captdata))

Coerce traps object to mask

Description

This function is used primarily for plotting covariates, for which the plot.mask function has greater functionality thanplot.traps. It also generates pretty maps of grid cells.

Usage

as.mask(x)

Arguments

Details

A mask derived by coercion withas.mask may behaveunpredictably e.g., insecr.fit.

Value

Ifx is a single-session traps object –

an object of class c("mask", "data.frame")

Ifx is a multi-session traps object –

an object of class c("mask", "list"), for which each component is asingle-session mask.

See Also

make.mask,plot.mask,mask,traps

Examples

plot(as.mask(traps(captdata)), dots = FALSE, meshcol = "black")plot(traps(captdata), add = TRUE)

Coerce ppp object to popn

Description

This function converts aspatstat "ppp" object (Baddeley et al. 2015), making it easier to use the simulation capability ofspatstat insecr.

Usage

as.popn(x)

Arguments

Details

Not all attributes are carried over.

Value

An object of class c("popn", "data.frame") with attribute "boundingbox". The attribute "Lambda" (spatstat class "im") is also carried over if present (used for the intensity surface of LGCP simulations).

References

Baddeley, A., Rubak, E., and Turner, R. 2015. Spatial Point Patterns: Methodology and Applications with R. Chapman and Hall/CRC Press, London. ISBN 9781482210200, https://www.routledge.com/Spatial-Point-Patterns-Methodology-and-Applications-with-R/Baddeley-Rubak-Turner/p/book/9781482210200/.

See Also

sim.popn,popn

Initial Parameter Values for SECR

Description

Find plausible initial parameter values forsecr.fit. Asimple SECR model is fitted by a fast ad hoc method.

Usage

autoini(capthist, mask, detectfn = 0, thin = 0.2, tol = 0.001,     binomN = 1, adjustg0 = TRUE, adjustsigma = 1.2, ignoreusage = FALSE,     ncores = NULL)

Arguments

Details

Plausible starting values are needed to avoid numericalproblems when fitting SECR models. Actual modelsto be fitted will usually have more than the three basic parametersoutput byautoini; other initial values can usually be set tozero forsecr.fit. If the algorithm encounters problems obtaininga value for g0, the default value of 0.1 is returned.

Only the halfnormal detection function is currently available inautoini (cfother options in e.g.detectfn andsim.capthist).

autoini implements a modified version of the algorithm proposedby Efford et al. (2004). In outline, the algorithm is

1. Find value of sigma that predicts the 2-D dispersion of individual locations (seeRPSV).

2. Find value of g0 that, with sigma, predicts the observed mean number of captures per individual (by algorithm of Efford et al. (2009, Appendix 2))

3. Compute the effective sampling area from g0, sigma, using thinned mask (seeesa)

4. Compute D =n/esa(g0, sigma), wheren is the number of individuals detected

Here ‘find’ means solve numerically for zero difference between the observed and predicted values, usinguniroot.

Halfnormal sigma is estimated withRPSV(capthist, CC = TRUE). The factoradjustsigma is applied as a crude correction for truncation of movements at the edge of the detector array.

IfRPSV cannot be computed the algorithm tries to use observedmean recapture distance\bar{d}. Computation of\bar{d} fails if there no recaptures, and all returnedvalues are NA.

If the mask has more than 100 points then a proportion 1–thin ofpoints are discarded at random to speed execution.

The argumenttol is passed touniroot. It may be avector of two values, the first for g0 and the second for sigma.

Iftraps(capthist) has ausage attribute (defining efforton each occasion at each detector) then the value of g0 is divided bythe mean of the non-zero elements of usage. This adjustment is notprecise.

Ifadjustg0 is TRUE then an adjustment is made to g0 dependingon the value ofbinomN. For Poisson counts (binomN = 0)the adjustment is linear on effort (adjusted.g0 = g0 /usage). Otherwise, the adjustment is on the hazard scale (adjusted.g0 =1 – (1 – g0) ^ (1 / (usage x binomN))). An arithmetic average is takenover all non-zero usage values (i.e. over used detectors and times). Ifusage is not specified it is taken to be 1.0.

Settingncores = NULL uses the existing value from the environment variable RCPP_PARALLEL_NUM_THREADS (seesetNumThreads).

Value

A list of parameter values :

Note

autoini always uses the Euclidean distance between detectors andmask points.

You may get this message from secr.fit: “'autoini' failed to find g0;setting initial g0 = 0.1”. If the fitted model looks OK (reasonableestimates, non-missing SE) there is no reason to worry about thestarting values. If you get this message and model fitting fails thensupply your own values in the start argument of secr.fit.

References

Efford, M. G., Dawson, D. K. and Robbins C. S. (2004) DENSITY: software for analysing capture–recapture data from passive detector arrays.Animal Biodiversity and Conservation27,217–228.

Efford, M. G., Dawson, D. K. and Borchers, D. L. (2009) Populationdensity estimated from locations of individuals on a passive detectorarray.Ecology90, 2676–2682.

See Also

capthist,mask,secr.fit,dbar

Examples

## Not run: demotraps <- make.grid()demomask <- make.mask(demotraps)demoCH <- sim.capthist (demotraps, popn = list(D = 5, buffer = 100), seed = 321)autoini (demoCH, demomask)## End(Not run)

Add Binned Covariate

Description

Forms a new covariate, replacing values of an old covariate by the central value of equal-width bins.

Usage

binCovariate(object, covname, width)

Arguments

Details

The name of the new covariate ispaste0(covname, width).

Fails if covariate not found or is not numeric or there is already a covariate with the new name.

Multi-session objects are handled appropriately.

Value

Object of the same class as the input with new covariate.

See Also

covariates,skink

Examples

# bin values of skink snout-vent length (mm)infraCH <- binCovariate (infraCH, 'SVL', 5)table(covariates(infraCH[[1]])$SVL5)# bin values of trap covariate 'HtBrack' (height of bracken, cm)traps(infraCH) <- binCovariate(traps(infraCH), "HtBrack", 20)table(covariates(traps(infraCH)[[1]])$HtBrack20)

Black Bear Hair Snag Dataset

Description

American black bearsUrsus americanus were surveyed with baited hair snags in the Great Smoky Mountains National Park, Tennessee, in the summer of 2003.

Usage

blackbearCHGSMblackbear.0blackbear.h2bk

Details

American black bearsUrsus americanus were surveyed in the Tennessee sector of Great Smoky Mountains National Park over 9 June–15 August 2003. Baited hair snags (barbed wire enclosures) were operated for 10 weeks at 65 sites, about 1 km apart and mostly close to trails. Bait consisted of bakery products in a small waxed-paper bag. Raspberry extract was used as a scent lure.

Genotyping and non-spatial capture-recapture analysis of a data subset weredescribed by Settlage et al. (2008). The sex of each genotyped bear was determined subsequently and some additional samples were included (J. Laufenberg pers. comm. 2012-05-09; Laufenberg et al. 2013).

The dataset is a single-session capthist object with binary proximity detector type. Snags were visited weekly, so there were 10 occasions in the raw data. A single covariate ‘sex’ was recorded for each individual.

The dataset comprises 282 detections of 81 females and 58 males. Female 15 apparently made a long movement (17 km) between occasions 1 and 3.

The hair snag array sampled less than 20% of the area of the park. The unforested area outside the park on the northwestern boundary of the study area was not considered to be black bear habitat (F. van Manen pers. comm. 2012-05-18) and should be excluded in analyses. The approximate boundary of the park is included as a shapefile ‘GSMboundary.shp’ in the ‘extdata’ folder of the package and as thesf sfc_POLYGON objectGSM. The latter may be used inmake.mask (see Examples).

Two models (blackbear.0 and blackbear.h2bk) were fitted as shown in the Examples.

Source

The data were provided by Jared Laufenberg, Frank van Manen and Joe Clark.

References

Laufenberg, J. S., van Manen, F. T., and Clark, J. D. (2013) Effects of sampling conditions on DNA-based estimates of American black bear abundance.Journal of Wildlife Management77, 1010–1020.

Settlage, K. E., Van Manen, F. T., Clark, J. D., and King, T. L. (2008) Challenges of DNA-based mark–recapture studies of American black bears.Journal of Wildlife Management72, 1035–1042.

Examples

summary(blackbearCH)# GSM is the approximate boundary of Great Smoky Mountains National Park# Make a habitat mask restricted to the parktr <- traps(blackbearCH)msk <- make.mask(tr, buffer = 6000, type = 'trapbuffer', poly = GSM)# Plotplot(GSM)plot(msk, add = TRUE)plot(blackbearCH, tracks = TRUE, add = TRUE)plot(tr, add = TRUE)# Fit models# suppress fastproximity to allow learned responsesetNumThreads()   # as appropriate# null modelblackbear.0 <- secr.fit(blackbearCH,  detectfn = 'EX', hcov = 'sex',     mask = msk, details = list(fastproximity = FALSE), trace = FALSE)# sex differences and site-specific behavioural responseblackbear.h2bk <- secr.fit(blackbearCH,  detectfn = 'EX', hcov = 'sex',     model = list(g0~bk+h2, sigma~h2), mask = msk,     details = list(fastproximity = FALSE), trace = FALSE)    AIC(blackbear.0, blackbear.h2bk)summary(blackbear.h2bk)   # How many if we extrapolate to GSM NP?region.N(blackbear.h2bk, region = GSM)

Spatial Capture History Object

Description

Acapthist object encapsulates all data needed bysecr.fit, except for the optional habitat mask.

Details

An object of classcapthist holds spatial capture histories,detector (trap) locations, individual covariates and other data neededfor a spatially explicit capture-recapture analysis withsecr.fit.

Acapthist is primarily an array of values with dim(capthist) = c(nc,noccasions, ntraps) where nc is the number of detected individuals. Values maybe binary ({–1, 0, 1}) or integer depending on the detector type.

Deaths during the experiment are represented as negative values.

Ancillary data are retained as attributes of acapthist object as follows:

• traps — object of classtraps (required)

• session — session identifier (required)

• covariates — dataframe of individual covariates (optional)

• cutval — threshold of signal strength for detection (‘signal’ only)

• signalframe — signal strength values etc., one row per detection (‘signal’ only)

• detectedXY — dataframe of coordinates for location withinpolygon (‘polygon’-like detectors only)

• xylist — coordinates of telemetered animals

• Tu — detectors x occasions matrix of sightings of unmarked animals

• Tm — detectors x occasions matrix of sightings of marked but unidentified animals

• Tn — detectors x occasions matrix of sightings with unknown mark status

read.capthist is adequate for most data input. Alternatively, the parts of a capthist object can be assembled with the functionmake.capthist. Usesim.capthist for Monte Carlo simulation(simple models only). Methods are provided to display and manipulatecapthist objects (print, summary, plot, rbind, subset, reduce)and to extract and replace attributes (covariates, traps, xy).

A multi-sessioncapthist object is a list in which each componentis acapthist for a single session. The list maybe deriveddirectly from multi-session input in Density format, or by combiningexistingcapthist objects withMS.capthist.

Note

Early versions ofsecr (before 3.0) used an individual x occasion matrix for data from single-catch and multi-catch traps, instead of a 3-D array. Entries in the matrix corresponded to trap numbers. The functionupdateCH converts the old format.

References

Borchers, D. L. and Efford, M. G. (2008) Spatiallyexplicit maximum likelihood methods for capture–recapture studies.Biometrics64, 377–385.

Efford, M. G., Borchers D. L. and Byrom, A. E. (2009) Density estimationby spatially explicit capture-recapture: likelihood-based methods. In:D. L. Thomson, E. G. Cooch and M. J. Conroy (eds)ModelingDemographic Processes in Marked Populations. Springer, New York. Pp.255–269.

See Also

traps,secr.fit,read.capthist,make.capthist,sim.capthist,subset.capthist,rbind.capthist,MS.capthist,reduce.capthist,mask

Dissect Spatial Capture History Object

Description

Extract parts of an object of class ‘capthist’.

Usage

animalID(object, names = TRUE, sortorder = c("snk", "ksn"))occasion(object, sortorder = c("snk", "ksn"))trap(object, names = TRUE, sortorder = c("snk", "ksn"))alive(object, sortorder = c("snk", "ksn"))alongtransect(object, tol = 0.01)xy(object)xy(object) <- valuetelemetryxy(object, includeNULL = FALSE)telemetryxy(object) <- valuetelemetered(object)

Arguments

Details

These functions extract data on detections, ignoring occasions when ananimal was not detected. By default, detections are ordered by occasion, animalIDand trap (sortorder = "snk"). The alternative is to order by trap, occasion and animalID (sortorder = "ksn"). (‘n’, ‘s’ and ‘k’ are the indices used internally for animals, occasions and traps respectively).

For historical reasons, "ksn" is used for locations within polygons and similar (xy).

trap returns polygon or transect numbers iftraps(object)has detector type ‘polygon’ or ‘transect’.

alongtransect returns the distance of each detection from thestart of the transect with which it is associated.

Replacement values must precisely matchobject in number ofdetections and in their order.xy<- expects a dataframe of x and ycoordinates for points of detection within a ‘polygon’ or ‘transect’detector.telemetryxy<- expects a list of dataframes, one per telemetered animal.

Value

ForanimalID andtrap a vector of numeric or character values, one per detection.

Foralive a vector of logical values, one per detection.

Foroccasion, a vector of numeric values, one per detection.

Forxy, a dataframe with one row per detection and columns ‘x’ and ‘y’.

Ifobject has multiple sessions, the result is a list with onecomponent per session.

See Also

capthist,polyID,signalmatrix

Examples

## `captdata' is a demonstration datasetanimalID(captdata)temp <- sim.capthist(popn = list(D = 1), make.grid(detector    = "count"))cbind(ID = as.numeric(animalID(temp)), occ = occasion(temp),    trap = trap(temp))

Overdispersion of Activity Centres

Description

Stochastic variation in the intensity surface may cause the number of detected individualsn to be overdispersed relative to a Poisson distribution (Efford and Fletcher 2025). This can cause the sampling variance of density estimates to be understated.

Usechat.nj to compute Fletcher's\hat c estimate of overdispersion for use as a variance inflation factor. The method requires replicate samples of the intensity surface, such as from multiple independent subgrids. Replicates may be provided as sessions or clusters of detectors within a session (seecluster andtrap.builder).

adjustVarD adjusts the SE and confidence limits of density estimates using the given\hat c. The implementation is limited to simple detection models (see Warnings).

See Cooch and White (2022) for an introduction to measurement of overdispersion in capture–recapture due to non-independence in the detection process. The focus here is on overdispersion of the number detectedn relative to the Poisson (or binomial) distribution ofn expected when the distribution of activity centres is an inhomogeneous or homogeneous Poisson (or binomial) point process (IHPP).

Usage

chat.nj(object, bycluster = FALSE, ...)adjustVarD(object, chatmin = 1, alpha = 0.05, chat = NULL)

Arguments

Details

chat.nj usesexpected.n to compute the expected values.

No adjustment is made byadjustVarD when\hat c is less than the minimum. Set 'chatmin' to zero to override.

adjustVarD also accepts a single dataframe as the argument ‘object’;the dataframe should have row ‘D’ and columns ‘link’, ‘estimate’, ‘SE.estimate’ as in the output frompredict.secr.

Value

Forchat.nj, usually a list comprising –

If ‘verbose = FALSE’ then only the numeric value of\hat c is returned (a vector of 2 values if ‘type = "both"’).

ForadjustVarD, a dataframe with one row for each session, based onpredict.secr orderived.secr, with extra column ‘c-hat’.

Warning

The variance inflation factor given bychat.nk was shown by Efford and Fletcher (2025) to be inadequate and should not be used. For replicate spatial samples,chat.nj is a better alternative.

adjustVarD previously computed Fletcher's ‘chat’ usingchat.nk; that is no longer recommended.

References

Bischof, R., P. Dupont, C. Milleret, J. Chipperfield, and J. A. Royle. 2020. Consequences of ignoring group association in spatial capture–recapture analysis.Wildlife Biology wlb.00649.doi:10.2981/wlb.00649

Cooch, E. and White, G. (eds) (2022)Program MARK: A Gentle Introduction. 22nd edition. Most recent edition available online at www.phidot.org/software/mark/docs/book/.

Efford, M. G. and D. Fletcher. 2025. Effect of spatial overdispersion on confidence intervals for population density estimated by spatial capture-recapture.bioRxiv https://doi.org/10.1101/2024.03.12.584742

Fletcher, D. (2012) Estimating overdispersion when fitting a generalized linear model to sparse data.Biometrika99, 230–237.

Wedderburn, R. W. M. (1974) Quasi-likelihood functions, generalized linear models, and the Gauss-Newtonmethod.Biometrika61, 439–47.

See Also

secr,make.mask,Detection functions,Fletcher.chat,cluster

Examples

## Not run: ## Clustered designmini <- make.grid(nx = 3, ny = 3, spacing = 50, detector = "proximity")tempgrids2 <- trap.builder (    cluster = mini , method = "all",    frame = expand.grid(x = seq(200, 1800, 400), y = seq(200, 1800, 400)),     plt = TRUE)tempmask2 <- make.mask(tempgrids2, buffer = 100, spacing = 20)pop1 <- sim.popn(D = 2, core = tempmask2, model2D = 'rLGCP',                  details = list(var = 0.5, scale = 100))capt <- sim.capthist(tempgrids2, popn = pop1, noccasions = 5,    detectpar = list(g0 = 0.2, sigma = 25))fit <- secr.fit(capt, mask = tempmask2, trace = FALSE)chat.nj(fit, bycluster = TRUE)## End(Not run)

Circular Probability

Description

Functions to answer the question "what radius is expected to includeproportion p of points from a circular bivariate distributioncorresponding to a given detection function", and the reverse. Thesefunctions may be used to relate the scale parameter(s) of a detectionfunction (e.g.,\sigma) to home-range area (specifically, the areawithin an activity contour for the corresponding simple home-rangemodel) (see Note).

WARNING: the default behaviour of these functions changed in version2.6.0. Integration is now performed on the cumulative hazard (exposure)scale for all functions unlesshazard = FALSE. Results willdiffer.

Usage

circular.r (p = 0.95, detectfn = 0, sigma = 1, detectpar = NULL, hazard= TRUE, upper = Inf, ...) circular.p (r = 1, detectfn = 0, sigma = 1, detectpar = NULL, hazard= TRUE, upper = Inf, ...)

Arguments

Details

circular.r is the quantile function of the specified circularbivariate distribution (analogous toqnorm, for example). Thequantity calculated bycircular.r is sometimes called 'circularerror probable' (see Note).

For detection functions with two parameters (intercept and scale) it isenough to providesigma. Otherwise,detectpar should be anamed list including parameter values for the requested detectionfunction (g0 may be omitted, and order does not matter).

Detection functions insecr are expressed in terms of the declinein probability of detection with distanceg(d), and bothcircular.r andcircular.p integrate this function bydefault. Rather than integratingg(d) itself, it may be moreappropriate to integrateg(d) transformed to a hazard i.e.1- log(-g(d)). This is selected withhazard = TRUE.

Integration may also fail with the message “roundoff error is detected in the extrapolation table”. Settingupper to a large number less than infinity sometimes corrects this.

Value

Vector of values for the required radii or probabilities.

Note

The term ‘circular error probable’ has a military origin. It iscommonly used for GPS accuracy with the default probability level set to0.5 (i.e. half of locations are further than CEP from the truelocation). A circular bivariate normal distriubution is commonly assumedfor the circular error probable; this is equivalent to settingdetectfn = "halfnormal".

Closed-form expressions are used for the normal and uniform cases; inthe circular bivariate normal case, the relationship isr =\sigma \sqrt{-2\mathrm{ln}(1-p)}. Otherwise,the probability is computed numerically by integrating the radialdistribution. Numerical integration is not foolproof, so checksuspicious or extreme values.

Whencircular.r is used with the defaultsigma = 1, the resultmay be interpreted as the factor by which sigma needs to be inflated toinclude the desired proportion of activity (e.g., 2.45 sigma for 95%of points from a circular bivariate normal distribution fitted on the hazardscale (detectfn = 14) OR 2.24 sigma on the probability scale (detectfn = 0)).

References

Calhoun, J. B. and Casby, J. U. (1958) Calculation of home range anddensity of small mammals. Public Health Monograph No. 55. United StatesGovernment Printing Office.

Johnson, R. A. and Wichern, D. W. (1982) Applied multivariatestatistical analysis. Prentice-Hall, Englewood Cliffs, New Jersey, USA.

See Also

detectfn,detectfnplot

Examples

## Calhoun and Casby (1958) p 3.## give p = 0.3940, 0.8645, 0.9888circular.p(1:3, hazard = FALSE)## halfnormal, hazard-rate and exponentialcircular.r ()circular.r (detectfn = "HR", detectpar = list(sigma = 1, z = 4))circular.r (detectfn = "EX")circular.r (detectfn = "HHN")circular.r (detectfn = "HHR", detectpar = list(sigma = 1, z = 4))circular.r (detectfn = "HEX")plot(seq(0, 5, 0.05), circular.p(r = seq(0, 5, 0.05)),    type = "l", xlab = "Radius (multiples of sigma)", ylab = "Probability")lines(seq(0, 5, 0.05), circular.p(r = seq(0, 5, 0.05), detectfn = 2),    type = "l", col = "red")lines(seq(0, 5, 0.05), circular.p(r = seq(0, 5, 0.05), detectfn = 1,    detectpar = list(sigma = 1,z = 4)), type = "l", col = "blue")abline (h = 0.95, lty = 2)legend (2.8, 0.3, legend = c("halfnormal","hazard-rate, z = 4", "exponential"),    col = c("black","blue","red"), lty = rep(1,3))## in this example, a more interesting comparison would use## sigma = 0.58 for the exponential curve.

Replicate Rows

Description

Clone rows of an object a constant or random number of times

Usage

  ## Default S3 method:clone(object, type, ...)  ## S3 method for class 'popn'clone(object, type, ...)  ## S3 method for class 'capthist'clone(object, type, ...)

Arguments

Details

The ... argument specifies the number of times each row should berepeated. For random distributions (Poisson or negative binomial) ...provides the required parameter values:lambda for Poisson,size, prob orsize, mu for negative binomial.

One application is to derive a population of cues from a popn object,where each animal in the original popn generates a number of cues fromthe same point.

Cloning a capthist object replicates whole detectionhistories. Individual covariates and detection-specific attributes(e.g., signal strength or xy location in polygon) are alsoreplicated. Cloned data from single-catch traps will cause verify() tofail, but a model may still be fitted insecr.fit by overridingthe check withverify = FALSE.

Value

Object of same class asobject but with varying number ofrows. Forclone.popn andcapthist an attribute ‘freq’ isset, a vector of length equal to the original number of rows giving thenumber of repeats (including zeros).

Ifpopn orcapthist is a multi-session object the returned value will bea multi-session object of the same length.

See Also

sim.popn

Examples

## population of animals at 1 / hectare generates random## Poisson number of cues, lambda = 5mics4 <- make.grid( nx = 2, ny = 2, spacing = 44, detector = "signal")pop <- sim.popn (D = 1, core = mics4, buffer = 300, nsessions = 6)pop <- clone (pop, "poisson", 5)attr(pop[[1]],"freq")clone(captdata, "poisson", 3)# To avoid losing any individuals use zero-truncated Poisson# First find lambda of truncated Poisson with given meangetlambda <- function (target) {    fn <- function(x) x / (1-exp(-x)) - target    uniroot(interval = c(1e-8, target), f = fn)$root}clone(captdata, "truncatedpoisson", getlambda(3))

Closed population estimates

Description

Estimate N, the size of a closed population, by several conventionalnon-spatial capture–recapture methods.

Usage

closedN(object, estimator = NULL, level = 0.95, maxN = 1e+07,    dmax = 10 )

Arguments

Details

Data are provided as spatial capture histories, but the spatialinformation (trapping locations) is ignored.

AIC-based model selection is available for the maximum-likelihoodestimatorsnull,zippin,darroch,h2, andbetabinomial.

Model weights are calculated as

w_i = \frac{\exp(-\Delta_i / 2)}{ \sum{\exp(-\Delta_i / 2)}}

Models for which dAICc >dmax are given a weight of zero and areexcluded from the summation, as are non-likelihood models.

Computation ofnull,zippin anddarroch estimatesdiffers slightly from Otis et al. (1978) in that the likelihood ismaximized over real values of N betweenMt1 andmaxN,whereas Otis et al. considered only integer values.

Asymmetric confidence intervals are obtained in the same way for allestimators, using a log transformation of\hat{N}-Mt1following Burnham et al. (1987), Chao (1987) and Rexstad and Burnham(1991).

The available estimators are

Value

A dataframe with one row per estimator and columns

Warning

If your data are from spatial sampling (e.g. grid trapping) it isrecommended that you donot use these methods to estimatepopulation size (see Efford and Fewster 2013). Instead, fit a spatial modeland estimate population size withregion.N.

Note

Prof. Anne Chao generously allowed me to adapt her code for thevariance of the ‘chao.th1’ and ‘chao.th2’ estimators.

Chao's estimators have been subject to various improvements notincluded here (e.g., Chao et al. 2016).

References

Burnham, K. P. and Overton, W. S. (1978) Estimating the size of a closedpopulation when capture probabilities vary amonganimals.Biometrika65, 625–633.

Chao, A. (1987) Estimating the population size for capture–recapturedata with unequal catchability.Biometrics43, 783–791.

Chao, A., Ma, K. H., Hsieh, T. C. and Chiu, Chun-Huo (2016) SpadeR: Species-Richness Prediction andDiversity Estimation with R. R package version 0.1.1. https://CRAN.R-project.org/package=SpadeR

Dorazio, R. M. and Royle, J. A. (2003) Mixture models for estimating thesize of a closed population when capture rates vary amongindividuals.Biometrics59, 351–364.

Efford, M. G. and Fewster, R. M. (2013) Estimating populationsize by spatially explicit capture–recapture.Oikos122, 918–928.

Hurvich, C. M. and Tsai, C. L. (1989) Regression and time series modelselection in small samples.Biometrika76, 297–307.

Lee, S.-M. and Chao, A. (1994) Estimating population size via samplecoverage for closed capture-recapture models.Biometrics50, 88–97.

Otis, D. L., Burnham, K. P., White, G. C. and Anderson, D. R. (1978)Statistical inference from capture data on closed animalpopulations.Wildlife Monographs62, 1–135.

Pledger, S. (2000) Unified maximum likelihood estimates for closedcapture-recapture models using mixtures.Biometrics56,434–442.

Rexstad, E. and Burnham, K. (1991) User's guide for interactive programCAPTURE. Colorado Cooperative Fish and Wildlife Research Unit, FortCollins, Colorado, USA.

See Also

capthist,closure.test,region.N

Examples

closedN(deermouse.ESG)

Closure tests

Description

Perform tests to determine whether a population sampled bycapture-recapture is closed to gains and losses over the period of sampling.

Usage

closure.test(object, SB = FALSE, min.expected = 2)

Arguments

Details

The test of Stanley and Burnham in part uses a sum over 2x2 contingencytables; any table with a cell whose expected count is less thanmin.expected is dropped from the sum. The default value of 2 is thatused by CloseTest (Stanley and Richards 2005, T. Stanley pers. comm.;see also Stanley and Burnham 1999 p. 203).

Value

In the case of a single-session capthist object, either a vector withthe statistic (z-value) and p-value for the test of Otis et al. (1978p. 120) or a list whose components are data frames with the statisticsand p-values for various tests and test components as follows –

Check the original papers for an explanation of the components of the Stanley and Burnham test.

In the case of a multi-session object, a list with one component (asabove) for each session.

Note

No omnibus test exists for closure: the existing tests may indicatenonclosure even when a population is closed if other effects such astrap response are present (see White et al. 1982 pp 96–97). The test ofStanley and Burnham is sensitive to individual heterogeneity which isinevitable in most spatial sampling, and it should not in general beused for this sort of data.

References

Otis, D. L., Burnham, K. P., White, G. C. and Anderson, D. R. (1978)Statistical inference from capture data on closed animalpopulations.Wildlife Monographs62, 1–135.

Stanley, T. R. and Burnham, K. P. (1999) A closure test fortime-specific capture–recapture data.Environmental andEcological Statistics6, 197–209.

Stanley, T. R. and Richards, J. D. (2005) A program for testingcapture–recapture data for closure.Wildlife Society Bulletin33, 782–785.

White, G. C., Anderson, D. R., Burnham, K. P. and Otis, D. L. (1982)Capture-recapture and removal methods for sampling closedpopulations. Los Alamos National Laboratory, Los Alamos, New Mexico.

See Also

capthist

Examples

 closure.test(captdata)

Detector Clustering

Description

Clusters are uniform groups of detectors. Use these functions toextract or replace cluster information of atraps object, orextract cluster information for each detection in acapthistobject.

Usage

clusterID(object)clusterID(object) <- valueclustertrap(object)clustertrap(object) <- value

Arguments

Details

Easy access to attributes used to define compound designs, those inwhich a detector array comprises several similar subunits(‘clusters’). ‘clusterID’ identifies the detectors belonging to eachcluster, and ‘clustertrap’ is a numeric index used to relate matchingdetectors in different clusters.

For replacement (‘traps’ only), the number of rows ofvaluemust match exactly the number of detectors inobject.

‘clusterID’ and ‘clustertrap’ are assigned automatically bytrap.builder. They may also be assigned to the traps object post hoc.

Value

Factor (clusterID) or integer-valued vector(clustertrap).

clusterID(object) may be NULL.

See Also

traps,trap.builder,mash,derivedCluster,cluster.counts,cluster.centres

Examples

## 25 4-detector clustersmini <- make.grid(nx = 2, ny = 2)tempgrid <- trap.builder (cluster = mini , method = "all",    frame = expand.grid(x = seq(100, 500, 100), y = seq(100,    500, 100)))clusterID(tempgrid)clustertrap(tempgrid)tempCH <- sim.capthist(tempgrid)table(clusterID(tempCH)) ## detections per clustercluster.counts(tempCH)   ## distinct individuals

Coefficients of secr Object

Description

Extract coefficients (estimated beta parameters) from a spatiallyexplicit capture–recapture model.

Usage

## S3 method for class 'secr' coef(object, alpha = 0.05, ...)

Arguments

Value

A data frame with one row per beta parameter and columns for thecoefficient, SE(coefficient), asymptotic lower and upper 100(1–alpha)confidence limits.

See Also

secr.fit,esaPlot

Examples

## load & extract coefficients of previously fitted null modelcoef(secrdemo.0)

Array of Parameter Estimates

Description

Estimates from one or more openCR models are formed into an array.

Usage

## S3 method for class 'secr'collate(object, ..., realnames = NULL, betanames = NULL, newdata = NULL,     alpha = 0.05, perm = 1:4, fields = 1:4)## S3 method for class 'ipsecr'collate(object, ..., realnames = NULL, betanames = NULL, newdata = NULL,     alpha = 0.05, perm = 1:4, fields = 1:4)## S3 method for class 'secrlist'collate(object, ..., realnames = NULL, betanames = NULL, newdata = NULL,     alpha = 0.05, perm = 1:4, fields = 1:4)

Arguments

Details

collate extracts parameter estimates from a set of fitted secrmodel objects.

fields may be used to select a subset of summaryfields ("estimate","SE.estimate","lcl","ucl") by name or number.

Value

A 4-dimensional array of model-specific parameter estimates. By default, the dimensions correspond respectively to

• rows innewdata (usually sessions),

• models,

• statistic fields (estimate, SE.estimate, lcl, ucl), and

• parameters ("phi", "sigma" etc.).

It often helps to reorder the dimensions with theperm argument.

See Also

modelAverage,secr.fit

Examples

collate (secrdemo.0, secrdemo.b, perm = c(4,2,3,1))[,,1,]

Profile Likelihood Confidence Intervals

Description

Compute profile likelihood confidence intervals for ‘beta’ or ‘real’ parameters of aspatially explicit capture-recapture model,

Usage

## S3 method for class 'secr' confint(object, parm, level = 0.95, newdata = NULL,tracelevel = 1, tol = 0.0001, bounds = NULL, ncores = NULL, ...)

Arguments

Details

Ifparm is numeric its elements are interpreted as the indices of‘beta’ parameters; character values are interpreted as ‘real’parameters. Different methods are used for beta parameters and realparameters. Limits for thej-th beta parameter are found by anumerical search for the value satisfying-2(l_j(\beta_j) - l) =q, wherel is the maximized loglikelihood,l_j(\beta_j) is the maximized profile loglikelihood with\beta_j fixed, andq is the100(1-\alpha) quantile of the\chi^2 distribution with one degree of freedom. Limitsfor real parameters use the method of Lagrange multipliers (Fletcher andFaddy 2007), except that limits for constant real parameters arebacktransformed from the limits for the relevant beta parameter.

Ifbounds is provided it should be a 2-vector or matrix of 2columns and length(parm) rows.

Settingncores = NULL uses the existing value from the environment variable RCPP_PARALLEL_NUM_THREADS (seesetNumThreads).

Value

A matrix with one row for each parameter inparm, and columnsgiving the lower (lcl) and upper (ucl) 100*level

Note

Calculation may take a long time, so probably you will do itonly after selecting a final model.

TheR functionuniroot is used to search for the roots of-2(l_j(\beta_j) - l) = q within asuitable interval. The interval is anchored at one end by the MLE, andat the other end by the MLE inflated by a small multiple of theasymptotic standard error (1, 2, 4 or 8 SE are tried in turn, using thesmallest for which the interval includes a valid solution).

A more efficient algorithm was proposed by Venzon and Moolgavkar (1988);it has yet to be implemented insecr, but seeplkhci inthe packageBhat for anotherR implementation.

References

Evans, M. A., Kim, H.-M. and O'Brien, T. E. (1996) An application ofprofile-likelihood based confidence interval to capture–recaptureestimators.Journal of Agricultural, Biological and ExperimentalStatistics1, 131–140.

Fletcher, D. and Faddy, M. (2007) Confidence intervals for expectedabundance of rare species.Journal of Agricultural, Biological andExperimental Statistics12, 315–324.

Venzon, D. J. and Moolgavkar, S. H. (1988) A method for computingprofile-likelihood-based confidence intervals.Applied Statistics37, 87–94.

Examples

## Not run: ## Limits for the constant real parameter "D"confint(secrdemo.0, "D")   ## End(Not run)

Contour Detection Probability

Description

Display contours of the net probability of detection p.(X), or thearea within a specified distance of detectors.bufferContouradds a conventional ‘boundary strip’ to a detector (trap) array, wherebuffer equals the strip width.

Usage

pdotContour(traps, border = NULL, nx = 64, detectfn = 0,    detectpar = list(g0 = 0.2, sigma = 25, z = 1), noccasions = NULL,    binomN = NULL, levels = seq(0.1, 0.9, 0.1), poly =    NULL, poly.habitat = TRUE, plt = TRUE, add = FALSE, fill = NULL, ...)bufferContour(traps, buffer, nx = 64, convex = FALSE, ntheta = 100,     plt = TRUE, add = FALSE, poly = NULL, poly.habitat = TRUE,      fill = NULL, ...)

Arguments

Details

pdotContour constructs a rectangular mask and appliespdot tocompute the p.(X) at each mask point.

Ifconvex = FALSE,bufferContour constructs a mask andcontours the points on the basis of distance to the nearest detector at thelevels given inbuffer.

Ifconvex = TRUE,bufferContour constructs a set ofpotential vertices by adding points on a circle of radius =buffer to each detector location; the desired contour is theconvex hull of these points (this algorithm derives from Efford, 2012).

Iftraps has ausage attribute thennoccasions isset accordingly; otherwise it must be provided.

Iftraps is for multiple sessions then detectpar should be a listof the same length, one component per session, and noccasions may be anumeric vector of the same length.

Increasenx for smoother lines, at the expense of speed.

Value

Coordinates of the plotted contours are returned as a list with onecomponent per polygon. The list is returned invisibly ifplt = TRUE.

For multi-session input (traps) the value is a list of suchlists, one per session.

Note

The precision (smoothness) of the fitted line inbufferContouris controlled byntheta rather thannx whenconvex = TRUE.

To suppress contour labels, include the argumentdrawlabels = FALSE (this will be passed via ... tocontour). Other usefularguments ofcontour arecol (colour of contour lines)andlwd (line width).

You may wish to consider function st_buffer in packagesf as analternative tobufferContour.

bufferContour failed with multi-sessiontraps beforesecr 2.8.0.

References

Efford, M. G. (2012)DENSITY 5.0: software for spatiallyexplicit capture–recapture. Department of Mathematics and Statistics,University of Otago, Dunedin, New Zealandhttps://www.otago.ac.nz/density/.

See Also

pdot,make.mask

Examples

possumtraps <- traps(possumCH)## convex and concave buffersplot(possumtraps, border = 270)bufferContour(possumtraps, buffer = 100, add = TRUE, col = "blue")bufferContour(possumtraps, buffer = 100, convex = TRUE, add = TRUE)## areasbuff.concave <- bufferContour(possumtraps, buffer = 100,    plt = FALSE)buff.convex  <- bufferContour(possumtraps, buffer = 100,    plt = FALSE, convex = TRUE)sum (sapply(buff.concave, polyarea)) ## sum over partssapply(buff.convex, polyarea)## effect of nx on areabuff.concave2 <- bufferContour(possumtraps, buffer = 100,    nx = 128, plt = FALSE)sum (sapply(buff.concave2, polyarea))## Not run: plot(possumtraps, border = 270)pdotContour(possumtraps, detectfn = 0, nx = 128, detectpar =    detectpar(possum.model.0), levels = c(0.1, 0.01, 0.001),    noccasions = 5, add = TRUE)## clipping to polygonolddir <- setwd(system.file("extdata", package = "secr"))possumtraps <- traps(possumCH)possumarea <- read.table("possumarea.txt", header = TRUE)par(xpd = TRUE, mar = c(1,6,6,6))plot(possumtraps, border = 400, gridlines = FALSE)pdotContour(possumtraps, detectfn = 0, nx = 256, detectpar =    detectpar(possum.model.0), levels = c(0.1, 0.01, 0.001),    noccasions = 5, add = TRUE, poly = possumarea, col = "blue")lines(possumarea)setwd(olddir)par(xpd = FALSE, mar = c(5,4,4,2) + 0.1)    ## reset to default## End(Not run)

Covariates Attribute

Description

Extract or replace covariates

Usage

covariates(object, ...)covariates(object) <- value

Arguments

Details

For replacement, the number of rows ofvalue must match exactly the number of rows inobject.

Value

covariates(object) returns the dataframe of covariates associated withobject.covariates(object) may be NULL.

Individual covariates are stored in the ‘covariates’ attribute of acapthist object.

Covariates used for modelling density are stored in the ‘covariates’attribute of amask object.

Detector covariates may vary between sampling occasions. In this case,columns in the detector covariates data.frame are associated withparticular times; the matching is controlled by thetimevaryingcov attribute.

See Also

timevaryingcov

Examples

## detector covariatestemptrap <- make.grid(nx = 6, ny = 8)covariates (temptrap) <- data.frame(halfnhalf =     factor(rep(c("left","right"),c(24,24))) )summary(covariates(temptrap))

Deermouse Live-trapping Datasets

Description

Data of V. H. Reid from live trapping of deermice (Peromyscusmaniculatus) at two sites in Colorado, USA.

Usage

deermouse.ESGdeermouse.WSG

Details

Two datasets of V. H. Reid were described by Otis et al. (1978) anddistributed with their CAPTURE software. They have been used inseveral other papers on closed population methods (e.g., Huggins 1991,Stanley and Richards 2005). This description is based on pages 32 and87–93 of Otis et al. (1978).

Both datasets are from studies in Rio Blanco County, Colorado, in thesummer of 1975. Trapping was for 6 consecutive nights. Traps werearranged in a 9 x 11 grid and spaced 50 feet (15.2 m) apart.

The first dataset was described by Otis et al. (1978: 32) as from 'adrainage bottom of sagebrush, gambel oak, and serviceberry with pinyonpine and juniper on the uplands'. By matching with the ‘examples’ fileof CAPTURE this was from East Stuart Gulch (ESG).

The second dataset (Otis et al. 1978: 87) was from Wet Swizer Creek orGulch (WSG) in August 1975. No specific vegetation description is givenfor this site, but it is stated that Sherman traps were used andtrapping was done twice daily.

Two minor inconsistencies should be noted. Although Otis et al. (1978)said they used data from morning trap clearances, the capture historiesin ‘examples’ from CAPTURE include a ‘pm’ tag on each record. Weassume the error was in the text description, as their numerical resultscan be reproduced from the data file. Huggins (1991) reproduced the EastStuart Gulch dataset (omitting spatial data that were not relevant to hismethod), but omitted two capture histories.

The data are provided as two single-sessioncapthist objects‘deermouse.ESG’ and ‘deermouse.WSG’. Each has a dataframe of individualcovariates, but the fields differ between the two study areas. Theindividual covariates of deermouse.ESG are sex (factor levels ‘f’, ‘m’),age class (factor levels ‘y’, ‘sa’, ‘a’) and body weight in grams. Theindividual covariates of deermouse.WSG are sex (factor levels ‘f’,‘m’)and age class (factor levels ‘j’, ‘y’, ‘sa’, ‘a’) (no data on bodyweight). The aging criteria used by Reid are not recorded.

The datasets were originally in the CAPTURE ‘xy complete’ format whichfor each detection gives the ‘column’ and ‘row’ numbers of the trap(e.g. ‘ 9 5’ for a capture in the trap at position (x=9, y=5) on thegrid). Trap identifiers have been recoded as strings with no spaces byinserting zeros (e.g. ‘905’ in this example).

Sherman traps are designed to capture one animal at a time, but the datainclude double captures (1 at ESG and 8 at WSG – see Examples). The truedetector type therefore falls between ‘single’ and ‘multi’. Detectortype is set to ‘multi’ in the distributed data objects.

Source

File ‘examples’ distributed with program CAPTURE.

References

Huggins, R. M. (1991) Some practical aspects of a conditional likelihoodapproach to capture experiments.Biometrics47, 725–732.

Otis, D. L., Burnham, K. P., White, G. C. and Anderson, D. R. (1978)Statistical inference from capture data on closed animalpopulations.Wildlife Monographs62, 1–135.

Stanley, T. R. and Richards, J. D. (2005) A program for testingcapture–recapture data for closure.Wildlife Society Bulletin33, 782–785.

See Also

closure.test

Examples

par(mfrow = c(1,2), mar = c(1,1,4,1))plot(deermouse.ESG, title = "Peromyscus data from East Stuart Gulch",    border = 10, gridlines = FALSE, tracks = TRUE)plot(deermouse.WSG, title = "Peromyscus data from Wet Swizer Gulch",    border = 10, gridlines = FALSE, tracks = TRUE)closure.test(deermouse.ESG, SB = TRUE)## reveal multiple capturestable(trap(deermouse.ESG), occasion(deermouse.ESG))table(trap(deermouse.WSG), occasion(deermouse.WSG))

Edit Mask Points

Description

Mask points may be removed by one of three methods:clicking on points, clicking on vertices to define a polygon fromwhich points will be removed, or specifying a polygon to which themask will be clipped.

Usage

deleteMaskPoints(mask, onebyone = TRUE, add = FALSE, poly = NULL, poly.habitat = FALSE, ...)

Arguments

Details

The default method (onebyone = TRUE, poly = NULL) is to click on eachpoint to be removed. The nearest mask point will be selected.

Setting onebyone = FALSE allows the user to click on the vertices of apolygon within which all points are to be removed (the default) orretained (poly.habitat = TRUE). Vertices need notcoincide with mask points.

Definingpoly here is equivalent to callingmake.maskwithpoly defined.poly one of the several types described inboundarytoSF. Whetherpoly represents habitat ornon-habitat is toggled withpoly.habitat – the default herediffers frommake.mask.

Value

A mask object, usually with fewer points than the input mask.

See Also

make.mask,subset.mask

Examples

if (interactive()) {    mask0 <- make.mask (traps(captdata))    ## Method 1 - click on each point to remove    mask1 <- deleteMaskPoints (mask0)    ## Method 2 - click on vertices of removal polygon    mask2 <- deleteMaskPoints (mask0, onebyone = FALSE)    ## Method 3 - predefined removal polygon    plot(captdata)    poly1 <- locator(5)    mask3 <- deleteMaskPoints (mask0, poly = poly1)}

Derived Parameters of Fitted SECR Model

Description

Compute derived parameters of spatially explicit capture-recapture model. Density is a derived parameter when a model is fitted by maximizing the conditional likelihood. So also is the effective sampling area (in the sense of Borchers and Efford 2008).

Usage

derived(object, ...)## S3 method for class 'secr'derived(object, sessnum = NULL, groups = NULL, alpha = 0.05,     se.esa = FALSE, se.D = TRUE, loginterval = TRUE, distribution = NULL,     ncores = NULL, bycluster = FALSE, Dweight = FALSE, ...)## S3 method for class 'secrlist'derived(object, sessnum = NULL, groups = NULL, alpha = 0.05,     se.esa = FALSE, se.D = TRUE, loginterval = TRUE, distribution = NULL,     ncores = NULL, bycluster = FALSE, Dweight = FALSE, ...)## S3 method for class 'secr'esa(object, sessnum = 1, beta = NULL, real = NULL, noccasions = NULL,     ncores = NULL, Dweight = FALSE, ...)

Arguments

Details

The derived estimate of density is a Horvitz-Thompson-like estimate:

\hat{D} = \sum\limits _{i=1}^{n} {a_i (\hat{\theta})^{-1}}

wherea_i (\hat{\theta}) is the estimate of effective sampling area for animali with detection parameter vector\theta.

A non-null value of the argumentdistribution overrides the valueinobject$details. The sampling variance of\hat{D}fromsecr.fit by default is spatially unconditional(distribution = "Poisson"). For sampling variance conditional on the population of thehabitat mask (and therefore dependent on the mask area), specifydistribution = "binomial". The equation for the conditionalvariance includes a factor(1 - a/A) that disappears in theunconditional (Poisson) variance (Borchers and Efford 2007). Thus theconditional variance is always less than the unconditional variance. Theunconditional variance may in turn be an overestimate or (more likely)an underestimate if the true spatial variance is non-Poisson.

Derived parameters may be estimated for population subclasses (groups)defined by the user with thegroups argument. Each named factoringroups should appear in the covariates dataframe ofobject$capthist (or each of its components, in the case of amulti-session dataset).

esa is used byderived to compute individual-specificeffective sampling areas:

a_i (\hat{\theta}) = \int _A \:p.(\mathbf{X};\mathbf{z}_i, \mathbf{\hat{\theta}}) \; \mathrm{d}\mathbf{X}

wherep.(\mathbf{X}) is the probability an individual at X isdetected at least once and the\mathbf{z}_i are optionalindividual covariates. Integration is over the areaA of thehabitat mask.

The argumentnoccasions may be used to vary the number ofsampling occasions; it works only when detection parameters are constantacross individuals and across time.

Settingncores = NULL uses the existing value from the environment variable RCPP_PARALLEL_NUM_THREADS (seesetNumThreads).

The effective sampling area ‘esa’ (a(\hat{\theta}))reported byderived is equal to the harmonic mean of thea_i (\hat{\theta}) (arithmeticmean prior to version 1.5). The sampling variance ofa(\hat{\theta}) is estimated by

\widehat{\mathrm{var}}(a(\hat{\theta})) = \hat{G}_\theta^T\hat{V}_\theta \hat{G}_\theta,

where\hat{V} is the asymptotic estimate of thevariance-covariance matrix of the beta detection parameters(\theta) and\hat{G} is a numerical estimateof the gradient ofa(\theta) with respect to\theta, evaluated at\hat{\theta}.

A 100(1–alpha)% asymptotic confidence interval is reported fordensity. By default, this is asymmetric about the estimate because thevariance is computed by backtransforming from the log scale. You may also choose a symmetric interval (variance obtained on natural scale).

The vector of detection parameters foresa may be specified viabeta orreal, with the former taking precedence. Ifneither is provided then the fitted values inobject$fit$par areused. Specifyingreal parameter values bypasses the variouslinear predictors. Strictly, the ‘real’ parameters are for a naivecapture (animal not detected previously).

The computation of sampling variances is relatively slow and may besuppressed withse.esa andse.D as desired.

For computingderived across multiple models in parallel seepar.derived.

Fromsecr 5.0.0 the ... argument may be used to control the step size (.relStep) used byfdHess when estimating gradients for SE(D) and SE(esa).

Value

Dataframe with one row for each derived parameter (‘esa’, ‘D’) andcolumns as below

For a multi-session or multi-group analysis the value is a listwith one component for each session and group.

The result will also be a list ifobject is an ‘secrlist’.

Warning

derived() may be applied to detection models fitted by maximizing the full likelihood (CL = FALSE). However, models using g (groups) will not be handled correctly.

Note

Before version 2.1, the output table had columns for ‘varcomp1’ (the variance in\hat{D} due to variation inn, i.e.,Huggins's^2), and ‘varcomp2’ (the variance in\hat{D} due to uncertainty in estimates of detection parameters).

These quantities are related to CVn and CVa as follows:

\mathrm{CVn} = \sqrt{ \mathrm{varcomp1} } / \hat{D}

\mathrm{CVa} = \sqrt{ \mathrm{varcomp2} } / \hat{D}

References

Borchers, D. L. and Efford, M. G. (2007) Supplements to Biometrics paper. Available online athttps://www.otago.ac.nz/density/.

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

Huggins, R. M. (1989) On the statistical analysis of capture experiments.Biometrika76, 133–140.

See Also

predict.secr,print.secr,secr.fit,empirical.varD

Examples

## Not run: ## extract derived parameters from a model fitted previously## by maximizing the conditional likelihood derived (secrdemo.CL)## what happens when sampling variance is conditional on mask N?derived(secrdemo.CL, distribution = "binomial")## fitted g0, sigmaesa(secrdemo.CL)## force different g0, sigmaesa(secrdemo.CL, real = c(0.2, 25))## End(Not run)

Derived Absolute Density

Description

A relative density model (one fitted by maximising the conditional likelihood) has a zero intercept for density on the default log scale (the intercept is 1.0 for the identity link).

The constantk that relates absolute density to relative densityD^\prime = k^{-1} D is obtained as described in Efford (2025).

These functions infer the value ofk and use this to construct the predicted density surface (predictDsurface is the equivalent function for full-likelihood models).

Thederived method for ‘secr’ objects performs the same calculation asderivedDcoef and also back-transforms the intercept and computes a delta-method estimate of its variance and confidence limits. However that variance estimate is unreliable.

derivedDfit constructs an secr fitted model object resembling that from an unconditional model fit.

Usage

## S3 method for class 'secr'derivedDcoef(object, se = FALSE, ...)## S3 method for class 'secrlist'derivedDcoef(object, se = FALSE, ...)derivedDsurface(object, mask = NULL, sessnum = NULL, groups = NULL)derivedDfit(object, vcv = TRUE)

Arguments

Details

The theory is provided by Efford in prep.

derivedDcoef(object, se = TRUE) is equivalent toderived(object, Dweight = TRUE), althoughderivedDcoef returns estimates on the link scale.

Value

For derivedDcoef –

A dataframe mimickingcoef(object) with an initial row for the derived density intercept\beta_0.For an identity link, subsequent density coefficients are scaled by the derived\beta_0.

For derivedDsurface –

Dsurface object with class c("Dsurface", "mask", "data.frame"). Multi-session if object is multi-session and sessnum = NULL.

If groups are defined the result is a list of Dsurfaces.

References

Efford, M. G. In prep. SECR models for relative density.

See Also

derived

predictDsurface

Detail Specification for secr.fit

Description

The functionsecr.fit allows many options. Some of these are usedinfrequently and have been bundled as a single argumentdetailsto simplify the documentation. They are described here. Some components (param, relativeD) are primarily used to record the type of model fitted that is an indirect result of other settings.

Detail components

details$autoini specifies the session number from which to compute starting values (multi-session data only; default 1). From 4.0.0, the character value ‘all’ first forms a single-session capthist usingjoin(); this may be slow or not work at all (especially with telemetry data).

details$centred = TRUE causes coordinates of both traps and maskto be centred on the centroid of the traps, computed separately for eachsession in the case of multi-session data. This may be necessary toovercome numerical problems when x- or y-coordinates are largenumbers. The default is not to centre coordinates.

details$chat optionally specifies the overdispersion of unmarked sightings Tu and unidentified marked sightings Tm. It is used only for mark-resight models, and is usually computed withinsecr.fit (details$nsim > 0), but may be provided by the user. For a single session'chat' is a vector of length 2; for multiple sessions it is a 2-column matrix.

details$chatonly = TRUE used withdetails$nsim > 0 causes the overdispersion statistics for sighting counts Tu and Tm to be estimated and returned as a vector or 2-column matrix (multi-session models), with no furthermodel fitting.

details$contrasts may be used to specify the coding of factor predictors. The value should be suitable for the 'contrasts.arg' argument ofmodel.matrix. See ‘Trend across sessions’ insecr-multisession.pdf for an example.

details$convexpolygon may be set to FALSE for searches of non-convex polygons. This is slower than the default which requires poygons to be convex east-west (secr-polygondetectors.pdf).

details$debug is an integer code used to control the printing of intermediate values (1,2) and to switch on the R code browser (3). In ordinary use it should not be changed from the default (0).

details$Dfn is a function for reparameterizing density models; this is set internally when Dlambda = TRUE. Exotic variations may be specified directly by the user when Dlambda = FALSE. The defaults (Dfn = NULL, Dlambda = FALSE) leavethe original density model unchanged. Note there is no connection to userDfn (except that the two are incompatible).

Dlambda if TRUE causes reparameterization of density as the session-on-session finite rate of increaselambda. Details at (secr-trend.pdf).

details$distribution specifies the distribution of the number ofindividuals detectedn; this may be conditional on the number in themasked area ("binomial") or unconditional ("poisson").distribution affects the sampling variance of the estimateddensity. The default is "poisson". The component ‘distribution’ may alsotake a numeric value larger than nrow(capthist), rather than "binomial"or "poisson". The likelihood then treats n as a binomial draw from asuperpopulation of this size, with consequences for the variance ofdensity estimates. This can help to reconcile MLE with Bayesianestimates using data augmentation.

details$externalpdot names a mask covariate that is used as an offset for relative density. This can be useful in a two-phase study when animals are tagged in phase one and sampled in phase two, with no further tagging (Efford in prep.). The covariate may differ fromp.(x) by a constant factor.

details$fastproximity controls special handling of data from binary proximity and count detectors. If TRUE and other conditions are met (no temporal variation or groups) then a multi-occasion capthist is automatically reduced to a count for a single occasion and further compressed by storing only non-zero counts, which can greatly speed up computation of the likelihood (default TRUE).

details$fixedbeta may be used to fix values of betaparameters. It should be a numeric vector of length equal to the totalnumber of beta parameters (coefficients) in the model. Parameters to beestimated are indicated by NA. Other elements should be valid values onthe link scale and will be substituted during likelihoodmaximisation. Check the order of beta parameters in a previously fittedmodel.

details$grain sets the grain argument for multithreading in RcppParallel parallelFor (default 1).details$grain = 0 suppresses multithreading (equivalent toncores = 1).

details$hessian is a character string controlling the computationof the Hessian matrix from which variances and covariances are obtained.Options are "none" (no variances), "auto" (the default) or "fdhess" (usethe function fdHess innlme). If "auto" then the Hessian from theoptimisation function is used.

details$ignoreusage = TRUE causes the function to ignoreusage (varying effort) information in the traps component. The default(details$ignoreusage = FALSE) is to include usage in the model.

details$intwidth2 controls the half-width of the intervalsearched by optimise() for the maximum likelihood when there is a singleparameter. Default 0.8 sets the search interval to(0.2s, 1.8s) wheresis the ‘start’ value.

details$knownmarks = FALSE causes secr.fit to fit a zero-truncated sightings-only model that implicitly estimates the number of marked individuals,rather than inferring it from the number of rows in the capthist object.

details$LLonly = TRUE causes the function to returns a singleevaluation of the log likelihood at the ‘start’ values.

details$maxdistance sets a limit to the centroid-to-mask distances considered. The centroid is the geometric mean of detection locations for each individual. If no limit is specified then summation is over all mask points. Specifyingmaxdistance can speed up computation; it is up to the user to select a limit that is large enough not to affect the likelihood (5\sigma?).

details$miscparm (default NULL) is an optional numeric vector ofstarting values for additional parameters used in a user-supplieddistance function (see ‘userdist’ below). If the vector has a namesattribute then the names will be used for the corresponding coefficients(‘beta’ parameters) which will otherwise be named ‘miscparm1’,miscparm2' etc. These parameters are constant across each model and donot appear in the model formula, but are estimated along with othercoefficients when the likelihood is maximised. Any transformation (linkfunction) etc. is handled by the user in the userdist function. Thecoefficients appear in the output fromcoef.secr andvcov.secr, but notpredict.secr.

details$newdetector specifies a detector type to use for this fit, replacing the previousdetector(traps(capthist)). The value may be a vector (one value per occasion) or for multi-session data, a list of vectors. A scalar value (e.g. "proximity") is otherwise used for all occasions and sessions. The true detector type is usually known and will be specified in the 'traps' attribute;newdetector is useful in simulation studies that examine the effect of misspecification. The capthist component of the output from secr.fit has the new type.

details$nsim specifies the number of replicate simulations to perform to estimate the overdispersion statistics for the sighting counts Tu and Tm. See alsodetails$chat anddetails$chatonly.

details$param chooses between various parameterisations of theSECR model. The defaultdetails$param = 0 is the formulation inBorchers and Efford (2008) and later papers.

details$param = 1 was once used to select the Gardner & Royle parameterisation ofthe detection model (p0,\sigma; Gardner et al. 2009) whenthe detector type is ‘multi’. This parameterisation was discontinued in 2.10.0.

details$param = 2 selects parameterisation in terms of(esa(g_0, \sigma),\sigma) (Efford and Mowat 2014).

details$param = 3 selects parameterisation in terms of(a_0(\lambda_0, \sigma),\sigma) (Efford and Mowat 2014). Thisparameterization is used automatically if a0 appears in the model (e.g.,a0 ~ 1).

details$param = 4 selects parameterisation of sigma in terms ofthe coefficient sigmak and constant c (sigma = sigmak /D^0.5 + c) (Efford et al. 2016). If c is not included explicitly inthe model (e.g., c ~ 1) then it is set to zero. Thisparameterization is used automatically if sigmak appears in the model (e.g.,sigmak ~ 1)

details$param = 5 combines parameterisations (3) and (4) (firstcompute sigma from D, then compute lambda0 from sigma).

details$relativeD indicates that a density model has been fitted conditional onn and hence describing relative density instead of absolute density. The intercept of the submodel for D as a function of covariates is fixed at zero for a log link or 1 for the identity link. Not set by the user in secr >= 5.3.0.

details$savecall determines whether the full call tosecr.fit is saved in the output object. The default is TRUE except when called bylist.secr.fit as names in the call are then evaluated, causing the output to become unwieldy.

details$saveprogress is a non-negative integer indicating the frequencywith which progress is saved to the RDS file named in details$progressfilename (overwritten each time).Logical values FALSE and TRUE correspond to 0 (never) and 1 (after each likelihood evaluation). Less frequent saving is advised, as the operation is slow. If fittingis terminated early it may be resumed from the saved file with functionsecr.refit. The value saved to the RDS file is a list of inputs for 'secr.fit'. The list has attribute 'log' that is a dataframe in which each row is a vector with the iteration number, log likelihood, time, and current values of the coefficients.

details$progressfilename is the name of an RDS file for 'saveprogress' (see previous). Ignored when saveprogress = 0. Default "progress.RDS".

details$splitmarked determines whether the home range centre of marked animals is allowed to move between the marking and sighting phases of a spatial capture–mark–resight study. The default is to assume a common home-range centre (splitmarked = FALSE).

details$telemetrytype determines how telemetry data in theattribute ‘xylist’ are treated. ‘none’ causes the xylist data to beignored. ‘dependent’ uses information on the sampling distribution ofeach home-range centre in the SECR likelihood. ‘concurrent’ does thatand more: it splits capthist according to telemetry status and appendsall-zero histories to the telemetry part for any animals present inxylist. The default is ‘concurrent’.

details$usecov selects the mask covariate to be used fornormalization. NULL limits denominator for normalization todistinguishing habitat from non-habitat.

details$userDfn is a user-provided function for modelling a density surface. Seesecr-densitysurfaces.pdf

details$userdist is either a function to compute non-Euclideandistances between detectors and mask points, or a pre-computed matrix ofsuch distances. The first two arguments of the function should be2-column matrices of x-y coordinates (respectivelyk detectors andm mask points). The third argument is a habitat mask that definesa non-Euclidean habitat geometry (a linear geometry is described indocumentation for the package ‘secrlinear’). The matrixreturned by the function must have exactlyk rows andmcolumns. When called with no arguments the function should return acharacter vector of names for the required covariates of ‘mask’,possibly including the dynamically computed density 'D' and a parameter‘noneuc’ that will be fitted. A slightly expanded account is atuserdist, and full documentation is in the separatedocumentsecr-noneuclidean.pdf.

**Do not use ‘userdist’ for polygon or transect detectors**

References

Efford, M. G., Dawson, D. K., Jhala, Y. V. and Qureshi, Q. (2016) Density-dependent home-range size revealed by spatially explicit capture–recapture.Ecography39, 676–688.

Efford, M. G. and Mowat, G. (2014) Compensatory heterogeneity incapture–recapture data.Ecology95, 1341–1348.

Gardner, B., Royle, J. A. and Wegan, M. T. (2009) Hierarchical modelsfor estimating density from DNA mark-recapture studies.Ecology90, 1106–1115.

Royle, J. A., Chandler, R. B., Sun, C. C. and Fuller, A. K. (2013)Integrating resource selection information with spatialcapture–recapture.Methods in Ecology and Evolution4, 520–530.

See Also

secr.fit,userdist

Examples

## Not run: ## Demo of miscparm and userdist## We fix the usual 'sigma' parameter and estimate the same ## quantity as miscparm[1]. Differences in CI reflect the implied use ## of the identity link for miscparm[1]. mydistfn3 <- function (xy1,xy2, mask) {    if (missing(xy1)) return(character(0))    xy1 <- as.matrix(xy1)    xy2 <- as.matrix(xy2)    miscparm <- attr(mask, 'miscparm')    distmat <- edist(xy1,xy2) / miscparm[1]    distmat}fit0 <- secr.fit (captdata)fit <- secr.fit (captdata, fixed = list(sigma=1), details =     list(miscparm = c(sig = 20), userdist = mydistfn3))    predict(fit0)coef(fit)## End(Not run)

Detection Functions

Description

A detection function relates the probability of detectiong or theexpected number of detections\lambda for an animal to thedistance of a detector from a point usually thought of as its home-rangecentre. Insecr only simple 2- or 3-parameter functions areused. Each type of function is identified by its number or by a 2–3letter code (version\ge 2.6.0; see below). In most cases the namemay also be used (as a quoted string).

Choice of detection function is usually not critical, and the default‘HN’ is usually adequate.

Functions (14)–(19) are parameterised in terms of the expected numberof detections\lambda, or cumulative hazard, rather thanprobability. ‘Exposure’ (e.g. Royle and Gardner 2011) is another termfor cumulative hazard. This parameterisation is natural for the ‘count’detector type or if the function is to be interpreted as adistribution of activity (home range). When one of the functions(14)–(19) is used to describe detection probability (i.e., for the binarydetectors ‘single’, ‘multi’,‘proximity’,‘polygonX’ or‘transectX’), the expected number of detections is internallytransformed to a binomial probability usingg(d) =1-\exp(-\lambda(d)).

The hazard halfnormal (14) is similar to the halfnormal exposure functionused by Royle and Gardner (2011) except they omit the factor of 2 on\sigma^2, which leads to estimates of\sigma that are largerby a factor of sqrt(2). The hazard exponential (16) is identical to theirexponential function.

Functions (1) and (15), the "hazard-rate" detection functions described by Hayes and Buckland(1983), are not recommended for SECR because of their long tail, andcare is also needed with (2) and (16).

Function (3), the compound halfnormal, follows Efford and Dawson (2009).

Function (4) uniform is defined only for simulation as it poses problemsfor likelihood maximisation by gradient methods. Uniform probabilityimplies uniform hazard, so there is no separate function ‘HUN’.

For function (7), ‘F’ is the standard normal distribution function and\mu ands are the mean and standard deviation on thelog scale of a latent variable representing a threshold of detectiondistance. See Note for the relationship to the fitted parameters sigmaand z.

For functions (8) and (18), ‘G’ is the cumulative distribution function of thegamma distribution with shape parameterk ( =z) and scaleparameter\theta ( =sigma/z). See R'spgamma.

For functions (9), (10) and (11), ‘F’ is the standard normaldistribution function andc is an arbitrary signal threshold. The twoparameters of (9) are functions of the parameters of (10) and (11):b_0 = (\beta_0 - c) / sdS andb_1 =\beta_1 / s (see Efford et al. 2009). Note that (9) doesnot require signal-strength data orc.

Function (11) includes an additional ‘hard-wired’ term for soundattenuation due to spherical spreading. Detection probability atdistances less than 1 m is given byg(d) = 1 - F \lbrace(c - \beta_0) / sdS \rbrace

Functions (12) and (13) are undocumented methods for sound attenuation.

Function (19) has been used in some published papers and is included for comparison (see e.g. Ergon and Gardner 2014).

Function (20) defines a detection model based on a bivariate Ornstein-Uhlenbeck movement model (mean-reverting random walk). Like the uniform (4), it is used insecr only for simulation. The three parameters are epsilon (radius of a detector within which detection occurs), sigma (asymptotic bivariate normal scale, as in HHN) and tau (serial correlation parameter\tau = 1/\beta). SeesimOU.

Note

The parameters of function (7) are potentially confusing. The fittedparameters describe a latent threshold variable on the natural scale:sigma (mean) =\exp(\mu + s^2 / 2) and z(standard deviation) =\sqrt{\exp(s^2 + 2\mu)(\exp(s^2)-1)}. As with otherdetection functions, sigma is a spatial scale parameter, although inthis case it corresponds to the mean of the threshold variable; thestandard deviation of the threshold variable (z) determines the shape(roughly 1/max(slope)) of the detection function.

References

Efford, M. G. and Dawson, D. K. (2009) Effect of distance-relatedheterogeneity on population size estimates from point counts.Auk126, 100–111.

Efford, M. G., Dawson, D. K. and Borchers, D. L. (2009) Populationdensity estimated from locations of individuals on a passive detectorarray.Ecology90, 2676–2682.

Ergon, T. and Gardner, B. (2014) Separating mortality and emigration: modelling space use, dispersal and survival with robust-design spatial capture–recapture data.Methods in Ecology and Evolution5, 1327–1336.

Hayes, R. J. and Buckland, S. T. (1983) Radial-distance models for theline-transect method.Biometrics39, 29–42.

Royle, J. A. and Gardner, B. (2011) Hierarchical spatialcapture–recapture models for estimating density from trappingarrays. In: A.F. O'Connell, J.D. Nichols & K.U. Karanth (eds)Camera Traps in Animal Ecology: Methods and Analyses. Springer,Tokyo. Pp. 163–190.

See Also

detectfnplot

Detector Type

Description

Extract or replace the detector type.

Usage

detector(object, ...)detector(object) <- value

Arguments

Details

Valid detector types are ‘single’, ‘multi’, ‘proximity’, ‘count’, ‘capped’,‘signal’, ‘polygon’, ‘transect’, ‘polygonX’, and ‘transectX’. Thedetector type is stored as an attribute of atraps object.Detector types are mostly described by Efford et al. (2009a,b; see alsosecr-overview.pdf). Polygon and transect detector types arefor area and linear searches as described insecr-polygondetectors.pdf and Efford (2011). The ‘signal’detector type is used for acoustic data as described insecr-sound.pdf.

The ‘capped’ detector type refers to binary proximity data in which no more than one individual may be detected at a detector on any occasion. The type is partially implemented insecr 3.1.1: data may be simulated and manipulated, but for model fitting these are treated as proximity data bysecr.fit().

Value

character string for detector type

References

Efford, M. G. (2011) Estimation of population density by spatiallyexplicit capture–recapture with area searches.Ecology92, 2202–2207.

Efford, M. G., Borchers D. L. and Byrom, A. E. (2009a) Density estimationby spatially explicit capture-recapture: likelihood-based methods. In:D. L. Thomson, E. G. Cooch and M. J. Conroy (eds)ModelingDemographic Processes in Marked Populations. Springer, New York. Pp.255–269.

Efford, M. G., Dawson, D. K. and Borchers, D. L. (2009b) Populationdensity estimated from locations of individuals on a passive detectorarray.Ecology90, 2676–2682.

See Also

traps,RShowDoc

Examples

## Default detector type is "multi"temptrap <- make.grid(nx = 6, ny = 8)detector(temptrap) <- "proximity"summary(temptrap)

Deviance of fitted secr model and residual degrees of freedom

Description

Compute the deviance or residual degrees of freedom of a fitted secrmodel, treating multiple sessions and groups as independent. Thelikelihood of the saturated model depends on whether the ‘conditional’or ‘full’ form was used, and on the distribution chosen for the numberof individuals observed (Poisson or binomial).

Usage

## S3 method for class 'secr'deviance(object, ...)## S3 method for class 'secr'df.residual(object, ...)

Arguments

Details

The deviance is-2log(\hat{L}) + 2log(L_{sat}), where\hat{L} is the value of thelog-likelihood evaluated at its maximum, andL_{sat} is thelog-likelihood of the saturated model, calculated thus:

Likelihood conditional onn -

L_{sat} = \log(n!) + \sum\limits _{\omega} [n_\omega \log (\frac{n_\omega}{n}) - \log (n_\omega !)]

Full likelihood, Poissonn -

L_{sat} = n\log(n) - n + \sum\limits _{\omega} [n_\omega \log (\frac{n_\omega}{n}) - \log (n_\omega !)]

Full likelihood, binomialn -

L_{sat} = n\log(\frac{n}{N}) + (N-n)\log(\frac{N-n}{N}) + \log (\frac{N!}{(N-n)!}) + \sum\limits _{\omega} [n_\omega \log (\frac{n_\omega}{n}) - \log (n_\omega !)]

n is the number of individuals observed at least once,n_\omega is the number of distinct histories, andN is the number in a chosen areaA that we estimate by\hat{N} = \hat{D}A.

The residual degrees of freedom is the number of distinct detectionhistories minus the number of parameters estimated. The detectionhistories of two animals are always considered distinct if they belong todifferent groups.

When samples are (very) large the deviance is expected to be distributedas\chi^2 withn_\omega - p degrees offreedom whenp parameters are estimated. In reality, simulation isneeded to assess whether a given value of the deviance indicates asatisfactory fit, or to estimate the overdispersion parameterc.sim.secr is a convenient tool.

Value

The scalar numeric value of the deviance or the residual degress of freedom extractedfrom the fitted model.

References

Borchers, D. L. and Efford, M. G. (2008) Spatially explicit maximumlikelihood methods for capture–recapture studies.Biometrics64, 377–385.

See Also

secr.fit,sim.secr

Examples

deviance(secrdemo.0)df.residual(secrdemo.0)

Rasterize Area Search or Transect Data

Description

It is sometimes useful to re-cast area-search (polygon or polygonX) data as if it was from aset of closely spaced point detectors, i.e. to rasterize the detection locations. This function makes that conversion. Each polygon detector in the input is replaced by a number of point detectors, each representing a square pixel. Detections are mapped to the new detectors on the basis of their x-y coordinates.

Ifobject contains transect data the problem is passed tosnip andreduce.capthist.

Usage

discretize(object, spacing = 5, outputdetector = c("proximity", "count", "multi"),     tol = 0.001, cell.overlap = FALSE, type = c("centre","any", "all"), ...)

Arguments

Details

The input should have detector type ‘polygon’ or ‘polygonX’.

A new array of equally spaced detectors is generated withineach polygon of the input, inflated radially by 1 + tol to avoid someinclusion problems. The origin of the superimposed grid is fixed automatically. Iftype = "centre" detectors are included if they lie within the (inflated) polygon. Otherwise, the decision on whether to include a candidate new detector is based on the corner vertices of the cell around the detector (side =spacing);type = "any" andtype = "all" have the obvious meanings.

tol may be negative, in which case the array(s) will be shrunk relativeto the polygon(s).

For irregular polygons the edge cells in the output may be only partially contained within the polygon they represent. Setcell.overlap = TRUE to retain the proportion of overlap as the ‘usage’ of the new traps object. This can take a few seconds to compute. If ‘usage’ is already defined then the new ‘usage’ is the old multiplied by the proportion of overlap.

Combiningtype = "any" andcell.overlap = TRUE withtol > 0 can have the odd effect of including some marginal detectors that are assigned zero usage.

Withtype = "any", the sum of the overlap proportions times cell area is equal to the area of the polygons.

Value

A capthist or traps object of the requested detector type, but otherwisecarrying forward all attributes of the input. The embedded traps object has a factor covariate ‘polyID’ recording the polygon to which each point detector relates.

Note

Consider the likely number of detectors in the output before you start.

See Also

reduce.capthist,snip

Examples

## Not run: ## generate some polygon datapol <- make.poly()CH <- sim.capthist(pol, popn = list(D = 30), detectfn = 'HHN',    detectpar = list(lambda0 = 0.3))plot(CH, border = 10, gridl = FALSE, varycol = FALSE)## discretize and plotCH1 <- discretize(CH, spacing = 10, output = 'count')plot(CH1, add = TRUE, cappar = list(col = 'orange'), varycol =    FALSE, rad = 0)plot(traps(CH1), add = TRUE)# overlay cell boundariesplot(as.mask(traps(CH1)), dots = FALSE, col = NA, meshcol = 'green',     add = TRUE)## show how detections are snapped to new detectorsnewxy <- traps(CH1)[nearesttrap(xy(CH),traps(CH1)),]segments(xy(CH)[,1], xy(CH)[,2], newxy[,1], newxy[,2])plot(traps(CH), add = TRUE)  # original polygon## Incomplete overlappol <- rotate(make.poly(), 45)CH2 <- sim.capthist(pol, popn = list(D = 30), detectfn = 'HHN',    detectpar = list(lambda0 = 0.3))plot(CH2, border = 10, gridl = FALSE, varycol = FALSE)CH3 <- discretize(CH2, spacing = 10, output = 'count', type = 'any',     cell.overlap = TRUE, tol=0.05)    plot(CH3, add = TRUE, cappar = list(col = 'orange'), varycol =    FALSE, rad = 0)plot(traps(CH3), add = TRUE)# overlay cell boundaries and usagemsk <- as.mask(traps(CH3))covariates(msk) <- data.frame(usage = usage(traps(CH3))[,1])plot(msk, dots = FALSE, cov='usage', meshcol = 'green',     add = TRUE)    ## End(Not run)

Distance To Nearest Detector

Description

Compute Euclidean distance from each of a set of points to the nearestdetector in an array, or return the sequence number of the detectornearest each point.

Usage

distancetotrap(X, traps)nearesttrap(X, traps)

Arguments

Details

distancetotrap returns the distance from each point in X to thenearest detector intraps. It may be used to restrict the pointson a habitat mask.

For traps objects with polygon detector type (polygon, polygonX), and for SpatialPolygons, the function sf::st_distance is used internally(fromsecr 4.5.2).

Value

distancetotrap returns a vector of distances (assumed to be in metres).

nearesttrap returns the index of the nearest trap.

See Also

make.mask

Examples

  ## restrict a habitat mask to points within 70 m of traps    ## this is nearly equivalent to using make.mask with the   ## `trapbuffer' option  temptrap <- make.grid()  tempmask <- make.mask(temptrap)  d <- distancetotrap(tempmask, temptrap)  tempmask <- subset(tempmask, d < 70)

Confidence Ellipses

Description

Plot joint confidence ellipse for two parameters of secr model, or for adistribution of points.

Usage

ellipse.secr(object, par = c("g0", "sigma"), alpha = 0.05,    npts = 100, plot = TRUE, linkscale = TRUE, add = FALSE,    col = palette(), ...)ellipse.bvn(xy, alpha = 0.05, npts = 100, centroid = TRUE, add = FALSE, ...)

Arguments

Details

ellipse.secr calculates coordinates of a confidence ellipse fromthe asymptotic variance-covariance matrix of the beta parameters(coefficients), and optionally plots it.

Iflinkscale == FALSE, the inverse of the appropriate linktransformation is applied to the coordinates of the ellipse, causing itto deform.

Ifobject is a list of secr models then one ellipse isconstructed for each model. Colours are recycled as needed.

ellipse.bvn plots a bivariate normal confidence ellipse for thecentroid of a 2-dimensional distribution of points (default centroid =TRUE), or a Jennrich and Turner (1969) elliptical home-range model.

Value

A list containing the x and y coordinates is returned invisibly fromeither function.

References

Jennrich, R. I. and Turner, F. B. (1969) Measurement ofnon-circular home range.Journal of Theoretical Biology,22, 227–237.

Examples

ellipse.secr(secrdemo.0)

Empirical Variance of H-T Density Estimate

Description

Compute Horvitz-Thompson-like estimate of population density from apreviously fitted spatial detection model, and estimate its samplingvariance using the empirical spatial variance of the number observedin replicate sampling units. Wrapper functions are provided forseveral different scenarios, but all ultimately callderivednj. The functionderived also computesHorvitz-Thompson-like estimates, but it assumes a Poisson or binomialdistribution of total number when computing the sampling variance.

An alternative and probably more general solution is got by combiningchat.nj andadjustVarD.

Usage

derivednj ( nj, esa, se.esa = NULL, method = c("SRS", "R2", "R3", "local",    "poisson", "binomial"), xy = NULL, alpha = 0.05, loginterval = TRUE,     area = NULL, independent.esa = FALSE )derivedMash ( object, sessnum = NULL,  method = c("SRS", "local"),    alpha = 0.05, loginterval = TRUE)derivedCluster ( object, method = c("SRS", "R2", "R3", "local", "poisson", "binomial"),    alpha = 0.05, loginterval = TRUE)derivedSession ( object,  method = c("SRS", "R2", "R3", "local", "poisson", "binomial"),     xy = NULL, alpha = 0.05, loginterval = TRUE, area = NULL, independent.esa = FALSE )derivedExternal ( object, sessnum = NULL, nj, cluster, buffer = 100,    mask = NULL, noccasions = NULL,  method = c("SRS", "local"), xy = NULL,    alpha = 0.05, loginterval = TRUE)

Arguments

Details

derivednj accepts a vector of counts (nj), along with\hat{a} and\widehat{SE}(\hat{a}). Theargumentesa may be a scalar or (if se.esa is NULL) a 2-column matrix with\hat{a_j} and\widehat{SE}(\hat{a_j}) for each replicatej (row). In the special case thatnjis of length 1, ormethod takes the values ‘poisson’ or‘binomial’, the variance is computed using a theoretical variancerather than an empirical estimate. The value ofmethodcorresponds to ‘distribution’ inderived, and defaults to‘poisson’. Formethod = 'binomial' you must specifyarea(see Examples).

Ifindependent.esa is TRUE then independence is assumed among cluster-specific estimates of esa, and esa variances are summed. The default is a weighted sum leading to higher overall variance.

derivedCluster accepts a model fitted to data from clustereddetectors; eachcluster is interpreted as a replicatesample. It is assumed that the sets of individuals sampled bydifferent clusters do not intersect, and that all clusters have thesame geometry (spacing, detector number etc.).

derivedMash accepts a model fitted to clustered data that havebeen ‘mashed’ for fast processing (seemash); eachcluster is a replicate sample: the function uses the vector of clusterfrequencies (n_j) stored as an attribute of the mashedcapthist bymash.

derivedExternal combines detection parameter estimates from afitted model with a vector of frequenciesnj from replicatesampling units configured as incluster. Detectors incluster are assumed to match those in the fitted model withrespect to type and efficiency, but sampling duration(noccasions), spacing etc. may differ. Themask shouldmatchcluster; ifmask is missing, one will beconstructed using thebuffer argument and defaults frommake.mask.

derivedSession accepts a single fitted model that must spanmultiple sessions; each session is interpreted as a replicate sample.

Spatial variance is calculated by one of these methods

The weighted options R2 and R3 substitute\hat{a_j} for line lengthl_k in the corresponding formulae of Fewster et al. (2009, Eq 3,5). Density is estimated byD = n/A whereA = \sum a_j. The variance ofA is estimated as the sum of the cluster-specific variances, assuming independence among clusters. Fewster et al. (2009) found that an alternative estimator for line transects derived by Thompson (2002) performed better when there were strong density gradients correlated with line length (R2 in Fewster et al. 2009, Eq 3).

The neighborhood variance estimator is implemented in packagespsurvey and was originally proposed for generalized random tessellation stratified (GRTS) samples. For ‘local’ varianceestimates, the centre of each replicate must be provided inxy,except where centres may be inferred from the data. It is unclear whether ‘local’ can or should be used when clusters vary in size.

derivedSystematic, now defunct, was an experimental function in earlier versions ofsecr.

Value

Dataframe with one row for each derived parameter (‘esa’, ‘D’) andcolumns as below

Note

The variance of a Horvitz-Thompson-like estimate of density may beestimated as the sum of two components, one due to uncertainty in theestimate of effective sampling area (\hat{a}) and theother due to spatial variance in the total number of animalsnobserved onJ replicate sampling units (n = \sum_{j=1}^{J}{n_j}). We use a delta-method approximationthat assumes independence of the components:

\widehat{\mathrm{var}}(\hat{D}) = \hat{D}^2 \{\frac{\widehat{\mathrm{var}}(n)}{n^2} + \frac{\widehat{\mathrm{var}}(\hat{a})}{\hat{a}^2}\}

where\widehat{\mathrm{var}}(n) = \frac{J}{J-1} \sum_{j=1}^{J}(n_j-n/J)^2. Theestimate of\mathrm{var}(\hat{a}) is model-based whilethat of\mathrm{var}(n) is design-based. This formulation followsthat of Buckland et al. (2001, p. 78) for conventional distancesampling. Given sufficient independent replicates, it is a robust wayto allow for unmodelled spatial overdispersion.

There is a complication in SECR owing to the fact that\hat{a} is a derived quantity (actually an integral)rather than a model parameter. Its sampling variance\mathrm{var}(\hat{a}) is estimated indirectly insecr by combining the asymptotic estimate of the covariancematrix of the fitted detection parameters\theta with anumerical estimate of the gradient ofa(\theta) withrespect to\theta. This calculation is performed inderived.

References

Buckland, S. T., Anderson, D. R., Burnham, K. P., Laake, J. L., Borchers,D. L. and Thomas, L. (2001)Introduction to Distance Sampling:Estimating Abundance of Biological Populations. Oxford UniversityPress, Oxford.

Fewster, R. M. (2011) Variance estimation for systematic designs in spatial surveys.Biometrics67, 1518–1531.

Fewster, R. M., Buckland, S. T., Burnham, K. P., Borchers, D. L., Jupp, P. E., Laake, J. L. and Thomas, L. (2009) Estimating the encounter rate variance in distance sampling.Biometrics65, 225–236.

Stevens, D. L. Jr and Olsen, A. R. (2003) Variance estimation forspatially balanced samples of environmental resources.Environmetrics14, 593–610.

Thompson, S. K. (2002)Sampling. 2nd edition. Wiley, New York.

See Also

derived,esa,chat.nj,adjustVarD

Examples

## The `ovensong' data are pooled from 75 replicate positions of a## 4-microphone array. The array positions are coded as the first 4## digits of each sound identifier. The sound data are initially in the## object `signalCH'. We first impose a 52.5 dB signal threshold as in## Dawson & Efford (2009, J. Appl. Ecol. 46:1201--1209). The vector nj## includes 33 positions at which no ovenbird was heard. The first and## second columns of `temp' hold the estimated effective sampling area## and its standard error.## Not run: signalCH.525 <- subset(signalCH, cutval = 52.5)nonzero.counts <- table(substring(rownames(signalCH.525),1,4))nj <- c(nonzero.counts, rep(0, 75 - length(nonzero.counts)))temp <- derived(ovensong.model.1, se.esa = TRUE)derivednj(nj, temp["esa",1:2])## The result is very close to that reported by Dawson & Efford## from a 2-D Poisson model fitted by maximizing the full likelihood.## If nj vector has length 1, a theoretical variance is used...msk <- ovensong.model.1$maskA <- nrow(msk) * attr(msk, "area")derivednj (sum(nj), temp["esa",1:2], method = "poisson")derivednj (sum(nj), temp["esa",1:2], method = "binomial", area = A)## Set up an array of small (4 x 4) grids,## simulate a Poisson-distributed population,## sample from it, plot, and fit a model.## mash() condenses clusters to a single clustertestregion <- data.frame(x = c(0,2000,2000,0),    y = c(0,0,2000,2000))t4 <- make.grid(nx = 4, ny = 4, spacing = 40)t4.16 <- make.systematic (n = 16, cluster = t4,    region = testregion)popn1 <- sim.popn (D = 5, core = testregion,    buffer = 0)capt1 <- sim.capthist(t4.16, popn = popn1)fit1 <- secr.fit(mash(capt1), CL = TRUE, trace = FALSE)## Visualize samplingtempmask <- make.mask(t4.16, spacing = 10, type =    "clusterbuffer")plot(tempmask)plot(t4.16, add = TRUE)plot(capt1, add = TRUE)## Compare model-based and empirical variances.## Here the answers are similar because the data## were simulated from a Poisson distribution,## as assumed by \code{derived}derived(fit1)derivedMash(fit1)## Now simulate a patchy distribution; note the## larger (and more credible) SE from derivedMash().popn2 <- sim.popn (D = 5, core = testregion, buffer = 0,    model2D = "hills", details = list(hills = c(-2,3)))capt2 <- sim.capthist(t4.16, popn = popn2)fit2 <- secr.fit(mash(capt2), CL = TRUE, trace = FALSE)derived(fit2)derivedMash(fit2)## The detection model we have fitted may be extrapolated to## a more fine-grained systematic sample of points, with## detectors operated on a single occasion at each...## Total effort 400 x 1 = 400 detector-occasions, compared## to 256 x 5 = 1280 detector-occasions for initial survey.t1 <- make.grid(nx = 1, ny = 1)t1.100 <- make.systematic (cluster = t1, spacing = 100,    region = testregion)capt2a <- sim.capthist(t1.100, popn = popn2, noccasions = 1)## one way to get number of animals per pointnj <- attr(mash(capt2a), "n.mash")derivedExternal (fit2, nj = nj, cluster = t1, buffer = 100,    noccasions = 1)## Review plotsbase.plot <- function() {    MASS::eqscplot( testregion, axes = FALSE, xlab = "",        ylab = "", type = "n")    polygon(testregion)}par(mfrow = c(1,3), xpd = TRUE, xaxs = "i", yaxs = "i")base.plot()plot(popn2, add = TRUE, col = "blue")mtext(side=3, line=0.5, "Population", cex=0.8, col="black")base.plot()plot (capt2a, add = TRUE,title = "Extensive survey")base.plot()plot(capt2, add = TRUE, title = "Intensive survey")par(mfrow = c(1,1), xpd = FALSE, xaxs = "r", yaxs = "r")  ## defaults## Weighted variancederivedSession(ovenbird.model.1, method = "R2")## End(Not run)

Mask Buffer Diagnostic Plot

Description

Plot effective sampling area (Borchers and Efford 2008) as a function of increasing buffer width.

esaPlot was previously calledesa.plot.

Usage

esaPlot (object, max.buffer = NULL, spacing = NULL, max.mask = NULL,    detectfn, detectpar, noccasions, binomN = NULL, thin = 0.1,    poly = NULL, poly.habitat = TRUE, session = 1, plt = TRUE,     type = c('density', 'esa', 'meanpdot', 'CVpdot'), n = 1, add = FALSE,     overlay = TRUE, conditional = FALSE, ...)

Arguments

Details

Effective sampling area (esa) is defined as the integral of netcapture probability (p.(\mathbf{X})) over aregion.esaPlot shows the effect of increasing region size onthe value of esa for fixed values of the detection parameters. Themax.buffer ormax.mask arguments establish the maximumextent of the region; points (cells) within this mask are sorted bytheir distanced_k from the nearest detector. esa(buffer) isdefined as the cumulative sum ofcp.(\mathbf{X}) ford_k(\mathbf{X}) <= \mathrm{buffer}, wherecis the area associated with each cell.

The default (type = 'density') is to plot the reciprocal of esamultiplied byn; this is on a more familiar scale (the densityscale) and hence is easier to interpret.

BecauseesaPlot uses the criterion 'distance to nearestdetector',max.mask should be constructed to include allhabitable cells within the desired maximum buffer and no others. Thisis achieved withtype = "trapbuffer" inmake.mask. It isa good idea to set thespacing argument ofmake.maskrather than relying on the default based onnx. Spacing may besmall (e.g. sigma/10) and the buffer ofmax.mask may be quitelarge (e.g. 10 sigma), as computation is fast.

Thinning serves to reduce redundancy in the plotted points, and (ifthe result is saved and printed) to generate more legible numericaloutput. Usethin=1 to include all points.

esaPlot calls the internal functionesaPlotsecr whenobject is a fitted model. In this casedetectfn,detectpar andnoccasions are inferred fromobject.

Value

A dataframe with columns

Ifplt = TRUE the dataframe is returned invisibly.

Note

The response of effective sampling area to buffer width is just onepossible mask diagnostic; it's fast, graphic, and oftensufficient.mask.check performs more intensive checks,usually for a smaller number of buffer widths.

The old argument 'as.density' was superceded by 'type' in 3.1.7.

References

Borchers, D. L. and Efford, M. G. (2008) Spatially explicit maximumlikelihood methods for capture–recapture studies.Biometrics64, 377–385.

See Also

mask,pdot,CVpdot,make.mask,mask.check,Detection functions

Examples

## Not run: ## with previously fitted modelesaPlot(secrdemo.0)## from scratchtrps <- make.grid()msk <- make.mask(trps, buffer = 200, spacing = 5, type = "trapbuffer")detectpar <- list(g0 = 0.2, sigma = 25)esaPlot(trps,,, msk, 0, detectpar, nocc = 10, col = "blue")esaPlot(trps,,, msk, 0, detectpar, nocc = 5, col = "green",    add = TRUE)esaPlot(trps,,, msk, 0, detectpar, nocc = 5, thin = 0.002, plt = FALSE)## End(Not run)

Expected Number of Individuals

Description

Computes the expected number of individuals detected across a detectorlayout or at each cluster of detectors.

Usage

expected.n(object, session = NULL, group = NULL, bycluster    = FALSE, splitmask = FALSE, ncores = NULL)

Arguments

Details

The expected number of individuals detected isE(n) = \int p.(X) D(X) dX where the integration is asummation overobject$mask.p.(X) is the probability anindividual atX will be detected at least once either on thewhole detector layout (bycluster = FALSE) or on the detectorsin a single cluster (seepdot for more onp.).D(X)is the expected density atX, given the model.D(X) isconstant (i.e. density surface flat) ifobject$CL == TRUE orobject$model$D == ~1, and for some other possible models.

If thebycluster option is selected and detectors are not, infact, assigned to clusters then each detector will be treated as acluster, with a warning.

Settingncores = NULL uses the existing value from the environment variable RCPP_PARALLEL_NUM_THREADS (seesetNumThreads).

By default, a full habitat mask is used for each cluster. This is themore robust option. Alternatively, the mask may be split into subregionsdefined by the cells closest to each cluster.

The calculation takes account of any fitted continuous model for spatialvariation in density (note Warning).

Value

The expected count (bycluster = FALSE) or a vector of expected counts,one per cluster. For multi-session data, a list of such vectors.

Warning

This function changed slightly between 2.1.0 and 2.1.1, and nowperforms as indicated here when bycluster = TRUE andclusters are not specified.

Clusters of detectors are assumed to be independent (always true with detector types‘proximity’, ‘count’ etc.). The computed E(n) does not apply whenthere is competition among clusters of detectors.

The prediction of density at present considers only the base level ofdensity covariates, such as cell-specific habitat variables.

See Also

region.N

Examples

## Not run: expected.n(secrdemo.0)expected.n(secrdemo.0, bycluster = TRUE)expected.n(ovenbird.model.D)## Clustered designmini <- make.grid(nx = 3, ny = 3, spacing = 50, detector =    "proximity")tempgrids <- trap.builder (cluster = mini , method = "all",    frame = expand.grid(x = seq(1000, 9000, 2000),    y = seq(1000, 9000, 2000)), plt = TRUE)capt <- sim.capthist(tempgrids, popn = list(D = 2))tempmask <- make.mask(tempgrids, buffer = 100,    type = "clusterbuffer")fit <- secr.fit(capt, mask = tempmask, trace = FALSE)En <- expected.n(fit, bycluster = TRUE)## GoF or overdispersion statisticp <- length(fit$fit$par)y <- cluster.counts(capt)## scaled by n-psum((y - En)^2 / En) / (length(En)-p)sum((y - En)^2 / En) / sum(y/En)## End(Not run)

Simulated Movements

Description

Extract movements from a previously simulated multi-session population.

Usage

extractMoves(pop, plotn = NULL, add = FALSE, collapse = TRUE, maxradius = Inf, ...)

Arguments

Details

This function is mostly used to check the movement simulations.

Moves are constrained by the edge (argument ‘edgemethod’ ofsim.popn). ‘maxradius’ may be set to restrict the extraction to the subset of animals initially near the centroid of the arena in each session.

Plotting uses the graphics functionarrows that has some quirks, such as difficult-to-suppress warnings for zero-length moves. Setcode = 0 to suppress arrowheads;length = 0.1 to shorten to 0.1 inches, etc.

Value

List of data frames, one for each session but the last (columns ‘x1’,‘y1’,‘x2’,‘y2’,‘d’).

See Also

turnover,sim.popn

Examples

set.seed(12345)pop3 <- sim.popn(D = 2, core = make.grid(), buffer = 200, nsessions = 3,     details = list(lambda = 1.0, movemodel = 'BVE', move.a = 50,     edgemethod = 'stop'))m <- extractMoves(pop3, plotn = 10, length = 0.1)mean(unlist(sapply(m, '[', 'd')))    # less than nominal 2 x move.a# For distances closer to nominal for BVE (2 x move.a = 100), # increase size of arena (e.g., buffer = 500) and consider only # central animals (e.g., maxradius = 300).

Activity Centres of Detected and Undetected Animals

Description

The summed probability densities of both observed andunobserved individuals are computed for a fitted model and dataset.

Functionfx.total was replaced by methodfxTotal insecr 5.0.0.

Usage

## S3 method for class 'secr'fxTotal(object, sessnum = 1, mask = NULL, ncores = NULL, ...)

Arguments

Details

This function callsfxi for each detected animal andoverlays the results to obtain a summed probability density surface D.fxfor the locations of the home-range centres of detected individuals.

A separate calculation usingpdot provides the expectedspatial distribution of undetected animals, as another densitysurface: crudely, D.nc(X) = D(X) * ( 1 – pdot(X)).

The pointwise sum of the two surfaces is sometimes used to represent thespatial distrbution of the population, but see Notes.

Settingncores = NULL uses the existing value from the environment variable RCPP_PARALLEL_NUM_THREADS (seesetNumThreads).

Value

An object of class ‘Dsurface’ (a variety of mask) with a ‘covariates’attribute that is a dataframe with columns –

All densities are in animals per hectare (the ‘scale’ argument ofplot.Dsurface allows the units to be varied later).

Note

The surface D.sum represents what is known from the data about aspecific realisation of the spatial point process for home rangecentres: varying the intensity of sampling will change its shape. It isnot an unbiased estimate of a biologically meaningful densitysurface. The surface will always tend to lack relief towards the edge ofa habitat mask where the main or only contribution is from D.nc.

References

Borchers, D. L. and Efford, M. G. (2008) Spatially explicit maximumlikelihood methods for capture–recapture studies.Biometrics64, 377–385.

See Also

fxi,fxiContour,pdot

Examples

## Not run: tmp <- fxTotal(secrdemo.0)## to plot we must name one of the covariates:## the Dsurface default 'D.0' causes an error plot(tmp, covariate = 'D.sum', col = terrain.colors(16),   plottype = 'shaded')plot(tmp, covariate = 'D.sum', col = 'white', add = TRUE,   plottype = 'contour')if (interactive()) {    spotHeight(tmp, prefix = 'D.sum')}fxsurface <- fxTotal(ovenbird.model.D, sessnum = 3)plot(fxsurface, covariate = 'D.sum')## End(Not run)

Probability Density of Activity Centre

Description

Display contours of the probability density function for the estimatedlocation of one or more activity centres (AC), compute values forparticular points X, or compute mode of pdf. The pdf is given byf(X_j|\omega_i) = \mathrm{Pr}(\omega_i|X_j)\pi(X_j), where\pi(X) is the probability densityof range centres across the mask (Borchers and Efford 2008).

These functions were previously namedfxi.secr,fxi.contour andfxi.mode.

Usage

## S3 method for class 'secr'fxi(object, i = NULL, sessnum = 1, X = NULL, ncores = NULL, ...)fxiContour (object, i = 1, sessnum = 1, border = 100, nx = 64,    levels = NULL, p = seq(0.1,0.9,0.1), plt = TRUE, add = FALSE,    fitmode = FALSE, plotmode = FALSE, fill = NULL,    output = c('list','sf','SPDF'), ncores = NULL, ...)fxiMode(object, i = 1, sessnum = 1, start = NULL, ncores = NULL, ...)

Arguments

Details

fxiContour computes contours of AC probability density for oneor more detection histories. Increasenx for smoothercontours. Iflevels is not set, contour levels are setto approximate the confidence levels inp.

fxi computes the AC probability density for one or moredetection histories;X may contain coordinates for one orseveral points; a dataframe or vector (x then y) will be coerced to amatrix.

fxiMode attempts to find the x- and y-coordinatescorresponding to the maximum of the AC pdf for a single detection history(i.e.i is of length 1).fxiMode callsnlm.

fxiContour withfitmode = TRUE callsfxiModefor each individual. Otherwise, the reported mode is an approximation(mean of coordinates of highest contour).

Ifi is character it will be matched to row names ofobject$capthist (restricted to the relevant session in the case of amulti-session fit); otherwise it will be interpreted as a row number.

Values of the pdf are normalised by dividing by theintegral of\mathrm{Pr}(\omega_i|X)\pi(X)over the habitat mask inobject. (In secr >= 4.0 may differ from previous versions).

Settingncores = NULL uses the existing value from the environment variable RCPP_PARALLEL_NUM_THREADS (seesetNumThreads).

Ifstart is not provided tofit.mode then (from 2.9.4) the weighted mean of all detector sites is used (see Warning below).

The ... argument gives additional control over a contour plot; forexample, setdrawlabels = FALSE to suppress contour labels.

Value

fxi –

Vector of probability densities

fxiContour (output = 'list') –

Coordinates of the plotted contours are returned as a list with onecomponent per polygon. The list is returned invisibly if plt = TRUE.

An additional component ‘mode’ reports the x-y coordinates of thehighest point of each pdf (see Details).

fxiContour (output = 'SPDF') –

Contours are returned as a SpatialPolygonsDataFrame (see packagesp) with one component per animal. The attributes dataframe has two columns, the x-and y-coordinates of the mode. The SpatialPolygonsDataFrame is returnedinvisibly if plt = TRUE.

fxiContour (output = 'sf') – simple features 'sf' object, as for SPDF.

fxiMode –

List with components ‘x’ and ‘y’

Warnings

fxiMode may fail to find the true mode unless a good startingpoint is provided. Note that the distribution may have multiple modes and only one is reported. The default value ofstart beforesecr 2.9.4 was the first detected location of the animal.

Note

Fromsecr 2.8.3, these functions work with both homogeneousand inhomogeneous Poisson density models, andfxi acceptsvector-valuedi.

SeefxTotal for a surface summed across individuals.

References

Borchers, D. L. and Efford, M. G. (2008) Spatially explicit maximumlikelihood methods for capture–recapture studies.Biometrics64, 377–385.

See Also

pdotContour,contour,fxTotal

Examples

## Not run: fxi(secrdemo.0, i = 1, X = c(365,605))## contour first 5 detection historiesplot(secrdemo.0$capthist)fxiContour (secrdemo.0, i = 1:5, add = TRUE,    plotmode = TRUE, drawlabels = FALSE)## extract modes only## these are more reliable than those from fit.mode called directly as## they use a contour-based approximation for the starting pointfxiout <- fxiContour (secrdemo.0, i = 1:5, plt = FALSE, fitmode = TRUE)t(sapply(fxiout, "[[", "mode"))## using fill colours## lty = 0 suppresses contour lines## nx = 256 ensures smooth outlineplot(traps(captdata))fxiContour(secrdemo.0, i = 1:5, add = TRUE, p = c(0.5,0.95), drawlabels    = FALSE, nx = 256, fill = topo.colors(4), lty = 0)## output as simple featuressf <- fxiContour(secrdemo.0, i = 1:3, plt = FALSE, p = c(0.5,0.95),    nx = 256, output = 'sf', fitmode = TRUE)## save as ESRI shapefile testsf.shp etc.library(sf)st_write(sf, 'testsf.shp')## plot contours and modesplot(st_as_sfc(sf))    # outline onlypoints(sf$modex, sf$modey)## output as SpatialPolygonsDataFramespdf <- fxiContour(secrdemo.0, i = 1:3, plt = FALSE, p = c(0.5,0.95),    nx = 256, output = 'SPDF', fitmode = TRUE)sp::plot(spdf)points(data.frame(spdf))## End(Not run)

Construct Grid Cells

Description

Forms grid cells centred on input points.

Usage

gridCells(x, cellsize = spacing(x), crs = NA)

Arguments

Details

The argument x will often be a traps or mask object with spacing attribute. Otherwisecellsize must be provided.

Seemake.grid for jittered locations within grid cells.

Value

A simple features (sf) object of class ‘sfc_MULTIPOLYGON’.

crs may be the integer EPSG code (e.g. 3578 Yukon Albers).

See Also

plotMaskEdge,spacing

Examples

plot(gridCells(traps(captdata)))plot(traps(captdata), add = TRUE)

Hybrid Mixture Model

Description

The argumenthcov insecr.fit is used to fit a hybridmixture model. ‘Hybrid’ refers to a flexible combination of latentclasses (as in a finite mixture) and known classes (cf groups orsessions). A hybrid mixture model includes a parameter ‘pmix’ for themixing proportion and optionally allows detection parameters to bemodelled as class-specific ( ~ h2). This is particularly useful formodelling sex ratio and sex differences in detection, and matches theBayesian sex-specific model of Gardner et al. (2010).

For observed animals all of unknown class the model is identical to afinite mixture (i.e. latent-class) model. For observed animals all ofknown class, the classes are no longer ‘latent’ and the model isequivalent to a grouped model with an additional binomial factor forclass membership.

Assumptions

hcov identifies a single individual covariate (the classcovariate) that should be a factor with two levels, or containcharacter values that will be coerced to a factor (e.g., ‘f’,‘m’). Missing values (NA) are used for individuals of unknownclass. Ifhcov has more than two levels, all but the first twolevels are converted to NA (but see exception for h3 models below).

It is assumed that the probability of recording a missing value forthe class covariate is independent of the true class membership (e.g.,sex equally likely to be recorded for males and females).

Operational details

A hybrid mixture model is fitted wheneverhcov is notNULL. Mixture models include a parameter ‘pmix’, the mixingproportion. If the covariate identified byhcov is missing (''or NA) for all individualsand a mixture term (h2 or h3)appears in the detection model (e.g., g0 ~ h2) then a conventionalfinite mixture model is fitted (cf Pledger 2000, Borchers & Efford2008).

As with finite mixture models, any detection parameter (g0, sigmaetc.) may be modelled as depending on mixture class by modelspecifications such as (g0 ~ h2, sigma ~ h2). See Examples.

In generalhcov has been designed for two classes and twoclasses are assumed if neither ‘h2’ nor ‘h3’ appears in the modelformulae. However, there is a small exception:hcov may havethree non-missing levels if ‘h3’ appears in a model formula. Notethat h2 cannot be combined with h3; h3 is for advanced use only andhas not been fully tested.

The number of fitted parameters is the same as the correspondingfinite mixture model if mixture terms (‘h2’, ‘h3’) appear in the modelformulae. Otherwise (no mixture terms) estimating pmix requires asingle extra parameter. The estimate of pmix then depends solely onthe observed class proportions in the covariate, and the betavariance-covariance matrix will show zero covariance of pmix withother detection parameters.

Models for pmix

Variation in the parameter pmix may be modelled across sessions i.e.,models such as pmix ~ session or pmix ~ Session are valid, as areformulae involving session covariates defined in the sessioncovargument of secr.fit.

If no mixture term appears in the formula for pmix then one is addedautomatically (usually ‘h2’). This serves mostly to keep track ofvalues in the output.

Attempting to model pmix as a function of individual covariates orother within-session terms (t, b etc.) will cause an error.

Interpreting output

When you display a fitted secr model the parameter estimates are in afinal section headed 'Fitted (real) parameters evaluated at baselevels of covariates'. The same output may be obtained by calling thepredict method directly. Callingpredict has the advantagethat you can obtain estimates for levels of the covariates other thanthe base levels, by specifyingnewdata. An example below showshow to specify h2 innewdata. [Note:predictis generic, and you must consult ?predict.secr to see the help for thespecific implementation of this method for fitted secr objects].

The output frompredict.secr for a mixture model is a list withone component for each (possibly latent) class. Each row correspondsto a fitted real parameter: ordinarily these include the detectionparameters (e.g., g0, sigma) and the mixing proportion (pmix).

In the case of a model fitted by maximizing the full likelihood(CL = FALSE), density D will also appear in the output. Notethat only one parameter for density is estimated, the total densityacross classes. This total density figure appears twice in theoutput, once for each class.

The standard error (SE.estimate) is shown for each parameter. Theseare asymptotic estimates back-transformed from the link scale. Theconfidence limits are also back-transformed from the link scale (95%CI by default; varyalpha inpredict.secr if you wante.g. 90% CI).

The mixing proportion pmix depends on the composition of the samplewith respect tohcov and the detection model. For a nulldetection model the mixing proportion is exactly the proportion in thesample, with appropriate binomial confidence limits. Otherwise, themixing proportion adjusts for class differences in the probability andscale of detection (see Examples).

The preceding refers to the default behaviour when pmix ~ h2. It ispossible also to fix the mixing proportion at any arbitrary value(e.g., fixed = list(pmix = 0.5) for 1:1 sex ratio).

On output the classes are tagged with the factor levels ofhcov,regardless of how few or how many individuals were actually of knownclass. If only a small fraction were of known class, and there iscryptic variation unrelated tohcov, then the associationbetween the fitted classes and the nominal classes (i.e. levels ofhcov) may be weak, and should not be trusted.

Limitations

Hybrid mixture models are incompatible with groups as presentlyimplemented.

The hcov likelihood conditions on the number of known-classindividuals. A model fitted withhcov = NULL or with adifferent hcov covariate has in effect a different data set, andlikelihoods, deviances or AICs cannot be compared. AIC can be used tocompare models provided they all have the same hcov covariate in thecall tosecr.fit, whether or not h2 appears in the modeldefinition.

Likelihood

The likelihood of the hybrid mixture model is detailed in an appendix ofthe vignettesecr-finitemixtures.pdf.

References

Borchers, D.L. and Efford, M.G. (2008) Spatially explicit maximumlikelihood methods for capture–recapture studies.Biometrics64,377–385.

Gardner, B., Royle, J.A., Wegan, M.T., Rainbolt, R. and Curtis,P. (2010) Estimating black bear density using DNA data from hairsnares.Journal of Wildlife Management74, 318–325.

Pledger, S. (2000) Unified maximum likelihood estimates forclosed capture–recapture models using mixtures.Biometrics56,434–442.

See Also

secr.fit

Examples

## Not run: ## house mouse dataset, morning trap clearances## 81 female, 78 male, 1 unknownmorning <- subset(housemouse, occ = c(1,3,5,7,9))summary(covariates(morning))## speedy model fitting with coarse maskmmask <- make.mask(traps(morning), buffer = 20, nx = 32)## assuming equal detection of males and females## fitted sex ratio p(female) = 0.509434 = 81 / (81 + 78)fit.0 <- secr.fit(morning, hcov = "sex", mask = mmask, trace = FALSE)predict(fit.0)## allowing sex-specific detection parameters## this leads to new estimate of sex ratio fit.h2 <- secr.fit(morning, hcov = "sex", mask = mmask, trace = FALSE,    model = list(g0 ~ h2, sigma ~ h2))predict(fit.h2)## specifying newdata for h2 - equivalent to predict(fit.h2)predict(fit.h2, newdata = data.frame(h2 = factor(c('f','m'))))## conditional likelihood fit of preceding model## estimate of sex ratio does not change fit.CL.h2 <- secr.fit(morning, hcov = "sex", mask = mmask, trace = FALSE,    CL = TRUE, model = list(g0 ~ h2, sigma ~ h2))predict(fit.CL.h2)## did sexes differ in detection parameters?fit.CL.0 <- secr.fit(morning, hcov = "sex", mask = mmask, trace = FALSE,    CL = TRUE, model = list(g0 ~ 1, sigma ~ 1))LR.test(fit.CL.h2, fit.CL.0)## did sex ratio deviate from 1:1?fit.CL.h2.50 <- secr.fit(morning, hcov = "sex", mask = mmask, trace = FALSE,    CL = TRUE, model = list(g0 ~ h2, sigma ~ h2), fixed = list(pmix = 0.5))LR.test(fit.CL.h2, fit.CL.h2.50)## did sexes show extra-compensatory variation in lambda0?## (Efford and Mowat 2014)fit.CL.a0 <- secr.fit(morning, hcov = "sex", mask = mmask, trace = FALSE,    CL = TRUE, model = list(a0 ~ 1, sigma ~ h2))LR.test(fit.CL.h2, fit.CL.a0)## trend in ovenbird sex ratio, assuming sex-specific detectionomask <- make.mask(traps(ovenCH), buffer = 300, nx = 32)fit.sextrend <- secr.fit(ovenCH, model = list(g0~h2, sigma~h2, pmix~Session),    hcov = "Sex", CL = TRUE, mask = omask, trace = FALSE)predict(fit.sextrend)[1:5]## End(Not run)

First or Last Part of an Object

Description

Returns the first or last parts of secr objects

Usage

## S3 method for class 'mask'head(x, n=6L, ...)## S3 method for class 'Dsurface'head(x, n=6L, ...)## S3 method for class 'traps'head(x, n=6L, ...)## S3 method for class 'capthist'head(x, n=6L, ...)## S3 method for class 'mask'tail(x, n=6L, ...)## S3 method for class 'Dsurface'tail(x, n=6L, ...)## S3 method for class 'traps'tail(x, n=6L, ...)## S3 method for class 'capthist'tail(x, n=6L, ...)

Arguments

Details

These custom S3 methods retain the class of the target object, unlike thedefault methods applied to ‘mask’, ‘Dsurface’, ‘traps’ or ‘capthist’ objects.

Value

An object of the same class as x, but (usually) fewer rows.

See Also

head,tail

Examples

head(possummask)

Home Range Statistics

Description

Some ad hoc measures of home range size may be calculated insecrfrom capture–recapture data:

dbar is the mean distance between consecutive capture locations,pooled over individuals (e.g. Efford 2004).moves returns theraw distances.

MMDM (for ‘Mean Maximum Distance Moved’) is the average maximumdistance between detections of each individual i.e. the observed rangelength averaged over individuals (Otis et al. 1978).

ARL (or ‘Asymptotic Range Length’) is obtained by fitting anexponential curve to the scatter of observed individual range length vsthe number of detections of each individual (Jett and Nichols 1987: 889).

RPSV (for ‘Root Pooled Spatial Variance’) is a measure of the 2-Ddispersion of the locations at which individual animals are detected,pooled over individuals (cf Calhoun and Casby 1958, Slade and Swihart 1983).

moves reports the distance between successive detections of each animal.

centroids reports the averaged coordinates of each animal's detections

ORL reports the observed range length of each animal, the maximum distance between any two detections.

t2r2 computes Schoener's measure of serial correlation (Swihart and Slade 1985, 1987). The expected value of t2r2 for independent detections is about 2.0.

trapsPerAnimal tabulates the number of animals recorded at 1, 2, ..., K detectors

Usage

dbar(capthist, userdist = NULL, mask = NULL)MMDM(capthist, min.recapt = 1, full = FALSE, userdist = NULL, mask = NULL)ARL(capthist, min.recapt = 1, plt = FALSE, full = FALSE, userdist = NULL, mask = NULL)moves(capthist, userdist = NULL, mask = NULL, names = FALSE)RPSV(capthist, CC = FALSE)ORL(capthist, userdist = NULL, mask = NULL)t2r2(capthist)centroids(capthist)trapsPerAnimal(capthist)

Arguments

Details

dbar is defined as –

\overline{d}=\frac{\sum\limits _{i=1}^{n} \sum\limits _{j=1}^{n_i - 1} \sqrt{(x_{i,j}-x_{i,j+1})^2 + (y_{i,j}-y_{i,j+1})^2}} {\sum\limits _{i=1}^{n} (n_i-1)}

WhenCC = FALSE,RPSV is defined as –

RPSV = \sqrt{ \frac {\sum\limits _{i=1}^{n} \sum\limits _{j=1}^{n_i} [ (x_{i,j} - \overline x_i)^2 + (y_{i,j} - \overline y_i)^2]}{\sum\limits _{i=1}^{n} (n_i-1) - 1}}

.

Otherwise (CC = TRUE),RPSV uses the formula of Calhounand Casby (1958) with a different denominator –

s = \sqrt{ \frac {\sum\limits _{i=1}^{n} \sum\limits _{j=1}^{n_i} [ (x_{i,j} - \overline x_i)^2 + (y_{i,j} - \overline y_i)^2]}{2\sum\limits _{i=1}^{n} (n_i-1)}}

.

The Calhoun and Casby formula (offered from 2.9.1) correctly estimates\sigmawhen trapping is on an infinite, fine grid, and is preferredfor this reason. The original RPSV(CC = FALSE) is retained as the default for compatibility withprevious versions ofsecr.

RPSV has a specific role as a proxy fordetection scale in inverse-prediction estimation of density (Efford2004, 2023).

RPSV is used inautoini to obtain plausible startingvalues for maximum likelihood estimation.

MMDM andARL discard data from detection historiescontaining fewer thanmin.recapt+1 detections.

Schoener's measure (t2r2) is defined ast^2/r^2 where

t^2 = \frac {\sum\limits _{i=1}^{n} \sum\limits _{j=1}^{n_i - 1} [ (x_{i,j} - x_{i,j+1})^2 + (y_{i,j} - y_{i,j+1})^2]}{\sum\limits _{i=1}^{n} (n_i-1)} ,\;\; r^2 = \frac {\sum\limits _{i=1}^{n} \sum\limits _{j=1}^{n_i} [ (x_{i,j} - \overline x_i)^2 + (y_{i,j} - \overline y_i)^2]}{\sum\limits _{i=1}^{n} (n_i-1)},

where(\bar x_i, \bar y_i) is the arithmetic mean location of individuali.

Theuserdist option is included for exotic non-Euclidean cases(see e.g.secr.fitdetails). RPSV is not defined fornon-Euclidean distances.

Ifcapthist comprises standalone telemetry data (all detector 'telemetry') then calculations are performed on the telemetry coordinates. Ifcapthist combines telemetry data and conventional detections (‘multi’, ‘proximity’ etc.) then only the conventional data are summarised.

Movements are reliably reported bymoves only if there is a maximum of one detection per animal per occasion. The sequence of detections within any occasion is not known; where these occur the sequence used bymoves is arbitrary (sequence follows detector index).

Value

Fordbar,MMDM,ARL andRPSV –

Scalar distance in metres, or a list of such values ifcapthistis a multi-session list.

Thefull argument may be used withMMDM andARL toreturn more extensive output, particularly the observed range length foreach detection history.

Formoves –

List with one component for each animal, a vector of distances, or numeric(0) if the animal is detected only once. A list of such lists ifcapthist is a multi-session list.

Forcentroids –

For a single-session capthist, a matrix of two columns, the x- and y-coordinates of the centroid of the detections of each animal. The number of detections is returned as the attribute ‘Ndetections’, a 1-column matrix.

For a multi-session capthist, a 3-D array as before, but with a third dimension for the session. Centroid coordinates are missing (NA) if the animal was not detected in a session. The attribute ‘Ndetections’ with the number of detections per animal and session is a matrix.

FortrapsPerAnimal –

A vector with the number of animals detected at k detectors.

Note

All measures are affected by the arrangement of detectors.dbaris also affected quite strongly by serial correlation in the sampledlocations. Usingdbar with ‘proximity’ detectors raises a problemof interpretation, as the original sequence of multiple detectionswithin an occasion is unknown. RPSV is a value analogous to the standarddeviation of locations about the home range centre.

The value returned bydbar for ‘proximity’ or ‘count’ detectorsis of little use because multiple detections of an individual within anoccasion are in arbitrary order.

Inclusion of these measures in thesecr package does not mean they arerecommended for general use! It is usually better to use a spatialparameter from a fitted model (e.g.,\sigma of thehalf-normal detection function). Even then, be careful that\sigma is not ‘contaminated’ with behavioural effects (e.g.attraction of animal to detector) or ‘detection at a distance’.

The argument 'names' was added in 3.0.1. The defaultnames = FALSE causes a change in behaviour from that version onwards.

References

Calhoun, J. B. and Casby, J. U. (1958) Calculation of home range anddensity of small mammals. Public HealthMonograph. No. 55. U.S. Government Printing Office.

Efford, M. G. (2004) Density estimation in live-trapping studies.Oikos106, 598–610.

Efford, M. G. (2023) ipsecr: An R package for awkward spatial capture–recapture data.Methods in Ecology and Evolution In press.

Jett, D. A. and Nichols, J. D. (1987) A field comparison of nested gridand trapping web density estimators.Journal of Mammalogy68, 888–892.

Otis, D. L., Burnham, K. P., White, G. C. and Anderson, D. R. (1978)Statistical inference from capture data on closed animalpopulations.Wildlife Monographs62, 1–135.

Slade, N. A. and Swihart, R. K. (1983) Home range indices for the hispidcotton rat (Sigmodon hispidus) in Northeastern Kansas.Journal ofMammalogy64, 580–590.

Swihart, R. K. and Slade, N. A. (1985) Testing for independence of observations in animal movements.Ecology66, 1176–1184.

Swihart, R. K. and Slade, N. A. (1987) A test for independence of movements as shown by live trapping.American Midland Naturalist117, 204–207.

See Also

autoini

Examples

dbar(captdata)RPSV(captdata)RPSV(captdata, CC = TRUE)centr <- centroids(captdata)plot(traps(captdata), border = 20 )text(centr[,1], centr[,2], attr(centr, 'Ndetections'))text(centr[,1]+2, centr[,2]+3, rownames(captdata), cex = 0.6,    adj = 0)

Flat-tailed Horned Lizard Dataset

Description

Data from multiple searches for flat-tailed horned lizards(Phrynosoma mcalli) on a plot in Arizona, USA.

Usage

hornedlizardCH

Details

The flat-tailed horned lizard (Phrynosoma mcalli) is a desertlizard found in parts of southwestern Arizona, southeastern Californiaand northern Mexico. There is considerable concern about itsconservation status. The species is cryptically coloured and has thehabit of burying under the sand when approached, making it difficult orimpossible to obtain a complete count (Grant and Doherty 2007).

K. V. Young conducted a capture–recapture survey of flat-tailed hornedlizards 25 km south of Yuma, Arizona, in the Sonoran Desert. The habitatwas loose sand dominated by creosote bush and occasional bur-sage andGalletta grass. A 9-ha plot was surveyed 14 times over 17 days (14 Juneto 1 July 2005). On each occasion the entire 300 m x 300 m plot wassearched for lizards. Locations within the plot were recorded byhandheld GPS. Lizards were captured by hand and marked individually ontheir underside with a permanent marker. Marks are lost when the lizardsheds, but this happens infrequently and probably caused few or noidentification errors during the 2.5-week study.

A total of 68 individuals were captured 134 times. Exactly half of theindividuals were recaptured at least once.

Royle and Young (2008) analysed the present dataset to demonstrate amethod for density estimation using data augmentation and MCMCsimulation. They noted that the plot size was much larger than has beensuggested as being practical in operational monitoring efforts for thisspecies, that the plot was chosen specifically because a high density ofindividuals was present, and that high densities typically correspond toless movement in this species. The state space in their analysis was asquare comprising the searched area and a 100-m buffer (J. A. Roylepers. comm.).

The detector type for these data is ‘polygonX’ and there is a singledetector (the square plot). The data comprise a capture history matrix(the body ofhornedlizardCH) and the x-y coordinates of eachpositive detection (stored as an attribute that may be displayed withthe ‘xy’ function); the ‘traps’ attribute ofhornedlizardCHcontains the vertices of the plot. Seesecr-datainput.pdf for guidance ondata input.

Non-zero entries in a polygonX capture-history matrix indicate thenumber of the polygon containing the detection. In this case there wasjust one polygon, so entries are 0 or 1. No animal can appear more thanonce per occasion with the polygonX detector type, so there is no needto specify ‘binomN = 1’ in secr.fit.

Source

Royle and Young (2008) and J. A. Royle (pers. comm.), with additionalinformation from K. V. Young (pers. comm.).

References

Efford, M. G. (2011) Estimation of population density by spatiallyexplicit capture–recapture analysis of data from areasearches.Ecology92, 2202–2207.

Grant, T. J. and Doherty, P. F. (2007) Monitoring of the flat-tailedhorned lizard with methods incorporating detectionprobability.Journal of Wildlife Management71, 1050–1056

Marques, T. A., Thomas, L. and Royle, J. A. (2011) A hierarchical modelfor spatial capture–recapture data: Comment.Ecology92,526–528.

Royle, J. A. and Young, K. V. (2008) A hierarchical model for spatialcapture–recapture data.Ecology89, 2281–2289.

See Also

capthist,detector,reduce.capthist

Examples

plot(hornedlizardCH, tracks = TRUE, varycol = FALSE,    lab1 = TRUE, laboff = 6, border = 10, title =    "Flat-tailed Horned Lizards (Royle & Young 2008)")table(table(animalID(hornedlizardCH)))traps(hornedlizardCH)## show first few x-y coordinateshead(xy(hornedlizardCH))## Not run: ## Compare default (Poisson) and binomial models for number## caughtFTHL.fit <- secr.fit(hornedlizardCH)FTHLbn.fit <- secr.fit(hornedlizardCH, details =    list(distribution = "binomial"))collate(FTHL.fit, FTHLbn.fit)[,,,"D"]## Collapse occasions (does not run faster)hornedlizardCH.14 <- reduce(hornedlizardCH, newoccasions =    list(1:14), outputdetector = "polygon")FTHL14.fit <- secr.fit(hornedlizardCH.14, binomN = 14)## End(Not run)

House mouse live trapping data

Description

Data of H. N. Coulombe from live trapping of feral house mice (Musmusculus) in a salt marsh, California, USA.

Usage

housemouse

Details

H. N. Coulombe conducted a live-trapping study on an outbreak of feral housemice in a salt marsh in mid-December 1962 at Ballana Creek, Los AngelesCounty, California. A square 10 x 10 grid was used with 100 Shermantraps spaced 3 m apart. Trapping was done twice daily, morning andevening, for 5 days.

The dataset was described by Otis et al. (1978) and distributed withtheir CAPTURE software. Otis et al. (1978 p. 62, 68) cited Coulombe's unpublished 1965 master's thesis from the University of California, Los Angeles, California.

The data are provided as a single-sessioncapthist object. Thereare two individual covariates: sex (factor levels ‘f’, ‘m’) and ageclass (factor levels ‘j’, ‘sa’, ‘a’). The sex of two animals is notavailable (NA); it is necessary to drop these records for analysesusing ‘sex’ unless missing values are specifically allowed, as inhcov.

The datasets were originally in the CAPTURE ‘xy complete’ format whichfor each detection gives the ‘column’ and ‘row’ numbers of the trap(e.g. ‘ 9 5’ for a capture in the trap at position (x=9, y=5) on thegrid). Trap identifiers have been recoded as strings with no spaces byinserting zeros (e.g. ‘0905’ in this example).

Sherman traps are designed to capture one animal at a time, but the datainclude 30 double captures and one occasion when there were 4individuals in a trap at one time. The true detector type thereforefalls between ‘single’ and ‘multi’. Detector type is set to ‘multi’ inthe distributed data objects.

Otis et al. (1978) report various analyses including a closure test onthe full data, and model selection and density estimation on data fromthe mornings only.

Source

File ‘examples’ distributed with program CAPTURE.

References

Otis, D. L., Burnham, K. P., White, G. C. and Anderson, D. R. (1978)Statistical inference from capture data on closed animalpopulations.Wildlife Monographs62, 1–135.

Examples

plot(housemouse, title = paste("Coulombe (1965), Mus musculus,",    "California salt marsh"), border = 5, rad = 0.5,    gridlines = FALSE)morning <- subset(housemouse, occ = c(1,3,5,7,9))summary(morning)## drop 2 unknown-sex miceknown.sex <- subset(housemouse, !is.na(covariates(housemouse)$sex))## reveal multiple capturestable(trap(housemouse), occasion(housemouse))## Not run: ## assess need to distinguish morning and afternoon sampleshousemouse.0 <- secr.fit (housemouse, buffer = 20)housemouse.ampm <- secr.fit (housemouse, model = g0~tcov, buffer = 20,    timecov = c(0,1,0,1,0,1,0,1,0,1))AIC(housemouse.0, housemouse.ampm)## End(Not run)

Work with Open Population data

Description

Functions for data manipulation

Usage

intervals(object, ...)intervals(object) <- valuesessionlabels(object, ...)sessionlabels(object) <- value

Arguments

Details

intervals extracts the ‘interval’ attribute if it exists.

The attribute ‘intervals’ is set automatically by the secr functionjoin.

sessionlabels provides session names for the primary sessions encoded in a “single-session” capthist object (e.g., the result ofjoin) that has an intervals attribute. The names are used by some summary functions in the packageopenCR (M. Efford unpubl.) (m.array,JS.counts).

The functionsession has a different purpose: labellingsessions in a multi-session capthist object. However,sessionnames of multi-session input are used automatically byjoin to construct thesessionlabels attribute of the resulting single-session object.

Value

Forintervals, a numeric vector of time intervals, one less than the number of occasions (secondary sessions).

Forsessionlabels, a character vector of primary session names.

Note

There is a naming conflict with the intervals function innlme.

Examples

singlesessionCH <- join(ovenCH)intervals(singlesessionCH)sessionlabels(singlesessionCH)

Combine or Split Sessions of capthist Object

Description

Make a single-session capthist object from a list ofsingle-session objects, or a multi-session capthist object.

Usage

 join(object, remove.dupl.sites = TRUE, tol = 0.001, sites.by.name = FALSE,    drop.sites = FALSE, intervals = NULL, sessionlabels = NULL,     timevaryingcov = NULL)     unjoin(object, intervals, ...)

Arguments

Details

join

The input sessions are assumed to be of the same detector type and tohave the same attributes (e.g., covariates should be present for allor none).

The number of occasions (columns) in the output is equal to the sum ofthe number of occasions in each input.

Duplicates may be defined either as sites within a given distance (tol) or sites with the same name (sites.by.name = TRUE). Using site names is faster.

For non-spatial analyses it is efficient to drop the third dimension and discard the traps attribute (drop.sites = TRUE).

A new dataframe of individual covariates is formed using the covariatesfor the first occurrence of each animal.

Iftimevaryingcov is given then for each name a new covariate is generated for each session and populated with values observed in that session, or NA if the animal was not detected. A ‘timevaryingcov’ (list) attribute is created that associates each set of new session-specific columns with the corresponding old name, so that it may be used in formulae (seetimevaryingcov).

Attributes xy and signal are handled appropriately, as is trap usage.

unjoin

The input grouping of occasions (columns) into sessions is specified viaintervals. This is a vector of length one less than the number ofoccasions (columns) inobject. Elements greater than zeroindicate a new session.

Theintervals argument may be omitted ifobject has avalid ‘intervals’ attribute, as in the output fromjoin.

Value

Forjoin, a single-session capthist object. The vector attribute ‘intervals’ records thedistinction between occasions that are adjacent in the input (interval =0) and those that are in consecutive sessions (e.g., interval = 1); ‘intervals’has length one less than the number of occasions.

Forunjoin, a multi-session capthist object. Sessions are namedwith integers.

Note

Do not confuseunjoin withsplit.capthist whichsplits by row (animal) rather than by column (occasion).

Occasions survive intact; to pool occasions usereduce.capthist.

join was modified in version 2.9.5 to check whether thecomponents of ‘object’ all used the same detectors (‘traps’) (puttingaside differences in usage). If the traps are identical andremove.dupl.sites = TRUE then the resulting ‘capthist’ uses the common list ofdetectors, with a usage attribute formed by concatenating the usagecolumns of the input. This is faster than the previous filteringalgorithm using ‘tol’; the older algorithm is still used if the traps differ.

Problems may be encountered with large datasets. These may be alleviated by setting sites.by.name = TRUE (if matching sites have matching names, avoiding the need for coordinate matching) or drop.sites = TRUE (if only non-spatial data are required for openCR).

See Also

MS.capthist,rbind.capthist

Examples

joined.ovenCH <- join (ovenCH)summary(joined.ovenCH)attr(joined.ovenCH, "intervals")summary(unjoin(joined.ovenCH))## Not run: ## suppose the 5-year ovenbird covariates include a column for weight## (here generated as random numbers)for (i in 1:5) covariates(ovenCH[[i]])$wt <- runif(nrow(ovenCH[[i]]))## construct single-session version of data for openCR## identify 'wt' as varying across yearsovenCHj <- join(ovenCH, timevaryingcov = 'wt')head(covariates(ovenCHj))timevaryingcov(ovenCHj)## Use example: openCR.fit(ovenCHj, model = p~wt)## End(Not run)

Overlap Index

Description

Computes the overlap index of Efford et al. (2016) from various inputs, including fitted models.

Usage

kfn(object)

Arguments

Details

kfn simply computesk = \sigma \sqrt D / 100, where\sigma is the sigma parameter of a fitted halfnormal detection function andD is the corresponding density estimate. The factor of 1/100 adjusts for the units used insecr (sigma in metres; D in animals per hectare).

Input may be in any of these forms

1. vector with D and sigma in the first and second positions.

2. matrix with each row as in (1)

3. dataframe such as produced bypredict.secr with rows ‘D’ and ‘sigma’, and column ‘estimate’.

4. fittedsecr model

5. a list of any of the above

Value

Numeric vector with elements ‘D’, ‘sigma’ and ‘k’, or a matrix with these columns.

Note

The index should not be taken too literally as a measure of overlap: it represents the overlap expectedif activity centres are randomly distributed andif home ranges have bivariate normal utilisation. Thus it doesnot measure overlap due to social behaviour etc. except as that affects home range size.

The index may be estimated directly using the sigmak parameterization (i.e., when sigmak appears in the model forsecr.fit). This provides SE and confidence limits for sigmak (=k). However, the directly estimated value of sigmak lacks the unit correction and is therefore 100\times the value fromkfn.

References

Efford, M. G., Dawson, D. K., Jhala, Y. V. and Qureshi, Q. (2016) Density-dependent home-range size revealed by spatially explicit capture–recapture.Ecography39, 676–688.

See Also

predict.secr,secr.fit,details

Examples

kfn(secrdemo.0)## compare## fitk <- secr.fit(captdata, model = sigmak~1, buffer = 100, trace = FALSE)## predict(fitk)

Fit Multiple SECR Models

Description

This function is a wrapper forsecr.fit that allows multiple models to be fitted.

Usage

list.secr.fit (..., constant = list(), prefix = "fit", names = NULL)

Arguments

Details

The ... argument may be one or several vectors of the same length that refer to a different named argument ofsecr.fit.secr.fit is called with the constant arguments plus the first value in each vector, then the second value, etc. The logic followsmapply.

Each of the ... arguments may also be a named argument with a single value, although the compound values should be wrapped in list(), passed by name (in quotes), or placed in the 'constant' list to avoid misinterpretation. For example, the capthist argument ofsecr.fit should be be wrapped in list() or " " if it is placed outside 'constant'.

'prefix' is used only if 'names' is not supplied.

Value

Ansecrlist of the successful model fits (seesecr.fit).

In the special case that ‘constant’ specifies ‘details’ with component LLonly = TRUE, the list of values fromsecr.fit without checking or modification.

Note

This function replaces the previous functionpar.secr.fit: since the introduction of multi-threading insecr 4.0 it is no longer efficient to use parallel worker processes.

See Also

secr.fit,AIC.secr,predict.secr

Examples

## Not run: # fit two detection modelsfits <- list.secr.fit (model = c(g0~1, g0~b), constant = list(captdata, trace = FALSE))AIC(fits)# alternatively,fits <- list.secr.fit ('captdata', model = c(g0~1, g0~b), trace = FALSE)AIC(fits)# replacing par.derived and par.region.N:lapply(fits, derived)lapply(fits, region.N)## End(Not run)

Logit Transformation

Description

Transform real values to the logit scale, and the inverse.

Usage

logit(x)invlogit(y)

Arguments

Details

The logit transformation is defined as\mathrm{logit}(x) = \mathrm{log}( \frac{x}{1-x}) forx \in (0,1).

Value

Numeric value on requested scale.

Note

logit is equivalent toqlogis, andinvlogit is equivalent toplogis (bothR functions in thestats package).logit andinvlogit are used insecr because they are slightly more robust to bad input, and their names are more memorable!

Examples

logit(0.5)invlogit(logit(0.2))

Multinomial Coefficient of SECR Likelihood

Description

Compute the constant multinomial component of the SECR log likelihood

Usage

logmultinom(capthist, grp = NULL)

Arguments

Details

For a particular dataset and grouping, the multinomial coefficient isa constant; it does not depend on the parameters and may be ignoredwhen maximizing the likelihood to obtain parameterestimates. Nevertheless, the log likelihood reported bysecr.fit includes this componentunless thedetector type is ‘signal’, ‘polygon’, ‘polygonX’, ‘transect’ or‘transectX’ (from 2.0.0).

Ifgrp is NULL then all animals are assumed to belong to onegroup. Otherwise, the length ofgrp should equal the number of rows ofcapthist.

grp may also be any vector that can be coercedto a factor. Ifcapthist is a multi-session capthist objectthengrp should be a list with one factor per session.

If capture histories are not assigned to groups the value is thelogarithm of

{{n}\choose{n_1, ..., n_C}} = {{n!} \over {n_1! n_2! ... n_C!}}

wheren is the total number ofcapture histories andn_1 ...n_C are the frequencies withwhich each of theC unique capture histories were observed.

If capture histories are assigned toG groups the value is thelogarithm of

{ \prod_{g=1}^{G} {{n_g!} \over {n_{g1}! n_{g2}! ... n_{gC_g}}!}}

wheren_g is the number of capture histories ofgroupg andn_{g1} ...n_{gC_g} are the frequencies withwhich each of theC_g unique capture histories were observed forgroupg.

For multi-session data, the value is the sum of the single-sessionvalues. Both session structure and group structure therefore affectthe value computed. Users will seldom need this function.

Value

The numeric value of the log likelihood component.

References

Borchers, D. L. and Efford, M. G. (2008) Spatially explicit maximumlikelihood methods for capture–recapture studies.Biometrics64, 377–385.

Efford, M. G., Borchers D. L. and Byrom, A. E. (2009) Density estimationby spatially explicit capture–recapture: likelihood-based methods. In:D. L. Thompson, E. G. Cooch and M. J. Conroy (eds)ModelingDemographic Processes in Marked Populations. Springer. Pp. 255–269.

See Also

stoatDNA

Examples

## no groupslogmultinom(stoatCH)

Construct capthist Object

Description

Form acapthist object from a data frame of capture records and atraps object.

Usage

make.capthist(captures, traps, fmt = c("trapID", "XY"), noccasions = NULL,    covnames = NULL, bysession = TRUE, sortrows = TRUE,    cutval = NULL, tol = 0.01, snapXY = FALSE, noncapt = "NONE", signalcovariates)

Arguments

Details

make.capthist is the most flexible way to prepare data forsecr.fit. Seeread.capthist for a more streamlinedway to read data from text files for common detector types. Each row ofthe input data framecaptures represents a detection on oneoccasion. The capture data frame may be formed from a text file withread.table.

Input formats are based on the Density software (Efford 2012; see alsosecr-datainput.pdf). Iffmt ="XY" the required fields are (session, ID, occasion, x, y) in thatorder. Iffmt = "trapID" the required fields are (session, ID,occasion, trap), wheretrap is the numeric index of the relevantdetector intraps.session andID may becharacter-, vector- or factor-valued; other required fields arenumeric. Fields are matched by position (column number),not byname. Columns after the required fields are interpreted as individualcovariates that may be continuous (e.g., size) or categorical (e.g.,age, sex).

Ifcaptures has data from multiple sessions thentraps maybe either a list oftraps objects, one per session, or a singletraps object that is assumed to apply throughout. Similarly,noccasions may be a vector specifying the number of occasions ineach session.

Covariates are assumed constant for each individual; the firstnon-missing value is used. The length ofcovnames should equal thenumber of covariate fields incaptures.

bysession takes effect when the same individual is detected intwo or more sessions: TRUE results in one capture history per session,FALSE has the effect of generating a single capture history (this is notappropriate for the models currently provided insecr).

Deaths are coded as negative values in the occasion field ofcaptures. Occasions should be numbered 1, 2, ..., noccasions. Bydefault, the number of occasions is the maximum value of ‘occasion’ incaptures.

Signal strengths may be provided in the fifth (fmt = trapID) or sixth(fmt = XY) columns. Detections with signal strength missing (NA) orbelow ‘cutval’ are discarded.

A session may result in no detections. In this case a null line isincluded incaptures using the animal ID field given bynoncapt, the maximum occasion number, and any trapID (e.g. "sess1NONE 5 1" for a 5-occasion session) (or equivalently "sess1 NONE 5 1010" for fmt = XY).

Nonspatial data (Session, AnimalID, Occasion and possibly individual covariates) may be entered by omitting the ‘traps’ argument or setting it to NULL.

Value

An object of classcapthist (a matrix or array ofdetection data with attributes for detector positions etc.). For‘single’ and ‘multi’ detectors this is a matrix with one row per animaland one column per occasion (dim(capthist)=c(nc,noccasions)); eachelement is either zero (no detection) or a detector number (the rownumber intrapsnot the row name). For ‘proximity’detectorscapthist is an array of values {-1, 0, 1} anddim(capthist)=c(nc,noccasions,ntraps). The number of animalsncis determined from the input, as isnoccasions if it is not specified.traps,covariates and other data are retained asattributes ofcapthist.

Deaths during the experiment are represented as negative values incapthist.

For ‘signal’ and ‘signalnoise’ detectors, the columns ofcapturesidentified insignalcovariates are saved along with signalstrength measurements in the attribute ‘signalframe’.

If the input has data from multiple sessions then the output is anobject of class c("capthist", "list") comprising a list of single-sessioncapthist objects.

Note

make.capthist requires that the data forcaptures andtraps already exist asR objects. To read data from external(text) files, first useread.table andread.traps, or tryread.capthist for a one-step solution.

Prior tosecr 4.4.0, occasional valid records for "multi" and "single" detectors were rejected as duplicates.

Fromsecr 4.5.0, ‘snapXY’ works for transects as well as point detectors.

References

Efford, M. G. (2012)DENSITY 5.0: software for spatially explicitcapture–recapture. Department of Mathematics and Statistics,University of Otago, Dunedin, New Zealand.https://www.otago.ac.nz/density/.

See Also

capthist,traps,read.capthist,secr.fit,sim.capthist

Examples

## peek at demonstration datahead(captXY)head(trapXY)demotraps <- read.traps(data = trapXY)demoCHxy  <- make.capthist (captXY, demotraps, fmt = "XY")demoCHxy            ## print method for capthistplot(demoCHxy)      ## plot method for capthistsummary(demoCHxy)   ## summary method for capthist## To enter `count' data without manually repeating rows## need a frequency vector f, length(f) == nrow(captXY)n <- nrow(captXY)f <- sample (1:5, size = n, prob = rep(0.2,5), replace = TRUE)## repeat rows as required...captXY <- captXY[rep(1:n, f),]counttraps <- read.traps(data = trapXY, detector = "count")countCH  <- make.capthist (captXY, counttraps, fmt = "XY")

Construct Lacework Detector Design

Description

A lacework design comprises a square grid with detectors placed at regular distances along the grid lines (Efford unpubl.). This requires fewer detectors than uniform coverage at close spacing and is simpler than clustered designs, while providing good spatial coverage and protection from alignment bias (Efford 2019).

Usage

make.lacework(region, spacing = c(100, 20), times = NULL, origin = NULL,     rotate = 0, radius = NULL, detector = "multi", keep.design = TRUE)

Arguments

Details

It is tidy for the major spacing (spacing[1]) to be a multiple of the minor spacing (spacing[2]); precisely one detector is then placed at each grid intersection. This outcome may also be achieved by providing only the minor spacing in thespacing argument and specifying an integer value fortimes.

In general it is better not to specifyorigin. Specifying bothorigin androtate may result in incomplete coverage, as the desired grid is relative to the bounding box of therotated region.

Setradius < spacing[1]/2 to break lacework into multiple cross-shaped arrays centred on the intersections (crossing points) and truncated atradius metres (assuming you follow advice and express all linear measurements in metres).

The number of detectors should not exceed 5000.

Value

Ansecr traps object. The attribute ‘crossings’ is a 2-column matrix with the coordinates of the intersection points. Ifkeep.design is TRUE then the input argument values are retained in attribute ‘design’ (a list with first componentfunction = 'make.lacework').

References

Efford, M. G. (2019) Non-circular home ranges and the estimation of population density.Ecology100, e02580.doi:10.1002/ecy.2580

See Also

make.systematic

Examples

trps <- make.lacework(possumarea, c(1000,100), rotate = 45, detector = 'proximity')plot(trps, gridspace = 1000)lines(possumarea)points(attr(trps, 'crossings'), pch = 16)

Build Habitat Mask

Description

Construct a habitat mask object for spatially explicit capture-recapture. A mask object is a set of points with optional attributes.

Usage

make.mask(traps, buffer = 100, spacing = NULL, nx = 64, ny = 64, type =    c("traprect", "trapbuffer", "pdot", "polygon", "clusterrect",    "clusterbuffer", "rectangular", "polybuffer"), poly = NULL, poly.habitat = TRUE,    cell.overlap = c("centre","any","all"), keep.poly = TRUE, check.poly = TRUE,     pdotmin = 0.001, random.origin = FALSE,    ...)

Arguments

Details

The ‘traprect’ method constructs a grid of points in the rectangleformed by adding a buffer strip to the minimum and maximum x-ycoordinates of the detectors intraps. Both ‘trapbuffer’ and‘pdot’ start with a ‘traprect’ mask and drop some points.

The ‘trapbuffer’ method restricts the grid to points within distancebuffer of any detector.

The ‘pdot’ method restricts the grid to points for which the netdetection probabilityp.(\mathbf{X}) (seepdot) is at leastpdotmin. Additional parametersare used bypdot (detectpar, noccasions). Set these with the... argument; otherwisemake.mask will silently use thearbitrary defaults.pdot is currently limited to a halfnormaldetection function.

The ‘clusterrect’ method constructs a grid of rectangular submaskscentred on ‘clusters’ of detectors generated withtrap.builder (possibly indirectly bymake.systematic). The ‘clusterbuffer’ method resembles‘trapbuffer’, but is usually faster when traps are arranged in clustersbecause it starts with a ‘clusterrect’ mask.

The ‘rectangular’ method constructs a simple rectangular mask with thegiven nx, ny and spacing.

The ‘polybuffer’ method constructs a mask by buffering around the polygon specified in the ‘poly’ argument. If that inherits from ‘SpatialPolygons’ or ‘sfc’ then the buffering is performed with sf::st_buffer. Otherwise, buffering is approximate, based on the distance to points on an initial discretized mask enclosed by ‘poly’ (points at half the current ‘spacing’).

Ifpoly is specified, points outsidepoly are dropped (unless type = "polybuffer"). The default is to require only the centre to lie withinpoly; usecell.overlap = "all" to require all cell corners to lie withinpoly, orcell.overlap = "any" to accept cells with any corner inpoly. The ‘polygon’ method places points on a rectangular grid clipped to thepolygon (buffer is not used). Thus ‘traprect’ is equivalent to‘polygon’ whenpoly is supplied.poly may be either

• a matrix or dataframe of two columns interpreted as x and ycoordinates, or

• an object from package ‘sf’ with polygon geometries, or

• a SpatialPolygons or SpatialPolygonsDataFrame object as defined in the package ‘sp’,possibly imported by reading a shapefile.

Ifspacing is not specified then it is determined by dividing therange of the x coordinates (including any buffer) bynx.

random.origin shifts the origin of the mask by a uniform random displacement within a spacing x spacing grid cell, while ensuring that the mask also satisfies the buffer requirement.random.origin is available only for ‘traprect’, ‘trapbuffer’, ‘polygon’, and ‘rectangular’ types, andspacing must be specified.

Value

An object of classmask. Whenkeep.poly = TRUE,poly andpoly.habitat are saved as attributes of themask.

Note

A warning is displayed iftype = "pdot" and the buffer is too small toinclude all points withp. > pdotmin.

A habitat mask is needed to fit an SECR model and for some relatedcomputations. The default mask settings insecr.fit may be goodenough, but it is preferable to usemake.mask to construct a maskin advance and to pass that mask as an argument tosecr.fit.

The functionbufferContour displays the extent of one or more‘trapbuffer’ zones - i.e. the effect of buffering the detector arraywith varying strip widths.

See Also

mask,read.mask,subset.mask,pdot,bufferContour,deleteMaskPoints,as.mask

Examples

temptrap <- make.grid(nx = 10, ny = 10, spacing = 30)## default method: traprecttempmask <- make.mask(temptrap, spacing = 5)plot(tempmask)summary (tempmask)## make irregular detector array by subsampling ## form mask by `trapbuffer' methodtemptrap <- subset (temptrap, sample(nrow(temptrap), size = 30))tempmask <- make.mask (temptrap, spacing = 5, type = "trapbuffer")plot (tempmask)plot (temptrap, add = TRUE)## Not run: ## form mask by "pdot" methodtemptrap <- make.grid(nx = 6, ny = 6)tempmask <- make.mask (temptrap, buffer = 150, type = "pdot",     pdotmin = 0.0001, detectpar = list(g0 = 0.1, sigma = 30),    noccasions = 4)plot (tempmask)plot (temptrap, add = TRUE)## Using an ESRI polygon shapefile for clipping (shapefile## polygons may include multiple islands and holes).library(sf)shpfilename <- system.file("extdata/possumarea.shp", package = "secr")possumarea <- st_read(shpfilename)possummask2 <- make.mask(traps(possumCH), spacing = 20,    buffer = 250, type = "trapbuffer", poly = possumarea)par(mar = c(1,6,6,6), xpd = TRUE)plot (possummask2, ppoly = TRUE)plot(traps(possumCH), add = TRUE)par(mar = c(5,4,4,2) + 0.1, xpd = FALSE)## if the polygon delineates non-habitat ...seaPossumMask <- make.mask(traps(possumCH), buffer = 1000,     type = "traprect", poly = possumarea, poly.habitat = FALSE)plot(seaPossumMask)plot(traps(possumCH), add = TRUE)## this mask is not useful!## End(Not run)

Construct Spatial Coverage Design

Description

A spatial coverage design places one cluster of detectors in each compact subregion of a region of interest. Equal subregions are determined byk-means clustering of pixels (Walvoort et al. 2010).

Usage

make.spcosa(n, cluster, region, rotation = 0, randomize = FALSE, maxtries = 100,     keep.mask = FALSE, ...)

Arguments

Details

The region may be specified in any form acceptable as the ‘poly’ argument ofmake.mask (see alsoboundarytoSF).

The ... argument determines the coarseness of the discretization used to define the subregions, via the ‘nx’ or ‘spacing’ arguments ofmake.mask.

By default (randomize = FALSE) clusters are centred at subregion centroids. Otherwise (randomize = TRUE) clusters are centred in a randomly selected cell of each subregion, subject to the constraint that all detectors fall within the subregion. An error results if no cluster meeting the constraint is found in ‘maxtries’ attempts.

Slightly different partitions of ‘poly’ are generated depending on the value of the random seed, so for consistency this should be first set withset.seed.

The argument ‘rotation’ is applied separately to each cluster, as intrap.builder and unlike the argument ‘rotate’ ofmake.systematic.

Value

A traps object with n x nrow(cluster) detectors.

References

Walvoort, D., Brus, D., and de Gruijter, J. (2010) An R package for spatialcoverage sampling and random sampling from compact geographical strata by k-means.Computers & Geosciences 36:1261–1267.

See Also

make.mask,trap.builder,boundarytoSF,traps

Examples

# check package 'spcosa' installedif (requireNamespace("spcosa")) {# preliminariespolygonfile <- system.file("extdata/possumarea.txt", package = "secr")poly <- read.table(polygonfile, header = TRUE)subgrid <- make.grid(3,3, spacing = 80)set.seed(123)# nx and keep.mask refer to the discretized region of interesttr <- make.spcosa(n = 5, subgrid, poly, nx = 32, randomize = TRUE,           keep.mask = TRUE)plot(attr(tr,'mask'), dots = FALSE, cov = 'stratum', legend = FALSE)plot(tr, add = TRUE)lines(poly)}

Construct Systematic Detector Design

Description

A rectangular grid of clusters within a polygonal region.

Usage

make.systematic(n, cluster, region, spacing = NULL, origin = NULL,     originoffset = c(0,0), chequerboard = c('all','black','white'),     order = c('x', 'y', 'xb', 'yb'), rotate = 0,  centrexy = NULL,    keep.design = TRUE, ...)

Arguments

Details

region may be any shape.

region may be one of the spatial classes described inboundarytoSF. Otherwise,region should be a dataframe with columns ‘x’ and ‘y’.

spacing may be a vector with separate values for spacing in x-and y- directions. Ifspacing is provided thenn is ignored.

Ifn is a scalar, the spacing of clusters is determined fromthe area of the bounding box ofregion divided by the requestednumber of clusters (this does not necessarily result in exactly nclusters). Ifn is a vector of two integers these are taken to bethe number of columns and the number of rows.

After preparing a frame of cluster centres,make.systematiccallstrap.builder with method = ‘all’; ... allows thearguments ‘rotation’, ‘edgemethod’, ‘plt’, and ‘detector’ to bepassed. Setting thetrap.builder argumentsframe,method, andsamplefactor has no effect.

Note the distinction between argumentrotate and thetrap.builder argumentrotation that is applied separately to each cluster.

Iforigin is not specified then a random uniform origin is chosen within a box (width = spacing) placed with its bottom left corner at the bottom left of the bounding box ofregion, shifted byoriginoffset. Before version 3.1.8 the behaviour ofmake.systematic was equivalent tooriginoffset = c(wx,wy) wherewx,wy are the cluster half widths.

chequerboard = "black" retains black ‘squares’ andchequerboard = "white" retains white ‘squares’, where the lower left cluster in the candidate rectangle of cluster origins is black, as on a chess board. The effect is the same as increasing spacing by sqrt(2) and rotating through 45 degrees.

order determines the ordering of clusters in the resulting traps object. The options are a subset of those forID argument ofmake.grid:

rotate rotates the array about the given centre (default is centroid of the bounding box ofregion).

Value

A single-session ‘traps’ object.

From 3.2.0 these additional attributes are set –

From 4.2.0 ifkeep.design is TRUE then the input argument values are retained in attribute ‘design’ (a list with first componentfunction = 'make.systematic').

Note

Do not confuse with the simpler functionmake.grid,which places single detectors in a rectangular array.

See Also

trap.builder,make.lacework,cluster.centres

Examples

mini <- make.grid(nx = 2, ny = 2, spacing = 100)region <- cbind(x=c(0,2000,2000,0), y=c(0,0,2000,2000))temp <- make.systematic(25, mini, region, plt = TRUE)temp <- make.systematic(c(6, 6), mini, region, plt = TRUE,    rotation = -1)## Example using shapefile "possumarea.shp" in## "extdata" folder. By default, each cluster is ## a single multi-catch detector## Not run: library(sf)shpfilename <- system.file("extdata/possumarea.shp", package = "secr")possumarea <- st_read(shpfilename)possumgrid <- make.systematic(spacing = 100, region =    possumarea, plt = TRUE)## or with 2 x 2 clusterspossumgrid2 <- make.systematic(spacing = 300,    cluster = make.grid(nx = 2, ny = 2, spacing = 100),    region = possumarea, plt = TRUE, edgemethod =    "allinside")## label clusterstext(cluster.centres(possumgrid2), levels(clusterID    (possumgrid2)), cex=0.7)## If you have GPSBabel installed and on the Path## then coordinates can be projected and uploaded## to a GPS with `writeGPS', which also requires the## package `proj4'. Defaults are for a Garmin GPS## connected by USB.if (interactive()) {    writeGPS(possumgrid, proj = "+proj=nzmg")}## End(Not run)

Build Detector Array

Description

Construct a rectangular array of detectors (trapping grid) or a circle of detectors or a polygonal search area.

Usage

make.grid(nx = 6, ny = 6, spacex = 20, spacey = spacex, spacing = NULL,    detector = "multi", originxy = c(0,0), hollow = FALSE, ID = "alphay",     leadingzero = TRUE, markocc = NULL)make.circle (n = 20, radius = 100, spacing = NULL,     detector = "multi", originxy = c(0,0), IDclockwise = TRUE,     leadingzero = TRUE, markocc = NULL)make.poly (polylist = NULL, x = c(-50,-50,50,50),    y = c(-50,50,50,-50), exclusive = FALSE, verify = TRUE)make.transect (transectlist = NULL, x = c(-50,-50,50,50),    y = c(-50,50,50,-50), exclusive = FALSE)make.telemetry (xy = c(0,0))

Arguments

Details

make.grid generates coordinates fornx.ny traps atseparationsspacex andspacey. Ifspacing isspecified it replaces bothspacex andspacey. Thebottom-left (southwest) corner is atoriginxy. For a hollow grid,only detectors on the perimeter are retained. By default, identifiersare constructed from a letter code for grid rows and an integer valuefor grid columns ("A1", "A2",...). ‘Hollow’ grids are always numberedclockwise in sequence from the bottom-left corner. Other values ofID have the following effects:

‘xy’ adds leading zeros as needed to give a string of constant length withno blanks.

make.circle generates coordinates for n traps in a circle centredonoriginxy. Ifspacing is specified then it overrides theradius setting; the radius is adjusted to provide the requestedstraightline distance between adjacent detectors. Traps are numberedfrom the trap due east of the origin, either clockwise or anticlockwiseas set byIDclockwise.

Polygon vertices may be specified withx andy in the caseof a single polygon, or aspolylist for one or more polygons. Eachcomponent ofpolylist is a dataframe with columns ‘x’ and ‘y’.polylist takes precedence.make.poly automatically closesthe polygon by repeating the first vertex if the first and last verticesdiffer.

Transects are defined by a sequence of vertices as for polygons, except that they are not closed.

make.telemetry builds a simple traps object for the 'telemetry' detector type. The attribute 'telemetrytype' is set to "independent".

Specialised functions for arrays using a triangular grid are describedseparately (make.tri,clip.hex).

Value

An object of classtraps comprising a data frame of x- andy-coordinates, the detector type ("single", "multi", or "proximity" etc.),and possibly other attributes.

Note

Several methods are provided for manipulating detector arrays - seetraps.

References

Efford, M. G. (2012)DENSITY 5.0: software for spatially explicitcapture–recapture. Department of Mathematics and Statistics,University of Otago, Dunedin, New Zealand.https://www.otago.ac.nz/density/.

Efford, M. G., Borchers D. L. and Byrom, A. E. (2009) Density estimationby spatially explicit capture-recapture: likelihood-based methods. In:D. L. Thomson, E. G. Cooch and M. J. Conroy (eds)ModelingDemographic Processes in Marked Populations. Springer, New York. Pp.255–269.

See Also

read.traps,detector,trap.builder,make.systematic,print.traps,plot.traps,traps,make.tri,addTelemetry

Examples

demo.traps <- make.grid()plot(demo.traps)## compare numbering schemespar (mfrow = c(2,4), mar = c(1,1,1,1), xpd = TRUE)for (id in c("numx", "numy", "alphax", "alphay", "numxb",     "numyb")){    temptrap <- make.grid(nx = 7, ny = 5, ID = id)    plot (temptrap, border = 10, label = TRUE, offset = 7,         gridl = FALSE)}temptrap <- make.grid(nx = 7, ny = 5, hollow = TRUE)plot (temptrap, border = 10, label = TRUE, gridl = FALSE)plot(make.circle(n = 20, spacing = 30), label = TRUE, offset = 9)summary(make.circle(n = 20, spacing = 30))## jitter locations randomly within grid square## and plot over `mask'# see also ?gridCellstr0 <- tr <- make.grid(nx = 7, ny = 7, spacing = 30)tr[] <- jitter(unlist(tr), amount = spacing(tr)/2)plot(as.mask(tr0), dots = FALSE, mesh = 'white')plot(tr, add = TRUE)

Build Detector Array on Triangular or Hexagonal Grid

Description

Construct an array of detectors on a triangular grid and optionallyselect a hexagonal subset of detectors.

Usage

make.tri (nx = 10, ny = 12, spacing = 20, detector = "multi",    originxy = c(0,0))clip.hex (traps, side = 20, centre = c(50, 60*cos(pi/6)),    fuzz = 1e-3, ID = "num", ...)

Arguments