Package 'jointNmix' reference manual

Title:	Joint N-Mixture Models for Site-Associated Species
Description:	Fits univariate and joint N-mixture models for data on two unmarked site-associated species. Includes functions to estimate latent abundances through empirical Bayes methods.
Authors:	Rafael de Andrade Moral [aut, cre], Clarice Garcia Borges Demetrio [aut], John Hinde [aut]
Maintainer:	Rafael de Andrade Moral <[email protected]>
License:	GPL (>= 2)
Version:	1.0
Built:	2024-11-16 06:37:06 UTC
Source:	CRAN

Joint N-Mixture Models for Site-Associated Species

Description

Fits univariate and joint N-mixture models for data on two unmarked site-associated species. Includes functions to estimate latent abundances through empirical Bayes methods.

Details

The DESCRIPTION file:

Package:	jointNmix
Type:	Package
Title:	Joint N-Mixture Models for Site-Associated Species
Version:	1.0
Date:	2016-10-04
Authors@R:	c(person("Rafael", "de Andrade Moral", role = c("aut", "cre"), email = "[email protected]"), person("Clarice", "Garcia Borges Demetrio", role = "aut"), person("John", "Hinde", role = "aut"))
Author:	Rafael de Andrade Moral [aut, cre], Clarice Garcia Borges Demetrio [aut], John Hinde [aut]
Maintainer:	Rafael de Andrade Moral <[email protected]>
Depends:	R (>= 3.0.0), methods, graphics, stats
Description:	Fits univariate and joint N-mixture models for data on two unmarked site-associated species. Includes functions to estimate latent abundances through empirical Bayes methods.
License:	GPL (>= 2)
NeedsCompilation:	no
Packaged:	2016-10-05 13:55:56 UTC; rafael
Repository:	CRAN
Date/Publication:	2016-11-12 00:38:21

Index of help topics:

AIC.Nmix                Methods for Nmix objects
Nmix                    Univariate N-mixture models
dneymanA                The Neyman-A probability function
fitted.jointNmix        Methods for joint Nmix objects
fitted.uniNmix          Methods for univariate Nmix objects
getcorr.jointNmix       Extract correlations and covariances
getranef.uniNmix        Get empirical Bayes predictions of the latent
                        abundances
jointNmix               Joint N-mixture models
jointNmix-package       Joint N-Mixture Models for Site-Associated
                        Species
plot.uniNmix            Plot Methods for Nmix objects

Author(s)

Rafael de Andrade Moral [aut, cre], Clarice Garcia Borges Demetrio [aut], John Hinde [aut]

Maintainer: Rafael de Andrade Moral <[email protected]>

References

Moral, R.A., Hinde, J., Demétrio, C.G.B., Reigada, C. and Godoy, W.A.C. (submitted) Models for jointly estimating abundance of two unmarked site-associated species subject to imperfect detection.

Get empirical Bayes predictions of the latent abundances

Description

Computes the conditional abundance distribution given the data and model estimates

Usage

getranef.uniNmix(obj, distr = FALSE)
getranef.jointNmix(obj, distr = FALSE)
getranef.uniNmix(obj, distr = FALSE)
getranef.jointNmix(obj, distr = FALSE)

Arguments

`obj`	fitted model object
`distr`	logical. If TRUE, returns the matrix of conditional probabilities. If FALSE, returns the expected values of the conditional distributions, i.e. the abundance estimates

Details

These functions returnt the empirical Bayes estimates of the latent abundances from univariate and joint N-mixture models, as described by Royle (2004) and Moral et al. (submitted), respectively.

Author(s)

Rafael A. Moral <[email protected]>, Clarice G. B. Demétrio and John Hinde

References

Royle, J.A. (2004) Models for estimating population size from spatially replicated counts. Biometrics 60:108-105.

Moral, R.A., Hinde, J., Demétrio, C.G.B., Reigada, C. and Godoy, W.A.C. (submitted) Models for jointly estimating abundance of two unmarked site-associated species subject to imperfect detection.

Extract correlations and covariances

Description

Extract estimated correlations and covariances between observed abundances for joint N-mixture models

Usage

getcorr.jointNmix(obj)
getcov.jointNmix(obj)
getcorr.jointNmix(obj)
getcov.jointNmix(obj)

Arguments

obj

fitted model object

Details

The correlations under each specification of the latent abundance distributions are displayed in Moral et al. (submitted)'s Table 1. The covariances are derived as Supplementary information.

