niche.plot: Plot for 2-d projection of niche regions.

In nicheROVER: Niche Region and Niche Overlap Metrics for Multidimensional Ecological Niches

Plot for 2-d projection of niche regions.

Description

For one or more species, creates a series of plots: (i) the raw niche indicators (e.g., stable isotope) data, (ii) their density estimates, and (iii) 2-dimensional projections of probabilistic niche regions based on n-dimensionsional data.

Usage

niche.plot(
  niche.par,
  niche.data,
  alpha = 0.95,
  species.names,
  iso.names,
  lims,
  col,
  ndens = 512,
  pfrac = 0,
  xlab,
  legend = TRUE
)

Arguments

niche.par	A list of length nspecies, each element of which in turn is a list with elements mu and Sigma. Each of these will correspond to an ellipse being drawn for that species in the corresponding 2-d plane. See 'Example'.
niche.data	A list of length nspecies, each element of which is a matrix with observations along the rows and niche indicators (e.g., stable isotopes) along the columns.
alpha	Size of the niche region to plot. Defaults to 0.95.
species.names	Names of the species. Defaults to names(niche.par).
iso.names	Names of the niche indicators (or isotopes) to plot. Defaults to colnames(niche.par).
lims	Two-row matrix of range limits for each niche indicator. Defaults to include all ellipses.
col	Vector of colours in which each species will be drawn.
ndens	Number of points at which to evaluate kernel density estimates.
pfrac	Fraction of the plot on which to display 1-dimensional raw niche indicator data. pfrac = 0 means don't display the raw data in 1-d.
xlab	Title of plot, located on the bottom. Defaults to no title.
legend	Whether or not to add a legend. Defaults to TRUE.

Details

A set of plots is created for each pairwise combination of niche indicators. Below the diagonal are scatterplots for each species, above the diagonal are ellipses corresponding to 2-d projections of the probabilistic niche regions. The diagonal displays density estimates for each indicator, and optionally the raw 1-d data. See Swanson et al. (2015) for detailed description of the probabilistic niche region.

Value

Returns a series of plots displaying niche indicator data and their probabilistic niche projections.

References

Swanson, H.K., Lysy, M., Stasko, A.D., Power, M., Johnson, J.D., and Reist, J.D. "A new probabilistic method for quantifying n-dimensional ecological niches and niche overlap." Ecology: Statistical Reports 96:2 (2015): 318-324. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1890/14-0235.1")}.

See Also

overlap.plot(), niw.post(), niiw.post().

Examples

data(fish) # 4 fish, 3 isotopes

# generate 10 parameter draws from the posteriors
# of each fish with default prior
nsamples <- 10
fish.par <- tapply(1:nrow(fish), fish$species,
                   function(ii) niw.post(nsamples = nsamples, X = fish[ii,2:4]))

# format data for plotting function
fish.data <- tapply(1:nrow(fish), fish$species, function(ii) X = fish[ii,2:4])

clrs <- c("black", "red", "blue", "orange") # colors for each species
niche.plot(niche.par = fish.par, niche.data = fish.data, pfrac = .1,
           iso.names = expression(delta^{15}*N, delta^{13}*C, delta^{34}*S),
           col = clrs, xlab = expression("Isotope Ratio (per mille)"))

nicheROVER documentation built on Oct. 13, 2023, 5:10 p.m.