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

 plot.dfunc R Documentation

## plot.dfunc - Plot method for distance (detection) functions

### Description

Plot method for objects of class '`dfunc`'. Objects of class '`dfunc`' are estimated distance functions produced by `dfuncEstim`.

### Usage

``````## S3 method for class 'dfunc'
plot(
x,
include.zero = FALSE,
nbins = "Sturges",
newdata = NULL,
legend = TRUE,
vertLines = TRUE,
plotBars = TRUE,
density = -1,
angle = 45,
xlab = NULL,
ylab = NULL,
border = TRUE,
col = "grey85",
col.dfunc = NULL,
lty.dfunc = NULL,
lwd.dfunc = NULL,
...
)
``````

### Arguments

 `x` An estimated distance function resulting from a call to `dfuncEstim`. `include.zero` Boolean value specifying whether to include 0 on the x-axis of 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 input distance range (`w.lo` to `w.hi`). `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, the suggested number of bars (a single number), a string naming an algorithm to compute the number of bars, or a function to compute the number of bars. See `hist` for all options. `newdata` Data frame similar to the `newdata` parameter to `lm` containing new values for covariates in the distance function. One distance function is computed and plotted for each row in the data frame. If `newdata` is NULL, the routine computes the mean of all numeric covariates in the distance function and the mode of all factor covariates in the distance function. The new mean and mode vector is used to predict and plot a distance function. `legend` Logical scalar for whether to include a legend. If TRUE, a legend will be included on the plot detailing the covariate values use to generate the plot. `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, repeated as necessary to exceed the number of bars. 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 and only the borders are rendered. If `density` >0, bars are shaded with colors and angles from parameters `col` and `angle`. `angle` When `density` is >0, the slope of bar shading lines, given as an angle in degrees (counter-clockwise), repeated as necessary to exceed the number of bars. `xlab` Label for the x-axis `ylab` Label for the y-axis `border` The color of bar borders when bars are plotted, repeated as necessary to exceed the number of bars. A value of NA or FALSE means no borders. If bars are shaded with lines (i.e., `density>0`), `border = TRUE` uses the same color for the border as for the shading lines. Otherwise, fill color or shaded line color are specified in `col` while border color is specified in `border`. `col` A vector of bar fill colors or line colors when bars are drawn and `density != 0`, repeated as necessary to exceed the number of bars. Also used for the bar borders when `border = TRUE`. `col.dfunc` Color of the distance function(s). If only one distance function (one line) is being plotted, the default color is "red". If covariates or `newdata` are present, the default value uses `graphics::rainbow(n)`, where `n` is the number of plotted distance functions. Otherwise, `col.dfunc` is replicated to the required length. Plot all distance functions in the same color by setting `col.dfunc` to a scalar. Plot blue-red pairs of distance functions by setting `col.dfunc` = `c("blue", "red")`. Etc. `lty.dfunc` Line type of the distance function(s). If covariates or `newdata` is present, the default uses line types to `1:n`, where `n` is the number of plotted distance functions. Otherwise, `lty.dfunc` is replicated to the required length. Plot solid lines by specifying `lty.dfunc = 1`. Plot solid-dashed line pairs by specifying `lty.dfunc = c(1,2)`. Etc. `lwd.dfunc` Line width of the distance function(s), replicated to the required length. Default is 2 for all lines. `...` When bars are plotted, this routine uses `graphics::barplot` to set up the plotting region and plot 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`, `density`, `angle`, 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 than can be used to reconstruct the plotted bars. To obtain values of the plotted distance functions, use `predict` with `type = "distances"`. The additional components are:

 `barHeights` A vector containing the scaled bar heights drawn on the plot. `barWidths` A vector or scaler of the bar widths drawn on the plot, with measurement units.

Re-plot the bars with ```barplot( return\$barHeights, width = return\$barWidths )```.

`dfuncEstim`, `print.dfunc`, `print.abund`

### Examples

``````set.seed(87654)
x <- rnorm(1000, mean=0, sd=20)
x <- x[x >= 0]
x <- units::set_units(x, "ft")
dfunc <- dfuncEstim(x~1, likelihood="halfnorm")
plot(dfunc)
plot(dfunc, nbins=25)

# showing effects of plot params
plot(dfunc
, col=c("red","blue","orange")
, border="black"
, xlab="Off-transect distance"
, ylab="Prob"
, vertLines = FALSE
, main="Showing plot params")

plot(dfunc
, col="wheat"
, density=30
, angle=c(-45,0,45)
, cex.axis=1.5
, cex.lab=2
, ylab="Probability")

plot(dfunc
, col=c("grey","lightgrey")
, border=NA)

plot(dfunc
, col="grey"
, border=0
, col.dfunc="blue"
, lty.dfunc=2
, lwd.dfunc=4
, vertLines=FALSE)

plot(dfunc
, plotBars=FALSE
, cex.axis=1.5
, col.axis="blue")
rug(dfunc\$detections\$dist)

# Plot showing f(0)
hist(dfunc\$detections\$dist
, n = 40
, border = NA
, prob = TRUE)
x <- seq(dfunc\$w.lo, dfunc\$w.hi, length=200)
y <- predict(dfunc, type="dfunc", distances = x)
lines(x, c(y)/attr(y, "scaler"))
c(attr(y,"scaler") / y[1], ESW(dfunc))  # 1/f(0) = ESW

# Covariates: detection by observer
data(sparrowDetectionData)
data(sparrowSiteData)
dfuncObs <- dfuncEstim(formula = dist ~ observer + groupsize(groupsize)
, likelihood = "hazrate"
, detectionData = sparrowDetectionData
, siteData = sparrowSiteData)
plot(dfuncObs
, newdata = data.frame(observer = levels(sparrowSiteData\$observer))
, vertLines = FALSE
, lty = c(1,1)
, col.dfunc = heat.colors(length(levels(sparrowSiteData\$observer)))
, col = c("grey","lightgrey")
, border=NA
, main="Detection by observer")

``````

Rdistance documentation built on July 9, 2023, 6:46 p.m.