Author(s)

Rafael A. Moral <[email protected]>, Clarice G. B. Demétrio and John Hinde

References

Moral, R.A., Hinde, J., Demétrio, C.G.B., Reigada, C. and Godoy, W.A.C. (submitted) Models for jointly estimating abundance of two unmarked site-associated species subject to imperfect detection.

The Neyman-A probability function

Description

Computes the probability function of the Neyman-A distribution

Usage

dneymanA(x, lambda1, lambda2, K, log = FALSE)
dneymanA(x, lambda1, lambda2, K, log = FALSE)

Arguments

`x`	vector of values
`lambda1`, `lambda2`	parameters of the distribution
`K`	truncation value for the infinite summation
`log`	logical. If TRUE, the logarithm of the probabilities is returned

Details

The Neyman-A distribution has probability function

$\frac{e^{-\lambda_1}\lambda_2^{x}}{x!}\sum_{k=0}^\infty\frac{(\lambda_1e^{-\lambda_2})^kk^x}{k!}$

and is an overdispersion model. The summation is truncated to K.

Author(s)

Rafael A. Moral <[email protected]>, Clarice G. B. Demétrio and John Hinde

Examples

x <- 0:10
dneymanA(x, lambda1 = 2, lambda2 = 1.5, K = 50)
x <- 0:10
dneymanA(x, lambda1 = 2, lambda2 = 1.5, K = 50)

Joint N-mixture models

Description

Fits joint N-mixture models for site-associated species

Usage

jointNmix(sp1, sp2, start, method = "BFGS", K, mixture = c("P", "P"), 
          Xp1, Xp2, Xl1, Xl2, Xpsi, includepsi = TRUE)
jointNmix(sp1, sp2, start, method = "BFGS", K, mixture = c("P", "P"), 
          Xp1, Xp2, Xl1, Xl2, Xpsi, includepsi = TRUE)

Arguments

`sp1`	observation matrix for species 1
`sp2`	observation matrix for species 2
`start`	initial values for the optimization process
`method`	optimization method passed to `optim`. Defaults to `"BFGS"`
`K`	truncation number of the infinite summations in the log-likelihood. Defaults to `max(sp1, sp2) + 100`
`mixture`	two-character vector for latent abundance distributions. `"P"` for Poisson and `"NB"` for negative binomial. Defaults to `c("P","P")`
`Xp1`	model matrix for detection probabilities of species 1
`Xp2`	model matrix for detection probabilities of species 2
`Xl1`	model matrix for abundance of species 1
`Xl2`	model matrix for linking parameter of species 2
`Xpsi`	model matrix for abundance of species 2
`includepsi`	logical. If FALSE, psi is not estimated and set to zero

Details

The function fits a bivariate extension to Royle's (2004) N-mixture model to data on the abundance of two species collected at R sites over T time occasions. The model for observation on site i at time t for species 1 can be specified as

$Y_{1it}|N_{1i} ~ Bin(N_{1i},p_{1it})$

$N_{1i} ~ a count distribution with mean \lambda_{1i}.$

The model for species 2 is

$Y_{2it}|N_{1i},N_{2i} ~ Bin(N_{2i},p_{2it})$

$N_{2i}|N_{1i} ~ a count distribution with mean \psi+\lambda_{2i}N_{1i}.$

Here, users may define a Poisson or negative binomial distribution for the latent abundances N_1i and N_2i.

Value

An object of class jointNmix and Nmix, for which many methods are available (see methods(class = "jointNmix") and methods(class = "Nmix"))

Author(s)

Rafael A. Moral <[email protected]>, Clarice G. B. Demétrio and John Hinde

References

Moral, R.A., Hinde, J., Demétrio, C.G.B., Reigada, C. and Godoy, W.A.C. (submitted) Models for jointly estimating abundance of two unmarked site-associated species subject to imperfect detection.

Examples

## simulating data with poisson latent abundances
R <- 10 # sites
T <- 10 # time occasions
lambda1 <- 5
psi <- 3
p1 <- .3
p2 <- .6
lambda2 <- .5
set.seed(1234); N1 <- rpois(R, lambda1)
set.seed(1234); N2 <- rpois(R, psi + lambda2*N1)
y1 <- y2 <- matrix(0, ncol=T, nrow=R)
set.seed(1234); for(i in 1:R) y1[,i] <- rbinom(T, N1, p1)
set.seed(1234); for(i in 1:R) y2[,i] <- rbinom(T, N2, p2)

