Distance (version 0.7.1)

ds: Fit detection functions and calculate abundance from line or point transect data

Description

This function fits detection functions to line or point transect data and then (provided that survey information is supplied) calculates abundance and density estimates. The examples below illustrate some basic types of analysis using ds().

Usage

ds(data, truncation = NULL, transect = "line",
    formula = ~1, key = "hn", adjustment = "cos",
    order = NULL, scale = "width", cutpoints = NULL,
    monotonicity = FALSE, region.table = NULL,
    sample.table = NULL, obs.table = NULL,
    convert.units = 1, method = "nlminb", quiet = FALSE,
    debug.level = 0)

Arguments

data

a data.frame containing at least a column called distance. NOTE! If there is a column called size in the data then it will be interpreted as group/cluster size, see the section "Clusters/groups", below.

truncation

either truncation distance (numeric, e.g. 5) or percentage (as a string, e.g. "15%"). Can be supplied as a list with elements left and right if left truncation is required (e.g. list(left=1,right=20)

transect

indicates transect type "line" (default) or "point".

formula

formula for the scale parameter. For a CDS analysis leave this as its default ~1.

key

key function to use; "hn" gives half-normal (default), "hr" gives hazard-rate and "unif" gives uniform.

adjustment

adjustment terms to use; "cos" gives cosine (default), "herm" gives Hermite polynomial and "poly" gives simple polynomial. "cos" is recommended. A value of NULL indicates that no adjustments are to be fitted.

order

orders of the adjustment terms to fit (as a vector/scalar), the default value (NULL) will select via AIC. For cosine adjustments, valid orders are integers greater than 2 (except when a uniform key is used, when the minimum order is 1

scale

the scale by which the distances in the adjustment terms are divided. Defaults to "width", scaling by the truncation distance. If the key is uniform only "width" will be used. The other option is "scale": the scale parameter of the detection

cutpoints

if the data are binned, this vector gives the cutpoints of the bins. Ensure that the first element is 0 (or the left truncation distance) and the last is the distance to the end of the furthest bin. (Default NULL, no binning.) Note t

monotonicity

should the detection function be constrained for monotonicity weakly ("weak"), strictly ("strict") or not at all ("none" or FALSE). See Montonicity, below. (Default FALSE).

region.table

data.frame with two columns: ll{ Region.Label label for the region Area area of the region } region.table has one row for each stratum. If there is no stratification then

sample.table

data.frame mapping the regions to the samples ( i.e. transects). There are three columns: ll{Sample.Label label for the sample Region.Label label for the region that the sample belongs to

obs.table

data.frame mapping the individual observations (objects) to regions and samples. There should be three columns: ll{object Region.Label label for the region that the sample belongs to.

convert.units

conversion between units for abundance estimation, see "Units", below. (Defaults to 1, implying all of the units are "correct" already.)

method

optimization method to use (any method usable by optim or optimx). Defaults to "nlminb".

debug.level

print debugging output. 0=none, 1-3 increasing level of debugging output.

quiet

surpress non-warning messages (useful for bootstraps etc). Default value FALSE.

Value

• a list with elements: ll{ddf a detection function model object. dht abundance/density information (if survey region data was supplied, else NULL).}

Details

If abundance estimates are required the data.frames region.table, sample.table and obs.table must be supplied.

Clusters/groups

Note that if the data contains a column named size, cluster size will be estimated and density/abundance will be based on a clustered analsis of the data. Setting this column to be NULL will perform a non-clustred analysis (for example if "size" means something else if your dataset).

Units

In extrapolating to the entire survey region it is important that the unit measurements be consistent or converted for consistency. A conversion factor can be specified with the convert.units variable. The values of Area in region.table, must be made consistent with the units for Effort in sample.table and the units of distance in the data.frame that was analyzed. It is easiest if the units of Area are the square of the units of Effort and then it is only necessary to convert the units of distance to the units of Effort. For example, if Effort was entered in kilometers and Area in square kilometers and distance in meters then using convert.units=0.001 would convert meters to kilometers, density would be expressed in square kilometers which would then be consistent with units for Area. However, they can all be in different units as long as the appropriate composite value for convert.units is chosen. Abundance for a survey region can be expressed as: A*N/a where A is Area for the survey region, N is the abundance in the covered (sampled) region, and a is the area of the sampled region and is in units of Effort * distance. The sampled region a is multiplied by convert.units, so it should be chosen such that the result is in the same units as Area. For example, if Effort was entered in kilometers, Area in hectares (100m x 100m) and distance in meters, then using convert.units=10 will convert a to units of hectares (100 to convert meters to 100 meters for distance and .1 to convert km to 100m units).

Monotonicity

When adjustment terms are used, it is possible for the detection function to not always decrease with increasing distance. This is unrealistic and can lead to bias. To avoid this, the detection function can be constrained for monotonicity.

Monotonicity constraints are supported in a similar way to that described in Buckland et al (2001). 20 equally spaced points over the range of the detection function (left to right truncation) are evaluated at each round of the optimisation and the function is constrained to be either always less than it's value at zero ("weak") or such that each value is less than or equal to the previous point (monotonically decreasing; "strict").

References

Buckland, S.T., Anderson, D.R., Burnham, K.P., Laake, J.L., Borchers, D.L., and Thomas, L. (2001). Distance Sampling. Oxford University Press. Oxford, UK.

Buckland, S.T., Anderson, D.R., Burnham, K.P., Laake, J.L., Borchers, D.L., and Thomas, L. (2004). Advanced Distance Sampling. Oxford University Press. Oxford, UK.

Examples

# An example from mrds, the golf tee data.
 library(Distance)
 data(book.tee.data)
 tee.data<-book.tee.data$book.tee.dataframe[book.tee.data$book.tee.dataframe$observer==1,]
 ds.model<-ds(tee.data,4,monotonicity="strict")
 summary(ds.model)
 plot(ds.model)

 # same model, but calculating abundance
 # need to supply the region, sample and observation tables
 region<-book.tee.data$book.tee.region
 samples<-book.tee.data$book.tee.samples
 obs<-book.tee.data$book.tee.obs

 ds.dht.model<-ds(tee.data,4,region.table=region,monotonicity="strict",
              sample.table=samples,obs.table=obs)
 summary(ds.dht.model)

 # specify order 2 cosine adjustments
 ds.model.cos2<-ds(tee.data,4,adjustment="cos",order=2)
 summary(ds.model.cos2)

 # specify order 2 and 3 cosine adjustments - LOTS of non-monotonicity!
 ds.model.cos24<-ds(tee.data,4,adjustment="cos",order=c(2,3))
 summary(ds.model.cos24)

 # truncate the largest 10\% of the data and fit only a hazard-rate
 # detection function
 ds.model.hr.trunc<-ds(tee.data,truncation="10%",key="hr",adjustment=NULL)
 summary(ds.model.hr.trunc)