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

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)

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 \times 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" or type="depDouble" 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.

Note

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

Value

an unmarkedMultFrame or unmarkedFrameGMM object

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

Set to "removal" for constant-interval removal sampling, "double" for standard double observer sampling, or "depDouble" for dependent 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

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)
#> Warning: yearlySiteCovs contains characters. Converting them to factors.

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")
#> Warning: yearlySiteCovs contains characters. Converting them to factors.


# 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
#>       [,1] [,2] [,3] [,4] [,5] [,6] [,7] [,8] [,9] [,10] [,11] [,12]
#>  [1,]    1    1    1    1    1    1    1    1    1     1     1     1
#>  [2,]    0    1    1    1    1    1    1    1    1     1     1     1
#>  [3,]    0    0    1    1    1    1    1    1    1     1     1     1
#>  [4,]    0    0    0    1    1    1    1    1    1     1     1     1
#>  [ reached getOption("max.print") -- omitted 8 rows ]


umfGMM2 <- unmarkedFrameGMM(y=y,
    siteCovs = data.frame(site=site),
    obsCovs=list(occasion=occasions),
    yearlySiteCovs=data.frame(year=c(t(years))),
    numPrimary=T, obsToY=o2y, piFun="instRemPiFun")
#> Warning: yearlySiteCovs contains characters. Converting them to factors.

str(umfGMM2)
#> Formal class 'unmarkedFrameGMM' [package "unmarked"] with 9 slots
#>   ..@ piFun         : chr "instRemPiFun"
#>   ..@ samplingMethod: chr "userDefined"
#>   ..@ numPrimary    : num 4
#>   ..@ yearlySiteCovs:'data.frame':	200 obs. of  1 variable:
#>   .. ..$ year: Factor w/ 4 levels "2010","2011",..: 1 2 3 4 1 2 3 4 1 2 ...
#>   ..@ y             : int [1:50, 1:12] 0 1 0 1 0 1 0 1 0 1 ...
#>   ..@ obsCovs       :'data.frame':	600 obs. of  1 variable:
#>   .. ..$ occasion: int [1:600] 1 2 3 4 5 6 7 8 9 10 ...
#>   ..@ siteCovs      :'data.frame':	50 obs. of  1 variable:
#>   .. ..$ site: int [1:50] 1 2 3 4 5 6 7 8 9 10 ...
#>   ..@ mapInfo       : NULL
#>   ..@ obsToY        : num [1:12, 1:12] 1 0 0 0 0 0 0 0 0 0 ...