| Type: | Package |
| Title: | Spatially Explicit Capture-Recapture by Inverse Prediction |
| Version: | 1.4.4 |
| Date: | 2025-06-10 |
| Description: | Estimates the density of a spatially distributed animal population sampled with an array of passive detectors, such as traps. Models incorporating distance-dependent detection are fitted by simulation and inverse prediction as proposed by Efford (2004) <doi:10.1111/j.0030-1299.2004.13043.x>. |
| Depends: | R (≥ 3.5.0), secr (≥ 4.5.8) |
| Imports: | graphics, grDevices, MASS, nlme, parallel, Rcpp (≥ 1.0.8.3),stats, stringr, tools, utils |
| Suggests: | FrF2, knitr, plot3D , rmarkdown, sf, spatstat, testthat (≥0.11.0) |
| LinkingTo: | BH, Rcpp, RcppArmadillo |
| VignetteBuilder: | knitr |
| License: | GPL-2 |GPL-3 [expanded from: GPL (≥ 2)] |
| LazyData: | yes |
| LazyDataCompression: | xz |
| URL: | https://github.com/MurrayEfford/ipsecr/,https://www.otago.ac.nz/density/ |
| NeedsCompilation: | yes |
| Packaged: | 2025-06-10 03:29:58 UTC; murra |
| Author: | Murray Efford [aut, cre] |
| Maintainer: | Murray Efford <murray.efford@otago.ac.nz> |
| Repository: | CRAN |
| Date/Publication: | 2025-06-10 05:20:02 UTC |
Spatially Explicit Capture–Recapture by Inverse Prediction
Description
Functions to estimate the density of a spatiallydistributed animal population sampled with an array of passivedetectors, such as traps.ipsecr addresses ‘difficult’ models that strictly cannot be fitted by maximum likelihood in the packagesecr (Efford 2022). The classic example concerns discrete-time datafrom single-catch traps.
Details
| Package: | ipsecr |
| Type: | Package |
| Version: | 1.4.4 |
| Date: | 2025-06-10 |
| License: | GNU General Public License Version 2 or later |
Spatially explicit capture–recapture is a set of methods for studyingmarked animals distributed in space. Data comprise the locations ofdetectors (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 are defined inipsecr using symbolic formula notation. The set of possible models overlaps withsecr (some models for varying detection parameters are excluded, e.g., ~t, ~b). Density models may include spatial trend. Habitat is distinguished from nonhabitat with an object of class ‘mask’.
Models are fitted inipsecr by simulation and inverse prediction (Efford 2004, 2023). A model fitted withipsecr.fit is an objectof classipsecr. Generic methods (plot, print, summary, etc.) areprovided.
A link at the bottom of each help page takes you to thehelp index. The vignette includes worked examples.
The analyses inipsecr 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/forum/ andthe Google groupsecrgroup. Feedback on the software is also welcome, including suggestions for additionaldocumentation or new features consistent with the overall design.
‘Inverse prediction’ uses methods from multivariate calibration (Brown1982). The goal is to estimate population density (D) and the parametersof a detection function (usually g0 or lambda0 and sigma) by ‘matching’ statisticsfromproxyfn(capthist) (the target vector) to statisticsfrom simulations of a 2-D population using the postulated detectionmodel. Statistics (see Note) are defined by the proxy function,which should return a vector equal in length to the number of parameters(default np = 3). Simulations of the 2-D population use either internal C++ code orsim.popn. The simulated 2-D distribution of animals is Poisson by default.
The simulated population is sampled with internal C++ code,sim.capthist, or a user-specified function. Simulations match the detector type (e.g., ‘single’ or ‘multi’) and detector layout specified in traps(capthist), including allowance for varying effort if the layout has ausage attribute.
Simulations are usually conducted on a factorial experimental design inparameter space - i.e. at the vertices of a cuboid ‘box’ centred on theworking values of the parameters, plus an optional number of centrepoints.
A multivariate linear model is fitted to predict each vector of simulatedproxies from the known parameter values. Simulations are performed at each design point until a specified precision is reached, up to a user-specified maximum number.
Once a model with sufficient precision has been obtained, a new workingvector of parameter estimates is ‘predicted’ by inverting the linearmodel and applying it to the target vector. A working vectoris accepted as the final estimate when it lies within the box; thisreduces the bias from using a linear approximation to extrapolate anonlinear function. If the working vector lies outside the box then a newdesign is centred on value for each parameter in the working vector.
Once a final estimate is accepted, further simulations are conducted toestimate the variance-covariance matrix. These also provide a parametricbootstrap sample to evaluate possible bias.
See Efford et al. (2004) for an early description of the method, andEfford et al. (2005) for an application.
If not provided, the starting values are determined automaticallywith the **secr** functionmakeStart.
Linear measurements are assumed to be in metres and density in animalsper hectare (10 000\mbox{m}^2).
Ifncores > 1 theparallel package is used to createworker processes on multiple cores (seeParallel for more).
Author(s)
Murray Effordmurray.efford@otago.ac.nz
References
Brown, P. J. (1982) Multivariate calibration.Journal of the RoyalStatistical Society, Series B44, 287–321.
Efford, M. G. (2004) Density estimation in live-trapping studies.Oikos106, 598–610.
Efford, M. G. (2022) secr: Spatially explicit capture–recapture models. R package version 4.5.8. https://CRAN.R-project.org/package=secr/
Efford, M. G. (2023) ipsecr: An R package for awkward spatial capture–recapture data.Methods in Ecology and Evolution14, 1182–1189.
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.
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., Warburton, B., Coleman, M. C. and Barker, R. J. (2005) Afield test of two methods for density estimation.Wildlife SocietyBulletin33, 731–738.
Otis, D. L., Burnham, K. P., White, G. C. and Anderson, D. R. (1978)Statistical inference from capture data on closed animal populations.Wildlife Monographs62.
See Also
proxy.msipsecr.fit,secr.fit,capthist,mask
Internal Functions
Description
Functions called internally byipsecr. These are exported and may be called separately for testing.
Usage
proxy.ms(capthist, model = NULL, trapdesigndata = NULL, ...)detectionDesignData(capthist, byoccasion = FALSE, ...)proxyfn1(capthist, N.estimator = c("n", "null","zippin","jackknife"), ...)simpop(mask, D, N, details = list(), ...)simCH(traps, popn, detectfn, detparmat, noccasions, NT = NULL, details = list(), ...) rpsv(capthist)rpsvi(capthist)Arguments
capthist | secr capthist object |
model | named list of model formulae (see |
trapdesigndata | dataframe with one row for each detector and session |
... | other arguments, mostly unused |
byoccasion | logical; if TRUE the output rows are repeated for each occasion |
N.estimator | character name of closed-population estimator |
mask | secr mask object |
D | numeric density in each mask cell |
N | integer number of animals to simulate |
traps | detector locations assecr traps object |
popn | animal locations assecr popn object |
detectfn | integer code for detection function (seedetectfn) |
detparmat | numeric matrix of detection parameter values |
noccasions | integer number of sampling occasions |
NT | numeric hazard of non-target interference at each detector |
details | list with optional additional named arguments |
Details
proxy.ms is the default proxyfn used byipsecr.fit. When used internally byipsecr.fit, ‘model’ and ‘trapdesigndata’ are passed automatically. The ... argument ofproxy.ms may be used to pass arguments toaddCovariates, especially ‘spatialdata’. FunctiondetectionDesignData is used internally to construct design data for non-constant detection models (lambda0, sigma), used in the glm 'data' argument. The capthist argument fordetectionDesignData should always be a list (wrap a single-session capthist in list()).
simpop is used byipsecr.fit for popmethod 'internal'. It is faster and simpler than thesecr functionsim.popn. The details component 'distribution' is a character value that may be ‘poisson’ (default) or 'even.
simCH is used byipsecr.fit for CHmethod 'internal'. It is faster and simpler than thesecr functionsim.capthist, and optionally simulates non-target interference. The argumentdetparmat is an individual x parameter matrix, with parameters in the order usual fordetectfn.
D andNT are matrices with one column per session.
proxyfn1 is a simple proxy function included mostly for historical reasons. It updates the function of Efford (2004) by log-transforming N, using a complementary log-log transformation instead of odds for p, and using log(RPSV(capthist)) for sigma. If you're interested, look at the code.
rpsv(capthist) is equivalent tosecr RPSV(capthist, CC = TRUE).rpsvi(capthist) returns a vector of individual-specific rpsv.
Value
proxy.ms – a numeric vector of length >= 3 corresponding to proxies for a wide range of models, including multi-session density and non-target interference models.
detectionDesignData – a dataframe with one row per individual per session (byoccasion = FALSE) or one row per individual per occasion per session (byoccasion = TRUE), ordered by session, occasion and individual. Columns include x and y coordinates of the individual's centroid, session, and any individual covariates.
proxyfn1 – a numeric vector of length 3 corresponding to proxies for population size, capture probability intercept and scale of detection.
simpop – apopn object.
simCH – a single-sessioncapthist object.
rpsv – scalar
rpsvi – vector, one element per animal
Note
proxyfn0 was removed in version 1.2.0.
References
Efford, M. G. (2004) Density estimation in live-trapping studies.Oikos106, 598–610.
See Also
Examples
proxy.ms(captdata)Detail Specification for ipsecr.fit
Description
The functionipsecr.fit allows many options. Some of these are usedinfrequently and have been bundled as a single argumentdetailsto simplify the documentation. They are described here in two groups: tuning parameters are listed in the following table, and more exotic options follow, listed alphabetically.
Tuning parameters
| Parameter | Default | Description |
| boxsize1 | 0.2 | scalar or vector of length np for size of design |
| boxsize2 | 0.05 | as forboxsize1; used from second box onwards |
| centre | 3 | number of centre points in simulation design |
| min.nsim | 20 | minimum number of simulations per point |
| max.nsim | 200 | maximum number of simulations per point |
| dev.max | 0.002 | tolerance for precision of points in proxy space (see below) |
| var.nsim | 2000 | number of additional simulations to estimate variance-covariance matrix |
| min.nbox | 2 | minimum number of attempts to `frame' solution |
| max.nbox | 5 | maximum number of attempts to `frame' solution |
| max.ntries | 2 | maximum number of attempts at each simulation |
dev.max defines a stopping rule: simulations are added in blocks of details$min.nsim until a measure of precision is less than dev.max for all proxies. If a vector of length 2, the first element applies to the first box and the second to all later boxes. The measure of precision may be the standard error on the link scale (details$boxtype = "absolute") or the coefficient of variation (details$boxtype = "relative").
Other ‘details’ components
binomN (default 0 = Poisson) integer code for distribution of counts.
boxtype (default "absolute") switches between specifying box size as additive on the transformed parameter scale ("absolute") and relative on the transformed parameter scale ("relative").
CHmethod (default "internal") chooses between internal C++ code, thesecr functionsim.capthist, and a user-provided R function with arguments "traps", "popn", "detectfn", "detectpar", and "noccasions". See also popmethod.
contrasts (default NULL) bmay 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.
debug (default FALSE) is used only for debugging. In ordinary use it should not be changed from the default.
distribution (default "poisson") 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 component ‘distribution’ may alsotake a numeric value larger than nrow(capthist), rather than "binomial"or "poisson".
extraparam is a list of starting values for extra 'real' parameters that may be needed for some user-specified models. See the vignette for explanation and an example.
factorial (default "full") chooses between "full" or "fractional" design. Fractional requires the package **FrF2** (Groemping 2014).
forkonunix (default TRUE) switches the cluster type generated bymakeCluster between FORK and PSOCK.
FrF2args (default NULL) provides a list of arguments defining a fractional design.
ignorenontarget (default FALSE) may be used to ignorenon-target information (the capthist attribute 'nontarget'). The default is to model non-target information if it is present.
ignoreusage (default FALSE) may be used to ignore usage (varying effort)information in the traps component. The default is to include usage in the model.
keep.sim (default FALSE) when TRUE causesipsecr.fit to save additional output, specifically lists (one component per box) of the simulations and parameters for each box, and the final variance simulations.
newdetector (default NULL) may be used to override the detector type of the traps object embedded in the capthist passed toipsecr.fit.
Nmax (default 1e4) maximum allowed population size for simulations.
nontargettype (default "exclusive") chooses among options "exclusive", "truncated", "erased, "independent", and "dependent". See vignette.
popmethod (default "internal") chooses between internal C++ code, thesecr functionsim.popn, and a user-provided R function with arguments 'mask', 'D' (density per cell of mask) and 'N' (number of individuals to simulate). See also CHmethod.
savecall (default TRUE) determines whether the function call is included in the output.
YonX (default TRUE) switches between regression of simulated proxy values Y on controlled parameter values X, or the reverse (which is not fully implemented).
References
Groemping, U. (2014). R Package FrF2 for Creating and Analyzing Fractional Factorial 2-Level Designs.Journal of Statistical Software,56, 1–56. https://www.jstatsoft.org/article/view/v056i01.
See Also
Defunct Functions in Packageipsecr
Description
These functions are no longer available inipsecr.
Usage
# Defunct in 1.2.0 (2022-08)proxyfn0()Details
proxyfn0 was removed without warning in ipsecr 1.2.0. Useproxyfn1 orproxy.ms.
See Also
Deprecated Functions in Packageipsecr
Description
These functions will be removed from future versions ofipsecr.
Details
No functions are deprecated at this point.
See Also
Spatially Explicit Capture–Recapture by Inverse Prediction
Description
Estimate population density by simulation and inverse prediction (Efford 2004; Efford,Dawson & Robbins 2004). A restricted range of SECR models may be fitted.
Usage
ipsecr.fit(capthist, proxyfn = proxy.ms, model = list(D ~ 1, g0 ~ 1, sigma ~ 1), mask = NULL, buffer = 100, detectfn = "HN", binomN = NULL, start = NULL, link = list(), fixed = list(), timecov = NULL, sessioncov = NULL, details = list(), verify = TRUE, verbose = TRUE, ncores = NULL, seed = NULL, ...)Arguments
capthist | secr capthist object including capture data and detector (trap) layout |
proxyfn | function to compute proxy from capthist for each coefficient (beta parameter) |
model | list with optional components each symbolically defining a linear predictor for one real parameter using |
mask |
|
buffer | scalar mask buffer radius in metres if |
detectfn | integer code or character string for shape ofdetection function 0 = halfnormal, 1 = hazard rate etc. – seedetectfn |
binomN | integer code for distribution of counts (see Details) |
start | vector of initial values for beta parameters, or |
link | list with optional components corresponding to ‘real’parameters (e.g., ‘D’, ‘g0’, ‘sigma’), each a character string in{"log", "logit", "identity", "sin"} for the link function of one real parameter |
fixed | list with optional components corresponding to real parameters giving the scalar value to which the parameter is to be fixed |
timecov | optional dataframe of values of time (occasion-specific) covariate(s). NOT USED |
sessioncov | optional dataframe of values of session-specific covariate(s) |
details | list of additional settings, to control estimation (see Details) |
verify | logical, if TRUE the input data are checked with |
verbose | logical, if TRUE then messages are output during execution |
ncores | integer number of cores to use for parallel processing |
seed | either NULL or an integer that will be used in a call to |
... | other arguments passed to proxy function |
Details
The vignette should be consulted for a full exposition.
Parallel computation
ncores determines the number of worker processes in a cluster created bymakeCluster (default type "FORK" on Unix platforms, otherwise "PSOCK"). Ifncores = NULL this defaults to the value fromsetNumThreads. Simulations are distributed over worker processes usingparRapply. There are substantial overheads in running multiple processes: using too many will slow down fitting. With PSOCK clusters (i.e. on Windows) fitting is very often fastest with ncores = 1.
The ‘details’ argument
details is used for various specialized settings listed below. These are also described separately - seedetails.
| Name | Default | Description |
| boxsize1 | 0.2 | scalar or vector of length np for size of design |
| boxsize2 | 0.05 | as forboxsize1; used from second box onwards |
| boxtype | 'absolute' | `absolute' or `relative' |
| centre | 3 | number of centre points in simulation design |
| dev.max | 0.002 | tolerance for precision of points in predictor space |
| var.nsim | 2000 | number of additional simulations to estimate variance-covariance matrix |
| keep.sim | FALSE | if true then the variance simulations are saved |
| min.nsim | 20 | minimum number of simulations per point |
| max.nsim | 200 | maximum number of simulations per point |
| min.nbox | 2 | minimum number of attempts to `frame' solution |
| max.nbox | 5 | maximum number of attempts to `frame' solution |
| max.ntries | 2 | maximum number of attempts at each simulation |
| distribution | `poisson' | `poisson', `binomial' or `even' |
| binomN | 0 | integer code for distribution of counts (unused) |
| ignorenontarget | FALSE | override nontarget attribute of capthist |
| ignoreusage | FALSE | override usage in traps object of capthist |
| debug | FALSE | stop at arbitrary points in execution (varies) |
| savecall | TRUE | optionally suppress saving of call |
| newdetector | NULL | detector type that overrides detector(traps(capthist)) |
| contrasts | NULL | coding of factor predictors |
| popmethod | `internal' | `internal' or `sim.popn' or a user-provided function |
| CHmethod | `internal' | `internal' or `sim.capthist' or a user-provided function |
| factorial | `full' | `full' or `fractional' design |
| FrF2args | NULL | arguments for FrF2 when factorial = 'fractional' |
| extraparam | NULL | list of starting values for extra parameters (see vignette) |
| forkonunix | TRUE | logical choice between FORK and PSOCK cluster types (not Windows) |
Value
An object of class 'ipsecr', a list comprising:
call | the function call (if details$savecall) |
capthist | input |
proxyfn | input |
model | input |
mask | input |
detectfn | input |
start | input |
link | input |
fixed | input |
timecov | input |
sessioncov | input |
details | input |
designD | list of design data for density |
trapdesigndata | list of design data for trap-specific models |
parindx | mapping of coefficients (beta parameters) to real parameters |
vars | names of covariates in model |
betanames | names of coefficients |
realnames | names of 'real' parameters |
code | integer completion code: 1 successful, 2 target not within final box, 3 exceeded maximum simulations |
beta | estimates of coefficients on link scale |
beta.vcov | variance-covariance matrix of estimates |
designbeta | vertices of final box (design points) |
sim.lm | last lm model fit |
ip.nsim | total number of simulations |
var.nsim.OK | number of successful variance simulations |
simulations | optional simulation output (see details$keep.sim) |
parameters | optional simulation input (see details$keep.sim) |
variance.bootstrap | dataframe summarising simulations for variance estimation |
version | package version |
starttime | time execution started |
proctime | processor time (seconds) |
seed | RNG state |
(The order and composition of the output list may change).
References
Efford, M. G. (2004) Density estimation in live-trapping studies.Oikos106, 598–610.
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.
See Also
proxy.ms,predict.ipsecr,summary.ipsecr
Examples
ipsecrdemo <- ipsecr.fit(captdata, ncores = 1, buffer = 100, detectfn = 14, seed = 1237)SECR Model Fitted to Demonstration Data
Description
Demonstration data from program Density are provided as acapthist object (captdata) ready for input toipsecr.fit.
The fitted models are objects of classipsecr formed by
ipsecrdemo <- ipsecr.fit(captdata, ncores = 1, detectfn = 'HHN', seed = 1237, details = list(keep.sim = TRUE))
Usage
data(ipsecrdemo)Details
The raw data are 235 fictional captures of 76 animals over 5 occasionsin 100 single-catch traps 30 metres apart on a square grid with originat (365,365).
The fitted model uses a hazard halfnormal detection function and default values of other arguments.
| Object | Description |
| ipsecrdemo | fitted ipsecr model -- null |
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,read.capthist,secrdemo
Examples
predict(ipsecrdemo)Create Default Design Data
Description
Internal function used to generate a dataframe containing design datafor the base levels of all predictors in an secr object.
Usage
## S3 method for class 'ipsecr'makeNewData(object, all.levels = FALSE, ...)Arguments
object | fitted ipsecr model object |
all.levels | logical; if TRUE then all levels of factors are included |
... | other arguments (not used) |
Details
makeNewData is used bypredict in lieu ofuser-specified ‘newdata’. There is seldom any need to call the functionmakeNewData directly.
Value
A dataframe with one row for each session and group, and columns for thepredictors used byobject$model.
See Also
Examples
## from previously fitted modelmakeNewData(ipsecrdemo)Plot Detection Functions
Description
Plot detection functions using estimates of parameters in an ipsecr object.
Usage
## S3 method for class 'ipsecr'plot(x, newdata = NULL, add = FALSE, sigmatick = FALSE, rgr = FALSE, limits = FALSE, alpha = 0.05, xval = 0:200, ylim = NULL, xlab = NULL, ylab = NULL, ...)Arguments
x | an |
newdata | dataframe of data to form estimates |
add | logical to add curve(s) to an existing plot |
sigmatick | logical; if TRUE the scale parameter sigma is shown by a vertical line |
rgr | logical; if TRUE a scaled curve r.g(r) is plotted instead of g(r) |
limits | logical; if TRUE pointwise confidence limits are drawn |
alpha | alpha level for confidence intervals |
xval | vector of distances at for which detection to be plotted |
ylim | vector length 2 giving limits of y axis |
xlab | label for x axis |
ylab | label for y axis |
... | arguments to pass to |
Details
newdata is usually NULL, in which case one curve is plotted foreach session and group. Otherwise,predict.ipsecr is used to formestimates and plot a curve for each row innewdata.
If axis labels are not provided they default to ‘Distance (m)’ and ‘Detection probability’ or ‘Detection lambda’.
Approximate confidence limits for g(r) are calculated using a numericalfirst-order delta-method approximation to the standard error at eachxval. The distribution of g(r) is assumed to be normal on the logit scale for non-hazard functions (detectfn 0:13). For hazard detection functions (detectfn 14:18) the hazard is assumed (from version 3.1.1) to be distributed normally on the log scale. Limits are back-transformed to the probability scale g(r).
Value
plot.ipsecr invisibly returns a dataframe of the plotted values (ora list of dataframes in the case thatnewdata has more than onerow).
See Also
Detection functions,plot,ipsecr,detectfnplot
Examples
plot (ipsecrdemo, xval = 0:100, ylim = c(0, 0.4))Plot design and saved simulations for one box from a model fitted withipsecr.fit
Description
A 3-D depiction of the design (a box in parameter space) and the resulting simulations (in proxy space).
Usage
plot3D.IP(object, box = 1, oldplot = NULL, plotcentre = TRUE, plotfinal = FALSE, zkludge = -0.2)Arguments
object | ipsecr object from |
box | integer number of box to plot |
oldplot | list containing transofrmations and plot limits from a previous execution |
plotcentre | logical; if TRUE the centrepoint of the design box is plotted |
plotfinal | logical; if TRUE the final estimates are plotted as a point in parameter space |
zkludge | numeric adjustment for base value of z when plotfinal is TRUE |
Details
The function is restricted to single-session models with 3 real parameters.
A 2-panel plot is generated, so the graphics options should allow at least 2 panels (e.g.,par(mfrow = c(1,2)).
Parameters are plotted on the link scale.
The packageplot3D is used (Soetaert 2021).
Value
Invisibly returns a list comprising
pmatparm | pmat used byplot3D for parameter space |
pmatsim | pmat used byplot3D for proxy space |
pr | 2-row matrix with lower and upper plot limits of each parameter |
sr | 2-row matrix with lower and upper plot limits of each simulated proxy |
References
Soetaert, K. (2021). plot3D: Plotting Multi-Dimensional Data. R package version 1.4.https://CRAN.R-project.org/package=plot3D
See Also
Examples
if (requireNamespace("plot3D")) { par(mfrow = c(2,2), oma = c(1,1,3,1)) # plot first box, saving projection and limits for later use oldplot <- plot3D.IP(ipsecrdemo, box = 1) # plot second box, using projections and limits from first box plot3D.IP(ipsecrdemo, box = 2, oldplot, plotfinal = TRUE, zkludge = -0.1) mtext(outer = TRUE, side = 3, line = 0.5, adj = c(0.2,0.8), cex = 1.1, c('Parameter space', 'Proxy space'))}Simulate and plot the relationship between a parameter and its designated proxy
Description
As described in the vignette, each parameter is matched to a proxy value computed cheaply from the rawdata by the proxy function. This function provides a visual check on that relationship.
Usage
plotProxy(parameter = "sigma", proxyfn = proxy.ms, traps, mask, detectfn = "HHN", noccasions = 5, basepar = list(), xvals = NULL, nrepl = 100, add = FALSE, trend = TRUE, points = FALSE, boxplot = TRUE, boxplotargs = list(), link = "log", details = NULL, ...)Arguments
parameter | character parameter of interest |
proxyfn | function to compute vector of proxy values from a capthist object |
traps | traps object |
mask | habitat mask object |
detectfn | numeric or character code for detection function (seedetectfn) |
noccasions | integer number of sampling occasions |
basepar | named list with central values of parameters |
xvals | specified values of focal paramater to simulate (optional) |
nrepl | integer number of simulations |
add | logical; if TRUE any plot is added to an existing plot |
trend | logical; if TRUE a least-squares trend line is plotted |
points | logical; if TRUE each simulated value is plotted |
boxplot | logical; if TRUE a boxplots is plotted for each level of the focal parameter |
boxplotargs | list of arguments for |
link | character link function for transforming parameter x-axis |
details | not used |
... | other arguments passed to plot() |
Details
Simulation uses the internal functionssimpop andsimCH.
boxplotargs may be used to override or add to the arguments ofboxplot.
This version ofplotProxy() does not allow for interference (NT) and assumes a simple SECR model with only 3 or 4 coefficients corresponding to density D and the parameters of the detection model (lambda0 or g0, sigma and possibly z).
Matching of proxies at the level of ‘beta’ parameters may be enabled in a future version.
Value
The simulated proxy values are returned invisibly as a matrix (nrepl x nlevels).
See Also
Examples
# try with small number of replicatestrps <- traps(captdata)msk <- make.mask(trps, buffer = 100)base <- list(D = 5, lambda0 = 0.2, sigma = 25)out <- plotProxy (parameter = 'D', traps = trps, mask = msk, basepar = base, boxplotargs = list(col='orange'), nrepl = 20)SECR Model Predictions
Description
Evaluate a spatially explicit capture–recapture model. That is, compute the ‘real’ parameters corresponding to the ‘beta’ parameters of a fitted model for arbitrary levels of any variables in the linear predictor.
Usage
## S3 method for class 'ipsecr'predict(object, newdata = NULL, type = c("response", "link"), se.fit = TRUE, alpha = 0.05, savenew = FALSE, ...)Arguments
object |
|
newdata | optional dataframe of values at which to evaluate model |
type | character; type of prediction required. The default ("response") provides estimates of the ‘real’ parameters. |
se.fit | logical for whether output should include SE and confidence intervals |
alpha | alpha level for confidence intervals |
savenew | logical for whether newdata should be saved |
... | other arguments passed to |
Details
The variables in the various linear predictors are described insecr-models.pdf and listed for the particular model in thevars component ofobject.
Optionalnewdata should be a dataframe with a column for each ofthe variables in the model (see ‘vars’ component ofobject). Ifnewdata is missing then a dataframe is constructed automatically.
Defaultnewdata are for a naive animal on the first occasion;numeric covariates are set to zero and factor covariates to their base(first) level. The argument ‘all.levels’ may be passed tonewdata; if TRUE then the default newdata includes all factor levels.
realnames may be used to select a subset of parameters.
Standard errors for parameters on the response (real) scale are by thedelta method (Lebreton et al. 1992), and confidence intervals arebacktransformed from the link scale.
The value ofnewdata is optionally saved as an attribute.
Value
Whense.fit = FALSE, a dataframe identical tonewdata except for the addition of one column for each ‘real’ parameter. Otherwise, a list with one component for each row innewdata. Each component is a dataframe with one row for each ‘real’ parameter (density, g0, sigma, b) and columns as below
| link | link function |
| estimate | estimate of real parameter |
| SE.estimate | standard error of the estimate |
| lcl | lower 100(1--alpha)% confidence limit |
| ucl | upper 100(1--alpha)% confidence limit |
Whennewdata has only one row, the structure of the list is‘dissolved’ and the return value is one data frame.
Fordetectpar, a list with the estimated values of detectionparameters (e.g., g0 and sigma if detectfn = "halfnormal"). In the caseof multi-session data the result is a list of lists (one list persession).
Note
predictDsurface should be used for predicting density at manypoints from a model with spatial variation. This deals automaticallywith scaling of x- and y-coordinates, and is much faster thanpredict.ipsecr. The resulting Dsurface object has its own plot method.
The argument ‘scaled’ was removed from both predict methods in version 2.10 as the scaleg0 and scalesigma features had been superceded by other parameterisations.
References
Lebreton, J.-D., Burnham, K. P., Clobert, J. and Anderson, D. R. (1992) Modeling survival and testing biological hypotheses using marked animals: a unified approach with case studies.Ecological Monographs62, 67–118.
See Also
Examples
predict (ipsecrdemo)Print, Trim or Summarise ipsecr Object
Description
Print results from fitting a spatially explicit capture–recapture model orgenerate a list of summary values.
Usage
## S3 method for class 'ipsecr' print(x, newdata = NULL, alpha = 0.05, call = TRUE, ...)## S3 method for class 'ipsecr' summary(object, newdata = NULL, alpha = 0.05, ...)## S3 method for class 'ipsecr' trim(object, drop = c('call', 'proxyfn', 'mask', 'sim.lm'), keep = NULL)Arguments
x |
|
object |
|
newdata | optional dataframe of values at which to evaluate model |
alpha | alpha level |
call | logical; if TRUE the call is printed |
... | other arguments (not used) |
drop | character vector identifying components to be dropped |
keep | character vector identifying components to be kept |
Details
Results fromprint.ipsecr are potentially complex and depend upon the analysis (seebelow). Optionalnewdata should be a dataframe with a column foreach of the variables in the model. Ifnewdata is missing then adataframe is constructed automatically. Defaultnewdata are fora naive animal on the first occasion; numeric covariates are set to zeroand factor covariates to their base (first) level. Confidence intervalsare 100 (1 – alpha) % intervals.
| call | the function call (optional) |
| version,time | ipsecr version, date and time fitting started, and elapsed time |
| Detector type | `single', `multi', `proximity' etc. |
| Detector number | number of detectors |
| Average spacing | |
| x-range | |
| y-range | |
| New detector type | as fitted when details$newdetector specified |
| N animals | number of distinct animals detected |
| N detections | number of detections |
| N occasions | number of sampling occasions |
| Mask area | |
| Model | model formula for each `real' parameter |
| Fixed (real) | fixed real parameters |
| Detection fn | detection function type (halfnormal or hazard-rate) |
| Distribution | spatial model (details$distribution) |
| N parameters | number of parameters estimated |
| Design points | number of vertices and centre points |
| Simulations per box | total number |
| Beta parameters | coef of the fitted model, SE and confidence intervals |
| vcov | variance-covariance matrix of beta parameters |
| Real parameters | fitted (real) parameters evaluated at base levels of covariates |
Value
Thesummary method constructs a list of outputs similar to those printed by theprint method, but somewhat more concise and re-usable:
| versiontime | ipsecr version, and date and time fitting started |
| traps | detector summary |
| capthist | capthist summary |
| mask | mask summary |
| modeldetails | miscellaneous model characteristics |
| coef | table of fitted coefficients with CI |
| predicted | predicted values (`real' parameter estimates) |
See Also
Examples
## load & print previously fitted null (constant parameter) modelprint(ipsecrdemo)summary(ipsecrdemo)Variance - Covariance Matrix of SECR Parameters
Description
Variance-covariance matrix of beta or real parameters from fitted ipsecr model.
Usage
## S3 method for class 'ipsecr'vcov(object, realnames = NULL, newdata = NULL, byrow = FALSE, ...)Arguments
object | ipsecr object output from the function |
realnames | vector of character strings for names of ‘real’ parameters |
newdata | dataframe of predictor values |
byrow | logical for whether to compute covariances among ‘real’ parameters for each row of new data, or among rows for each real parameter |
... | other arguments (not used) |
Details
By default, returns the matrix of variances and covariances among theestimated model coefficients (beta parameters).
Ifrealnames andnewdata are specified, the result iseither a matrix of variances and covariances for each ‘real’ parameteramong the points in predictor-space given by the rows ofnewdataor among real parameters for each row ofnewdata. Failure tospecifynewdata results in a list of variances only.
Value
A matrix containing the variances and covariances among beta parameterson the respective link scales, or a list of among-parameter variance-covariancematrices, one for each row ofnewdata, or a list of among-row variance-covariancematrices, one for each ‘real’ parameter.
See Also
Examples
## previously fitted ipsecr modelvcov(ipsecrdemo)