Xp <- cbind(rep(1, R*T))
Xl <- cbind(rep(1, R))

## Not run: 
## fitting the Poisson-Poisson joint N-mixture model
fitpp <- jointNmix(y1, y2, Xp1=Xp, Xp2=Xp, Xl1=Xl, Xl2=Xl, mixture=c("P","P"), K=30)

## fitting the negbin-Poisson joint N-mixture model
fitnbp <- jointNmix(y1, y2, Xp1=Xp, Xp2=Xp, Xl1=Xl, Xl2=Xl, mixture=c("NB","P"), K=30)

## likelihood-ratio test between P-P and NB-P models
anova(fitpp, fitnbp)

## comparing using AIC
lapply(list(fitpp, fitnbp), AIC)

## conditional posterior probability functions for abundances
plot(fitpp, posterior = TRUE)

## estimated abundances vs. true abundances
data.frame(getranef.jointNmix(fitpp), N1, N2)
  
## End(Not run)
## simulating data with poisson latent abundances
R <- 10 # sites
T <- 10 # time occasions
lambda1 <- 5
psi <- 3
p1 <- .3
p2 <- .6
lambda2 <- .5
set.seed(1234); N1 <- rpois(R, lambda1)
set.seed(1234); N2 <- rpois(R, psi + lambda2*N1)
y1 <- y2 <- matrix(0, ncol=T, nrow=R)
set.seed(1234); for(i in 1:R) y1[,i] <- rbinom(T, N1, p1)
set.seed(1234); for(i in 1:R) y2[,i] <- rbinom(T, N2, p2)

Xp <- cbind(rep(1, R*T))
Xl <- cbind(rep(1, R))

## Not run: 
## fitting the Poisson-Poisson joint N-mixture model
fitpp <- jointNmix(y1, y2, Xp1=Xp, Xp2=Xp, Xl1=Xl, Xl2=Xl, mixture=c("P","P"), K=30)

## fitting the negbin-Poisson joint N-mixture model
fitnbp <- jointNmix(y1, y2, Xp1=Xp, Xp2=Xp, Xl1=Xl, Xl2=Xl, mixture=c("NB","P"), K=30)

## likelihood-ratio test between P-P and NB-P models
anova(fitpp, fitnbp)

## comparing using AIC
lapply(list(fitpp, fitnbp), AIC)

## conditional posterior probability functions for abundances
plot(fitpp, posterior = TRUE)

## estimated abundances vs. true abundances
data.frame(getranef.jointNmix(fitpp), N1, N2)
  
## End(Not run)

Methods for joint Nmix objects

Description

Fitted values, residual extraction, simulation and print method for joint N-mixture models

Usage

## S3 method for class 'jointNmix'
fitted(object, ...)
## S3 method for class 'jointNmix'
print(x, round = TRUE, ...)
## S3 method for class 'jointNmix'
residuals(object, type = c("ordinary", "standardized"), ...)
## S3 method for class 'jointNmix'
simulate(object, ...)
## S3 method for class 'jointNmix'
fitted(object, ...)
## S3 method for class 'jointNmix'
print(x, round = TRUE, ...)
## S3 method for class 'jointNmix'
residuals(object, type = c("ordinary", "standardized"), ...)
## S3 method for class 'jointNmix'
simulate(object, ...)

Arguments

`object`, `x`	fitted model object
`round`	logical. Round the estimates?
`type`	type of residuals to be returned. May be ordinary or standardized
`...`	not used

Details

fitted.uniNmix prints the fitted values for the model fit; residuals.uniNmix returns the ordinary (

$r_i^o=y_i-\hat{\mu}_i$

) or standardized (

$r_i^s=\frac{y_i-\hat{\mu}_i}{\mbox{Var}(Y_i)}$

) residuals; simulate.uniNmix simulates one sample from the fitted model.

Author(s)

Rafael A. Moral <[email protected]>, Clarice G. B. Demétrio and John Hinde

References

Moral, R.A., Hinde, J., Demétrio, C.G.B., Reigada, C. and Godoy, W.A.C. (submitted) Models for jointly estimating abundance of two unmarked site-associated species subject to imperfect detection.

Univariate N-mixture models

Description

Fits univariate N-mixture models

Usage

Nmix(sp1, start, method = "BFGS", K, mixture, Xp, Xl)
Nmix(sp1, start, method = "BFGS", K, mixture, Xp, Xl)

