sars (version 2.0.0)

plot.habitat: Plot Options For a 'habitat' Object

Description

S3 method for class 'habitat'. plot.habitat creates plots for objects of class habitat, using the R base plotting framework. The exact plot generated depends on whether the input data come from sar_habitat or sar_countryside.

Usage

# S3 method for habitat
plot(
  x,
  IC = "AICc",
  type = 1,
  powFit = TRUE,
  xlab = NULL,
  ylab = NULL,
  lcol = NULL,
  pLeg = TRUE,
  legPos = "right",
  legInset = 0,
  ModTitle = NULL,
  which = NULL,
  ...
)

Arguments

x

An object of class 'habitat'.

IC

The information criterion weights to present (must be one of 'AIC', 'BIC' or 'AICc'), if plotting a sar_habitat object.

type

Whether a Type 1, 2 or 3 plot should be generated, if plotting a sar_countryside object (see details).

powFit

For Type 1 plots, should the predicted total richness values of the power (or logarithmic) model be included as red points (logical argument).

xlab

Title for x-axis (default titles are used if not provided).

ylab

Title for y-axis (default titles are used if not provided).

lcol

For Type 2 & 3 plots: the colours of the fitted lines, for each component model. Should be a vector, the length (and order) of which should match the number of species groups in x. If not included, randomly selected colours are used.

pLeg

For Type 2 & 3 plots: should a legend be included (logical argument), showing the line colours and corresponding species groups.

legPos

For Type 2 & 3 plots: the location of the legend. Can either be a position (e.g., "bottomright"), or the x and y co-ordinates to be used to position the legend (e.g., c(0,5)).

legInset

For Type 2 & 3 plots: the inset argument in legend. Enables the legend to be plotted outside the plotting window (it still needs the user to manually change their graphical margin parameters).

ModTitle

For Type 2 & 3 plots: a vector of plot titles, which should have the same length as the number of habitats used in the original model fit. If NULL (default), the habitat names used in the original model fit are used. If no plot titles are wanted, use ModTitle = "none".

which

For Type 2 & 3 plots: select an individual plot to generate, rather than generating the plots for all habitats. If not NULL (the default) should be a numeric vector of length 1; the order of plots matches the order of habitats in the original data used to fit the model.

...

Further graphical parameters may be supplied as arguments.

Details

The exact plot that is generated depends on the input data. If x is the fit object from sar_habitat, a simple barplot of information criterion (IC) weights for the different model fits is produced. The particular IC metric to use is chosen using the IC argument.

If x is the fit object from sar_countryside, three plot types can be produced (selected using the type argument). A Type 1 plot plots the predicted total richness values (from both countryside and Arrhenius power (or logarithmic) SAR models) against the observed total richness values, with a regression line (intercept = 0, slope = 1) included to aid interpretation.

A Type 2 plot uses countryside_extrap internally to generate separate fitted SAR curves for each of the modelled species groups, for each habitat individually, using a set of hypothetical sites (ranging in area from zero to the maximum observed site area value) in which the proportion of a given habitat is always 100 percent. See Matthews et al. (2025) for further details. A plot for each habitat is generated, unless the which argument is used to select the plot for a specific habitat. See the Examples section below.

A Type 3 plot follows a similar approach as for Type 2 plots, but instead varies the proportion of a given habitat while fixing site area. The area of the largest site in data is used, and for a given (focal) habitat, the proportion of the site represented by the focal habitat is varied from zero up to one. As site area is fixed, as the proportion of the focal habitat increases, the proportions of the other habitats decrease at an equal rate. This process is then repeated using the next habitat as the focal habitat, and so on.

Note that the logarithmic SAR model doesn't work with zero area values, so the minimum area value of the 'hypothetical' sites used to generate the fitted curves in a Type 2 or 3 plot is set to 0.01 if this model is used.

References

Matthews et al. (2025) An R package for fitting multi-habitat species–area relationship models. In prep.

Examples

#Run the sar_habitat function and generate a barplot of the AICc
#values
data(habitat)

s <- sar_habitat(data = habitat, modType = "power_log",
con = NULL, logT = log)

plot(s, IC = "AICc", col = "darkred")

if (FALSE) {
#Run the sar_countryside function and generate a Type 1 plot,
#including the predicted values of the standard power model
data(countryside)

s3 <- sar_countryside(data = countryside, modType = "power",
gridStart = "partial", habNam = c("AG", "SH",
"F"), spNam = c("AG_Sp", "SH_Sp", "F_Sp", "UB_Sp"))

plot(s3, type = 1, powFit = TRUE)

#Generate Type 2 plots providing set line colours, plot titles,
#and modifying other aspects of the plot using the standard
#base R plotting commands.

 plot(s3, type = 2, lcol = c("black", "aquamarine4",
"#CC661AB3" , "darkblue"), pLeg = TRUE, lwd = 1.5, 
 ModTitle = c("Agricultural land", "Shrubland", "Forest"))
 
#Generate the same plots, but all in a single plotting window,
#using the ask argument
 par(mfrow = c(2, 2))
 plot(s3, type = 2, lcol = c("black", "aquamarine4",
"#CC661AB3" , "darkblue"), pLeg = FALSE, lwd = 1.5, 
 ModTitle = c("Agricultural land", "Shrubland", "Forest"),
 ask = FALSE)
 
 dev.off()
 
#Select a single plot to generate, including
#a legend and positioning it outside the main plotting window.
#Note this will change the graphical margins of your plotting
#window.
par(mar=c(5.1, 4.1, 4.1, 7.5), xpd=TRUE)

plot(s3, type = 2, lcol = c("black", "aquamarine4",
"#CC661AB3" , "darkblue"), pLeg = TRUE,  legPos ="topright",
legInset = c(-0.2,0.3), lwd = 1.5, ModTitle = "Forest",
which = 3)

dev.off()

#Generate Type 3 plots (here only displaying the first)
plot(s3, type = 3, lcol = c("black", "aquamarine4",
"#CC661AB3" , "darkblue"), pLeg = TRUE, lwd = 1.5, ModTitle =
c("Agricultural land", "Shrubland", "Forest"), which =1)

}