secr.design.MS {secr} | R Documentation

## Construct Detection Model Design Matrices and Lookups

### Description

Internal functions used by `secr.fit`.

### Usage

    secr.design.MS (capthist, models, timecov = NULL, sessioncov = NULL,
        groups = NULL, hcov = NULL, dframe = NULL, naive = FALSE, bygroup = FALSE,
        keep.dframe = FALSE, full.dframe = FALSE, ignoreusage = FALSE, contrasts = NULL, ...)

    make.lookup (tempmat)

    insertdim (x, dimx, dims)

### Arguments

`capthist` | `capthist` object
`models` | list of formulae for parameters of detection
`timecov` | optional dataframe of values of time (occasion-specific) covariate(s).
`sessioncov` | optional dataframe of values of session-specific covariate(s).
`groups` | optional vector of one or more variables with which to form groups. Each element should be the name of a factor variable in the `covariates` attribute of `capthist`.
`hcov` | character name of an individual (capthist) covariate for known class membership in h2 models
`dframe` | optional data frame of design data for detection parameters
`naive` | logical if TRUE then modelled detection probability is for a naive animal (not caught previously); if FALSE then detection probability is contingent on individual's history of detection
`bygroup` | logical if TRUE then the individual dimension of the parameter matrix is automatically collapsed to one row per group; if FALSE then the full dimensionality is retained (one row per individual)
`keep.dframe` | logical; if TRUE the dataframe of design data is included in the output
`full.dframe` | logical; if FALSE then padding rows are purged from output dframe (ignored if `keep.dframe = FALSE`)
`ignoreusage` | logical; if TRUE any usage attribute of traps(capthist) is ignored
`contrasts` | contrast specification as for `model.matrix`
`...` | other arguments passed to the R function `model.matrix`
`tempmat` | matrix for which row lookup required
`x` | vector of character, numeric or factor values
`dimx` | vector of notional dimensions for x to fill in target array
`dims` | vector of notional dimensions of target array

### Details

This is an internal secr function that you are unlikely ever to use. ... may be used to pass `contrasts.arg` to `model.matrix`.

Each real parameter is notionally different for each unique combination of session, individual, occasion, detector and latent class, i.e., for R sessions, n individuals, S occasions and K detectors there are potentially R x n x S x K x M different values. Actual models always predict a much reduced set of distinct values, and the number of rows in the design matrix is reduced correspondingly; a parameter index array allows these to retrieved for any combination of session, individual, occasion and detector.

The `keep.dframe` option is provided for the rare occasions that a user may want to check the data frame that is an intermediate step in computing each design matrix with `model.matrix` (i.e. the data argument of `model.matrix`).

### Value

For `secr.design.MS`, a list with the components

`designMatrices` | list of reduced design matrices, one for each real detection parameter
`parameterTable` | index to row of the reduced design matrix for each real detection parameter; dim(parameterTable) = c(uniquepar, np), where uniquepar is the number of unique combinations of paramater values (uniquepar < RnSKM) and np is the number of parameters in the detection model.
`PIA` | Parameter Index Array - index to row of parameterTable for a given session, animal, occasion and detector; dim(PIA) = c(R,n,S,K,M)
`R` | number of sessions

If `models` is empty then all components are NULL except for PIA which is an array of 1's (M set to 1).

Optionally (`keep.dframe = TRUE`) -

`dframe` | dataframe of design data, one column per covariate, one row for each c(R,n,S,K,M). For multi-session models n, S, and K refer to the maximum across sessions
`validdim` | list giving the valid dimensions (n, S, K, M) before padding

For `make.lookup`, a list with components

`lookup` | matrix of unique rows
`index` | indices in lookup of the original rows

For `insertdim`, a vector with length prod(dims) containing the values replicated according to dimx.

### See Also

`D.designdata`, `model.matrix`

### Examples

    secr.design.MS (captdata, models = list(g0 = ~b))$designMatrices
    secr.design.MS (captdata, models = list(g0 = ~b))$parameterTable

    ## peek at design data constructed for learned response model
    head(captdata)
    temp <- secr.design.MS (captdata, models = list(g0 = ~b),
        keep.dframe = TRUE)
    a1 <- temp$dframe$animal == 1 &  temp$dframe$detector %in% 8:10
    temp$dframe[a1,]

    ## ... and trap specific learned response model
    temp <- secr.design.MS (captdata, models = list(g0 = ~bk),
        keep.dframe = TRUE)
    a1 <- temp$dframe$animal == 1 &  temp$dframe$detector %in% 8:10
    temp$dframe[a1,]

    ## place values 1:6 in different dimensions
    insertdim(1:6, 1:2, c(2,3,6))
    insertdim(1:6, 3, c(2,3,6))

[Package secr version 3.2.1 Index]