Arguments

`sp1`	observation matrix for the species
`start`	initial values for the optimization process
`method`	optimization method passed to `optim`. Defaults to `"BFGS"`
`K`	truncation number of the infinite summations in the log-likelihood. Defaults to `max(sp1, sp2) + 100`
`mixture`	latent abundance distribution specification. `"P"` for Poisson, `"NB"` for negative binomial and `"NeymanA"` for Neyman-A distributions are available. Defaults to `"P"`
`Xp`	model matrix for detection probabilities
`Xl`	model matrix for abundance parameter

Details

The function fits Royle's (2004) N-mixture model to data on species abundance collected at R sites over T time occasions. The model for observation on site i at time t can be specified as

$Y_{it}|N_i ~ Bin(N_i,p_{it})$

$N_i ~ a count distribution with mean \lambda_i.$

Here, users may define a Poisson, negative binomial or Neyman-A distributions for the latent abundances N_i.

Value

An object of class uniNmix and Nmix, for which many methods are available (see methods(class = "uniNmix") and methods(class = "Nmix"))

Author(s)

Rafael A. Moral <[email protected]>, Clarice G. B. Demétrio and John Hinde

References

Royle, J.A. (2004) Models for estimating population size from spatially replicated counts. Biometrics 60:108-105.

Examples

## simulating data with negative binomial latent abundances
R <- 10 # sites
T <- 10 # time occasions
lambda <- 5 # abundance parameter
p <- .3 # probability of detection
phi <- 1 # dispersion parameter
set.seed(1234); Ni <- rnbinom(R, mu=lambda, size=phi) # latent abundances
y <- matrix(0, ncol=T, nrow=R)
set.seed(1234); for(i in 1:R) y[,i] <- rbinom(T, Ni, p) # observed abundances

## fitting the Poisson N-mixture model
fitp <- Nmix(y, Xp=cbind(rep(1, R*T)), Xl=cbind(rep(1, R)), mixture="P", K=25)

## fitting the negative binomial N-mixture model
fitnb <- Nmix(y, Xp=cbind(rep(1, R*T)), Xl=cbind(rep(1, R)), mixture="NB", K=25)

## fitting the Neyman-A N-mixture model
fitna <- Nmix(y, Xp=cbind(rep(1, R*T)), Xl=cbind(rep(1, R)), mixture="NeymanA", K=25)

## likelihood-ratio test between Poisson and negbin models
anova(fitp, fitnb)

## comparing using AIC
lapply(list(fitp, fitnb, fitna), AIC)

## conditional posterior probability functions for abundances
plot(fitnb, posterior = TRUE)

## estimated abundances vs. true abundances
data.frame(getranef.uniNmix(fitnb), Ni)
## simulating data with negative binomial latent abundances
R <- 10 # sites
T <- 10 # time occasions
lambda <- 5 # abundance parameter
p <- .3 # probability of detection
phi <- 1 # dispersion parameter
set.seed(1234); Ni <- rnbinom(R, mu=lambda, size=phi) # latent abundances
y <- matrix(0, ncol=T, nrow=R)
set.seed(1234); for(i in 1:R) y[,i] <- rbinom(T, Ni, p) # observed abundances

## fitting the Poisson N-mixture model
fitp <- Nmix(y, Xp=cbind(rep(1, R*T)), Xl=cbind(rep(1, R)), mixture="P", K=25)

## fitting the negative binomial N-mixture model
fitnb <- Nmix(y, Xp=cbind(rep(1, R*T)), Xl=cbind(rep(1, R)), mixture="NB", K=25)

## fitting the Neyman-A N-mixture model
fitna <- Nmix(y, Xp=cbind(rep(1, R*T)), Xl=cbind(rep(1, R)), mixture="NeymanA", K=25)

## likelihood-ratio test between Poisson and negbin models
anova(fitp, fitnb)

## comparing using AIC
lapply(list(fitp, fitnb, fitna), AIC)

## conditional posterior probability functions for abundances
plot(fitnb, posterior = TRUE)

## estimated abundances vs. true abundances
data.frame(getranef.uniNmix(fitnb), Ni)

Methods for Nmix objects

Description

AIC, anova, coef, and logLik methods for univariate and joint N-mixture models

Usage

