unmarkedMultFrame {unmarked} | R Documentation

## Create an unmarkedMultFrame, unmarkedFrameGMM, unmarkedFrameGDS, or unmarkedFrameGPC object

### Description

These functions construct unmarkedFrames for data collected during primary and secondary sampling periods.

### Usage

      unmarkedMultFrame(y, siteCovs, obsCovs, numPrimary, yearlySiteCovs)
      unmarkedFrameGMM(y, siteCovs, obsCovs, numPrimary, yearlySiteCovs, type,
        obsToY, piFun)
      unmarkedFrameGDS(y, siteCovs, numPrimary, yearlySiteCovs, dist.breaks,
        survey, unitsIn, tlength)
      unmarkedFrameGPC(y, siteCovs, obsCovs, numPrimary, yearlySiteCovs)

### Arguments

`y` | A matrix of the observed data.
`siteCovs` | Data frame of covariates that vary at the site level.
`obsCovs` | Data frame of covariates that vary within site-year-observation level.
`numPrimary` | Number of primary time periods (seasons in the multiseason model).
`yearlySiteCovs` | Data frame containing covariates at the site-year level.
`type` | Either "removal" or "double" for constant-interval removal sampling or double observer sampling. This should be not be specified for other types of survey designs.
`obsToY` | A matrix specifying relationship between observation-level covariates and response matrix
`piFun` | A function converting an MxJ matrix of detection probabilities into an MxJ matrix of multinomial cell probabilities.
`dist.breaks` | see `unmarkedFrameDS`
`survey` | see `unmarkedFrameDS`
`unitsIn` | see `unmarkedFrameDS`
`tlength` | see `unmarkedFrameDS`

### Details

unmarkedMultFrame objects are used by `colext`.

unmarkedFrameGMM objects are used by `gmultmix`.

unmarkedFrameGDS objects are used by `gdistsamp`.

unmarkedFrameGPC objects are used by `gpcount`.

For a study with M sites, T years, and a maximum of J observations per site-year, the data can be supplied in a variety of ways but are stored as follows. `y` is an M by TJ matrix, with each row corresponding to a site. `siteCovs` is a data frame with M rows. `yearlySiteCovs` is a data frame with MT rows which are in site-major, year-minor order. `obsCovs` is a data frame with MTJ rows, which are ordered by site-year-observation, so that a column of `obsCovs` corresponds to `as.vector(t(y))`, element-by-element. The number of years must be specified in `numPrimary`.

If the data are in long format, the convenience function `formatMult` is useful for creating the unmarkedMultFrame.

unmarkedFrameGMM and unmarkedFrameGDS are superclasses of unmarkedMultFrame containing information on the survey design used that resulted in multinomial outcomes. For unmarkedFrameGMM and constant-interval removal sampling, you can set type="removal" and ignore the arguments obsToY and piFun. Similarly, for double-observer sampling, setting type="double" will automatically create an appropiate obsToY matrix and `piFuns`. For all other situations, the type argument of unmarkedFrameGMM should be ignored and the obsToY and piFun arguments must be specified. piFun must be a function that converts an MxJ matrix of detection probabilities into an MxJ matrix of multinomial cell probabilities. obsToY is a matrix describing how the obsCovs relate to the observed counts y. For further discussion and examples see the help page for `multinomPois` and `piFuns`.

unmarkedFrameGMM and unmarkedFrameGDS objects can be created from an unmarkedMultFrame using the "as" conversion method. See examples.

### Value

an unmarkedMultFrame or unmarkedFrameGMM object

### Note

Data used with colext, gmultmix, and gdistsamp may be collected during a single year, so yearlySiteCovs may be a misnomer is some cases.

### See Also

`formatMult`, `colext`, `gmultmix`, `gpcount`

### Examples

    n <- 50   # number of sites
    T <- 4    # number of primary periods
    J <- 3    # number of secondary periods

    site <- 1:50
    years <- data.frame(matrix(rep(2010:2013, each=n), n, T))
    years <- data.frame(lapply(years, as.factor))
    occasions <- data.frame(matrix(rep(1:(J*T), each=n), n, J*T))

    y <- matrix(0:1, n, J*T)

    umf <- unmarkedMultFrame(y=y,
        siteCovs = data.frame(site=site),
        obsCovs=list(occasion=occasions),
        yearlySiteCovs=list(year=years),
        numPrimary=T)

    umfGMM1 <- unmarkedFrameGMM(y=y,
        siteCovs = data.frame(site=site),
        obsCovs=list(occasion=occasions),
        yearlySiteCovs=data.frame(year=c(t(years))),
        # or: yearlySiteCovs=list(year=years),
        numPrimary=T, type="removal")

    # A user-defined piFun calculating removal probs when time intervals differ.
    instRemPiFun <- function(p) {
    	M <- nrow(p)
    	J <- ncol(p)
    	pi <- matrix(NA, M, J)
    	p[,1] <- pi[,1] <- 1 - (1 - p[,1])^2
    	p[,2] <- 1 - (1 - p[,2])^3
    	p[,3] <- 1 - (1 - p[,3])^5
    	for(i in 2:J) {
    		pi[,i] <- pi[, i - 1]/p[, i - 1] * (1 - p[, i - 1]) * p[, i]
    		}
    	return(pi)
    	}

    # Associated obsToY matrix required by unmarkedFrameMPois
    o2y <- diag(ncol(y))
    o2y[upper.tri(o2y)] <- 1
    o2y

    umfGMM2 <- unmarkedFrameGMM(y=y,
        siteCovs = data.frame(site=site),
        obsCovs=list(occasion=occasions),
        yearlySiteCovs=data.frame(year=years),
        numPrimary=T, obsToY=o2y, piFun="instRemPiFun")

    str(umfGMM2)

[Package unmarked version 0.12-3 Index]