mastif {mastif}

Gibbs sampler for mast data

Description

Estimates productivity and dispersion of seeds observed at seed traps, using information on locations, and covariates that could explain source strength. Data can be simulated with mastSim.

Usage

  mastif( inputs, formulaFec = NULL, formulaRep = as.formula("~diam"), 
           ng = NULL, burnin = NULL )
  
  ## S3 method for class 'mastif'
print(x, ...)
  
  ## S3 method for class 'mastif'
summary(object, verbose = TRUE, latex = FALSE, ...)

Arguments

inputs

list that must include two character vectors, (specNames, seedNames) and four data.frames (treeData, seedData, xytree, xytrap). See details.

formulaFec

R formula for fecundity model, e.g., ~ diam + x1.

formulaRep

R formula for maturation model, e.g., ~ diam.

ng

numeric number of Gibbs steps.

burnin

numeric number of burnin steps, before predictions are saved.

object

currently, also an object of class mastif.

verbose

if TRUE summary sent to screen.

latex

if TRUE tables written to screen in latex format.

x

object of class mastif.

...

further arguments not used here.

Details

inputs includes the following:

specNames is a character vector containing names of species, specNames, that appear in the treeData$species column.

seedNames is a character vector of seed types that appear as column names in seedData.

treeData is a data.frame holding tree information, including predictors and tree-year identification. Required columns are plot, tree, species, year, diam, and any other predictors for fecundity or maturation.

seedData is a data.frame holding seed counts with seed trap and year identification. Required columns are plot, trap, year, and seedNames, the latter holding seed counts.

xytree is a data.frame holding tree locations. Required columns are plot, tree, x, and y.

xytrap is data.frame holding seed trap locations. Required columns are plot, trap, x, and y.

formulaFec and formulaRep specify the models for plant fecundity and maturation. Variables listed in formulas appear as column headings in treeData. Note that formulaFec and formulaRep begin with ~, not y ~. The response matrix is constructed from seed types in seedData.

The treeData$tree column has values that are unique for a tree within a plot. These reference the same unique identifiers in xytree$tree. In addition to these identifiers, the data.frame xytree holds columns x and y for map locations.

The character vector seedNames holds the names of columns in seedData for seed counts. The elements of seedNames are seed types produced by one or more of the species in specNames. seedData must also include columns for trap, plot, and year, which link with columns in xytrap, which additionally includes columns x and y.

predList includes the names of plots and years to be predicted. It can include a numeric value mapMeters for the distance between lattice points in the prediction grid. See examples.

yearEffect is a list indicating the column names in treeData for random groups in year effects or AR(p) models. See examples.

randomEffect is a list indicating the column names in treeData for random groups in fecundity estimates, the character randGroups and the formulaRan for random effects. The formulaRan must be a subset of predictors from formulaFec. See examples.

modelYears is a numeric vector of years to include in the analysis.

ng is the number of Gibbs steps. burnin is the number of initial steps, must be less than ng.

Additional arguments to inputs can include prior parameters; default values are:

priorDist = 10 is a prior mean dispersal distance in meters.

priorVDist = 1 is the prior variance on mean dispersal distance in meters.

minDist = 2 and maxDist = 60 are the minimum and maximum values for the mean dispersal kernel in meters.

minDiam = 2 is the minimum diameter that a tree could be reproductively mature, in cm.

sigmaMu = .5 and sigmaWt = nrow(inputs$treeData) are the prior mean and the prior weight on log fecundity variance.

maxF = 1e+8, maximum fecundity, helps stabilize analysis of especially noisy data.

More detailed vignettes can be obtained with:

browseVignettes('mastif')

Value

Returns an object of class "mast", which is a list containing the following components:

inputs

list includes all inputs to the model, including transformations not resulting from posterior simulation.

chains

list of MCMC matrices, each with ng rows, includes:

bfec: fecundity coefficients

brep: maturation coefficients

ugibbs: dispersal parameters

sgibbs: residual variance and, after burnin, rmspe (root mean square prediction error)

rgibbs: if multiple seed types, then rows are the specNames to seedNames matrix R.