## S3 method for class 'Nmix'
AIC(object, ...)
## S3 method for class 'Nmix'
anova(object, object2, ...)
## S3 method for class 'Nmix'
coef(object, ...)
## S3 method for class 'Nmix'
logLik(object, ...)
## S3 method for class 'Nmix'
AIC(object, ...)
## S3 method for class 'Nmix'
anova(object, object2, ...)
## S3 method for class 'Nmix'
coef(object, ...)
## S3 method for class 'Nmix'
logLik(object, ...)

Arguments

`object`	fitted model object
`object2`	second model object for the `anova` method
`...`	not used

Details

AIC.Nmix provides the Akaike Information Criterion for the model fit; anova.Nmix performs a likelihood-ratio test between two nested model fits; coef.Nmix prints the estimates of the model fit; logLik.Nmix prints the log-likelihood of the model fit.

Author(s)

Rafael A. Moral <[email protected]>, Clarice G. B. Demétrio and John Hinde

Plot Methods for Nmix objects

Description

Plots residuals vs. fitted values or the conditional distributions of the abundances for each site

Usage

## S3 method for class 'uniNmix'
plot(x, posterior = FALSE, layout, sites, restype, ...)
## S3 method for class 'jointNmix'
plot(x, posterior = FALSE, layout, sites, restype, ...)
## S3 method for class 'uniNmix'
plot(x, posterior = FALSE, layout, sites, restype, ...)
## S3 method for class 'jointNmix'
plot(x, posterior = FALSE, layout, sites, restype, ...)

Arguments

`x`	fitted model object
`posterior`	logical. If TRUE, plots the conditional distributions of the abundances. If FALSE, plots residuals vs. fitted values
`layout`	two-number vector indicating the partition of the graphical window in rows and columns, respectively
`sites`	index of sites to plot the conditional distribution of the abundances. If left unspecified, all sites are plotted
`restype`	type of residuals to be plotted. Defaults to "ordinary"
`...`	not used

Author(s)

Rafael A. Moral <[email protected]>, Clarice G. B. Demétrio and John Hinde

References

Moral, R.A., Hinde, J., Demétrio, C.G.B., Reigada, C. and Godoy, W.A.C. (submitted) Models for jointly estimating abundance of two unmarked site-associated species subject to imperfect detection.

Methods for univariate Nmix objects

Description

Fitted values, residual extraction, simulation and print method for univariate N-mixture models

Usage

## S3 method for class 'uniNmix'
fitted(object, ...)
## S3 method for class 'uniNmix'
print(x, round = TRUE, ...)
## S3 method for class 'uniNmix'
residuals(object, type = c("ordinary", "standardized"), ...)
## S3 method for class 'uniNmix'
simulate(object, ...)
## S3 method for class 'uniNmix'
fitted(object, ...)
## S3 method for class 'uniNmix'
print(x, round = TRUE, ...)
## S3 method for class 'uniNmix'
residuals(object, type = c("ordinary", "standardized"), ...)
## S3 method for class 'uniNmix'
simulate(object, ...)

Arguments

`object`, `x`	fitted model object
`round`	logical. Round the estimates?
`type`	type of residuals to be returned. May be ordinary or standardized
`...`	not used

Details

fitted.uniNmix prints the fitted values for the model fit; residuals.uniNmix returns the ordinary (

$r_i^o=y_i-\hat{\mu}_i$

) or standardized (

$r_i^s=\frac{y_i-\hat{\mu}_i}{\mbox{Var}(Y_i)}$

) residuals; simulate.uniNmix simulates one sample from the fitted model.

Author(s)

Rafael A. Moral <[email protected]>, Clarice G. B. Demétrio and John Hinde

Package 'jointNmix'

Help Index

Joint N-Mixture Models for Site-Associated Species

Description

Details

Author(s)

References

Get empirical Bayes predictions of the latent abundances

Description

Usage

Arguments

Details

Author(s)

References

See Also

Extract correlations and covariances

Description

Usage

Arguments

Details

Author(s)

References

See Also

The Neyman-A probability function

Description

Usage

Arguments

Details

Author(s)

Examples

Joint N-mixture models

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Examples

Methods for joint Nmix objects

Description

Usage

Arguments

Details

Author(s)

References

See Also

Univariate N-mixture models

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Examples

Methods for Nmix objects

Description

Usage

Arguments

Details

Author(s)

See Also

Plot Methods for Nmix objects

Description

Usage

Arguments

Author(s)

References

See Also

Methods for univariate Nmix objects

Description

Usage

Arguments

Details

Author(s)

See Also