posum {posum}R Documentation

Population Surface Model Fitting

Description

This routine fits a population surface model or death rate surface model to age structured population data. The routine relies on mgcv 0.8.2 or above.

Usage

posum(data,constrain=TRUE,fam="n",jk=50,ak=10,fk=5,rk=10,
      options=posum.options(),control=gam.control(),model.type=1)

Arguments

data A data frame containing the following named variables:
y
The stage population data. This may contain NA's: a feature whose prime function is to allow the user to supply extra information about stage boundaries, if needed.
stage
Which stage each element of y relates to.
a0
The lower age boundary for this observation.
a1
The upper age boundary for this observation. NA implies an adult stage. If an element is equal to the corresponding a0 element then the corresponding y is taken as a direct observation of the population surface height (rather than the usual integral under it.)
t
Sample time for each observation.
constrain Should positive death rate, positive population constraints on the model be imposed?
fam Which error distribution to use. "n" for normal, "p" for Poisson or "g" for gamma. (Note that link is always identity - nothing else makes sense for these models.)
jk The maximum number of parameters to use to represent the juvenile population surface. Actual effective degrees of freedom will be chosen by mgcv as part of model fitting.
ak The maximum number of parameters to use to represent the adult population surve. Actual effective degrees of freedom will be chosen by mgcv as part of model fitting.
fk basis dimension to use for initial age structure for type 2 models.
rk basis dimension to use for recruitment function for type 2 models.
options A list of options controlling numerical details of the calculations. See posum.options.
control A gam fit control object: see gam.control for details.
model.type Set to code{1} for a population surface model, in which the smoothness assumptions relate to the population per unit age interval surface, and death rates are obtained by differentiation of the fitted population surface. Set to code{2} for a death rate surface model, in which recruitment rate, inital population structure and total death rate surface are the things assumed smooth. In the latter case the population surface is obtained from the recruitment or initial population functions after subtraction of a suitable integral under the death rate surface.

Details

The code is based on setting up population surface/ death surface models as special versions of generalized additive models and then fitting these using the GAM routines provided by package mgcv.

Model type 1 is based on estimating the population per unit age interval surface as a smooth function of age and time and is quite quick. Model type 2 estimates the total death rate surface as a smooth function of age and time, the birth rate as a smooth function of time, and the initial populaiton per unit age inteval as a smooth function of age. Type 2 model are much slower, but can produce better results if recruitment varies rather fast in relation to the variation in death rate.

Value

The function returns a gam object, that can be used with most of the standard gam handling routines provided in mgcv. In addition it has some extra elements:

amax.fn A function returning the age at the upper boundary of the population surface. This is based on the user supplied age boundary data, interpolated using a cubic spline filtered using a modification of Hyman's algorithm in order to ensure a gradient with respect to time less than or equal to one.
adults TRUE if adults present in data, FALSE if not.
data The input data frame.
options The input options.

WARNING

Author(s)

Simon N. Wood snw@st-and.ac.uk

References

Gu and Wahba (1991) Minimizing GCV/GML scores with multiple smoothing parameters via the Newton method. SIAM J. Sci. Statist. Comput. 12:383-398

Wood (2000) Modelling and Smoothing Parameter Estimation with Multiple Quadratic Penalties. JRSSB 62(2):413-428

Wood (2003) Thin Plate Regression Splines in press JRSSB

http://www.ruwpa.st-and.ac.uk/simon.html

See Also

age.max, cm.splinefun, death.surface, hyman.filter, pcdr, population, population.data, population.surface, posum.atplot, posum.check, posum.con, posum.fit, posum.options, posum.plot, posum.stage, posum.stage.plot, posum.X, rec, sim.age.bound, spl.coef.conv, stage.bound, survival,

Examples

data<-population.data(fam="p",adult=TRUE) #simulate data
b<-posum(data,fam="p")
op<-par(mfrow=c(2,2))
posum.plot(b)
plot(fitted(b),residuals(b))
plot(data$y,fitted(b))
par(mfrow=c(3,4))
posum.stage.plot(b)
posum.stage(b,lo=1,hi=4)
rm(data,b)
par(op)

[Package Contents]