bygibbsF, bygibbsR: if yearEffects are included in the model, these are fixed year/lag and random year/lag effects by random group.

agibbs: if randomEffects on individuals, rows are covariance matrix.

parameters

list of parameter estimates summarized from chains.

acfMat: autocorrelation on fecundity by random group.

betaFec: fecundity regression coefficients (log scale).

betaRep: maturation regression coefficients (probit scale).

dpars: dispersal kernel coefficient, by random group, on meter scale.

omegaList: fecundity covariance between trees for the same plot-year.

pacfMat: partial autocorrelation on fecundity.

pacfSe: standard errors for pacfMat.

pacsMat: partial autocorrelation on seed counts.

sigma: estimate of residual log fecundity variance.

sigmaList: fecundity covariance over years.

upars: dispersal kernel coefficient, by random group, on meter^2 scale.

rMu, rSe: if more than one seedName, posterior mean and standard error on R matrix

If yearEffects, then the following will be included in $parameters:

betaYrMu, betaYrSe: posterior mean and standard errors on fixed year effects.

betaYrRand, betaYrRandSE: posterior mean and standard errors on random year effects.

alphaMu, alphaSe: posterior mean and standard errors on random tree effects.

aMu, aSe: posterior mean and standard errors on random effects covariance.

prediction

list of latent variable estimates and prediction:

fecPred includes matrEst, fecEstMu, fecEstSe maturation and fecundity estimates and matrPred, fecPred, fecEst maturation and fecundity predictions.

seedPred includes seed predictions by species, from estimates of latent fecundity and maturation (_estMean, _estSe) and from the fully generative model (_predMean, _predSe).

If predictList is passed to mast, then predictions are returned as seeds per m^2 (not per trap) for the regular prediction grid spaced mapMeters apart in the data.frame seedPredGrid. Tree predictions are returned in treePredGrid are included. If the AR(p) model is used (yearEffect$p is supplied), then both data.frames include p-yr hind casts and p-yr forecasts.

Author(s)

James S Clark, [e-mail]

References

Clark, J.S., C. Nunes, and B. Tomasek. 2019. Foodwebs based on unreliable foundations: spatio-temporal masting merged with consumer movement, storage, and diet. Ecological Monographs, e01381. Qiu, T., ..., and J. S. Clark. 2023. Mutualist dispersers and the global distribution of masting: mediation by climate and fertility. Nature Plants, https://doi.org/10.1038/s41477-023-01446-5.

See Also

mastSim simulates data

A more detailed vignette is can be obtained with:

browseVignettes('mastif')

website 'http://sites.nicholas.duke.edu/clarklab/code/'.

Examples

# simulate data (see \link{\code{mastSim}})
seedNames  <- specNames  <- 'acerRubr'
sim <- list(nyr=10, ntree=20, nplot=5, ntrap=40,
               specNames = specNames, seedNames = seedNames)
               
inputs   <- mastSim(sim)        # simulate data
inputs$predList <- list( mapMeters = 3, plots = inputs$plots[1], 
                         years = inputs$years ) 
output   <- mastif( inputs = inputs, ng = 3000, burnin = 2000 )
# mastPlot(output)

# for Liriodendron
d <- "https://github.com/jimclarkatduke/mast/blob/master/liriodendronExample.rData?raw=True"
repmis::source_data(d)

formulaFec <- as.formula( ~ diam )   # fecundity model
formulaRep <- as.formula( ~ diam )   # maturation model

yearEffect   <- list(groups = 'species') 
randomEffect <- list(randGroups = 'treeID', 
                     formulaRan = as.formula( ~ 1 ) )
inputs   <- list( specNames = specNames, seedNames = seedNames, 
                  treeData = treeData, seedData = seedData, 
                  xytree = xytree, xytrap = xytrap, 
                  yearEffect = yearEffect, randomEffect = randomEffect )
output <- mastif(inputs = inputs, formulaFec, formulaRep, ng = 1000, 
                 burnin = 400 )
summary(output)
# plot output:
# mastPlot(output)