# plot.dfunc: Plot a distance (detection) function In Rdistance: Distance-Sampling Analyses for Density and Abundance Estimation

## Description

Plot method for an estimated distance function. Estimated distance functions are of class 'dfunc'

## Usage

 1 2 3 4 5 6 ## S3 method for class 'dfunc' plot(x, include.zero = FALSE, nbins = "Sturges", newdata = NULL, legend = TRUE, vertLines = TRUE, plotBars = TRUE, density = NULL, xlab = "Distance", ylab = if (x\$pointSurvey) "Observation density" else "Probability of detection", border = "blue", col = 0, col.dfunc = "red", lty.dfunc = 1, lwd.dfunc = 2, ...)

## Arguments

 x An estimated distance function resulting from a call to dfuncEstim. include.zero Boolean value specifying whether to include 0 in the plot. A value of TRUE will include 0 on the left hand end of the x-axis regardless of the range of distances. A value of FALSE will plot only the range on input distanced. nbins Internally, this function uses hist to compute histogram bars for the plot. This argument is the breaks argument to hist. This can be either a vector giving the breakpoints between bars, a single number giving the suggested number of bars, a string naming an algorithm to compute the number of bars, or a function to compute the number of bars. See help(hist) for all options. newdata Matrix containing values of covariates to plot. Each row is a set of covariate values (i.e. each column contains all values of each covariate) legend Logical scalar for whether to include legend. If TRUE, a legend will be included on plot detailing covariate values plotted. vertLines Logical scalar specifying whether to plot vertical lines at w.lo and w.hi from 0 to the distance function. plotBars Logical scalar for whether to plot the histogram of distances behind the distance function. If FALSE, no histogram is plotted, only the distance function line(s). density If plotBars=TRUE, a vector giving the density of shading lines, in lines per inch, for the bars underneath the distance function. Values of NULL or a number strictly less than 0 mean solid fill using colors from parameter col. If density =0 , bars are not filled with any color or lines. xlab Label for the x-axis ylab Label for the y-axis border The color of bar borders when bars are plotted. A value of NA means no borders. If there are shading lines (i.e., density>0), border = TRUE uses the same color for the border as for the shading lines. col A vector of bar fill colors or line colors when bars are drawn and density != 0, replicated to the correct length. A value of 0 is the background color. col.dfunc Color of the distance function(s), replicated to the required length. If covariates or newdata is present and length(col.dfunc)==1, col.dfunc is expanded to to number of plotted distance functions by setting it equal to graphics::rainbow(n), where n is the number of plotted distance functions. If you want to plot all distance functions in the same color, set col.dfunc to a constant vector having length at least 2 (e.g., col.dfunc = c(1,1)) will plot all curves in black). lty.dfunc Line type of the distance function(s), replicated to the required length. If covariates or newdata is present and length(lty.dfunc)==1, lty.dfunc is expanded to to number of plotted distance functions by setting it equal to lty.dfunc + 0:(n-1), where n is the number of plotted distance functions. If you want to plot all distance functions using the same line type, set lty.dfunc to a constant vector having length at least 2 (e.g., lty.dfunc = c(1,1)) will plot all solid lines). lwd.dfunc Line width of the distance function(s), replicated to the required length. ... When bars are plotted, this routine uses graphics::barplot for setting up the plotting region and plotting bars. When bars are not plotted, this routine sets up the plot with graphics::plot. ... can be any other argument to barplot or plot EXCEPT width, ylim, xlim, and space.

## Details

If plotBars is TRUE, a scaled histogram is plotted and the estimated distance function is plotted over the top of it. When bars are plotted, this routine uses graphics::barplot for setting up the initial plotting region and most parameters to graphics::barplot can be specified (exceptions noted above in description of '...').The form of the likelihood and any series expansions is printed in the main title (overwrite this with main="<my title>"). Convergence of the distance function is checked. If the distance function did not converge, a warning is printed over the top of the histogram. If one or more parameter estimates are at their limits (likely indicating non-convergence or poor fit), another warning is printed.

## Value

The input distance function is returned, with two additional components related to the plot that may be needed if additional lines or text is to added to the plot by the user. These additional components are:

 xscl.plot Scaling factor for horizontal coordinates. Due to the way barplot works, the x-axis has been scaled. The internal coordinates of the bars are 1, 2, ..., nbars. To plot something at a distance coordinate of x, x must be divided by this value. For example, to draw a vertical line at a value of 10 on the x-axis, the correct call is abline(v=10/obj\$xscl.plot). yscl Scaling factor for vertical coordinates. The histogram and distance function plotted by this routine are scaled so that height of the distance function at w.lo is g0. Usually, this means the distance curve is scaled so that the y-intercept is 1, or that g(0) = 1. To add a plot feature at a real coordinate of y, y must be divided by this returned parameters. For example, to draw a horizontal line at y-axis coordinate of 1.0, issue abline(h=1/obj\$yscl).

## Author(s)

Trent McDonald, WEST Inc., tmcdonald@west-inc.com
Aidan McDonald, WEST Inc., aidan@mcdcentral.org