This function plots the overlap of traits among species for each community. If there are multiple traits, each trait is plotted separately in one-dimensional space.

Ostats_plot(
  plots,
  sp,
  traits,
  overlap_dat = NULL,
  use_plots = NULL,
  n_col = 1,
  scale = "fixed",
  colorvalues = NULL,
  alpha = 0.5,
  adjust = 2,
  bin_width = 1,
  limits_x = NULL,
  legend = FALSE,
  name_x = "trait value",
  name_y = "probability density",
  normalize = TRUE,
  means = FALSE,
  circular = FALSE,
  discrete = FALSE,
  circular_args = list()
)

Arguments

plots

Site identity: a vector of names of each community.

sp

Taxon identity: a vector of species or taxa names.

traits

A vector of trait measurements for each individual, or a matrix or data frame with rows representing individuals and columns representing traits.

overlap_dat

Optional: an object containing the output of Ostats. If provided, overlap statistics will be displayed in the plot panels.

use_plots

a vector of sites to plot. If NULL, the function will plot all the sites.

n_col

Number of columns for layout of individual panels. Default is 1.

scale

If you want the scale of x, y or both x and y axis to be independent, set the argument to "free_x", "free_y" or "free" respectively. Default = "fixed" which uses the same scale across all sites. See facet_grid.

colorvalues

Vector of color values for the density polygons. Defaults to a viridis palette if none provided.

alpha

defines the transparency level for the density polygons. Default is 0.5.

adjust

the bandwidth adjustment of the density polygons. Default is 2. See density. Only used if discrete = FALSE.

bin_width

the width of each bin of the histograms. Default is 1. Only used if discrete = TRUE.

limits_x

Vector of length 2, with multiplicative factor to apply to the minimum and maximum values of each trait to expand the limits of the x axis. Default is c(0.5, 1.5), or 0.5 times the minimum and 1.5 times the maximum value of each trait, for continuous traits. For discrete traits the default is c(1, 1) or no expansion of limits.

legend

Whether to include a legend. Defaults to FALSE.

name_x

x-axis label. Default is 'trait value'

name_y

y-axis label. Default is 'probability density'

normalize

if TRUE, areas of density plots are normalized to be equal across taxa; if FALSE, areas will be proportional to abundance. Default is TRUE.

means

if TRUE, trait means for each species are plotted in an additional plot column next to the traits distribution plots for each site. Default is FALSE.

circular

if TRUE, plots density plots or histograms using polar coordinates, and estimates density using method for objects of class circular. Default is FALSE.

discrete

if TRUE, plots histograms at discrete trait values instead of smooth kernel density plots. Default is FALSE.

circular_args

optional list of additional arguments to pass to circular. Only used if circular = TRUE and discrete = FALSE. If no arguments are provided, default arguments to circular are used.

Value

Density plots of species trait distributions plotted together for each community to show how they overlap each other. Each community is plotted on a separate panel within a multipanel figure. The overlap value obtained as output from Ostats

is labelled on each community graph, if provided by the user.

If trait values are discrete rather than continuous, histograms are plotted instead of kernel density plots.

If trait values are circular, a circular kernel density estimate for each species is plotted on a polar coordinate plot. If trait values are both circular and discrete, a "sunburst" plot is returned.

The class of the returned object is Ostats_plot_object. Calling

print on this object will draw the plot using

grid.draw.

If more than one trait is provided, a list of objects of class

Ostats_plot_object will be returned.

See also

Ostats to Calculate O-statistics (community-level pairwise niche overlap statistics)

Examples

# set the arguments:
plots <- small_mammal_data$siteID
sp <- small_mammal_data$taxonID
traits <- log10(small_mammal_data$weight)

# to plot only selected sites:
use_plots <- c('BART','KONZ','JORN')


Ostats_plot(plots = plots, sp = sp, traits = traits,
           overlap_dat = small_mammal_Ostats,
           use_plots = use_plots, means = TRUE)
#> Warning: Removed 61 rows containing non-finite values (stat_density).
#> Warning: Groups with fewer than two data points have been dropped.
#> Warning: Groups with fewer than two data points have been dropped.
#> Warning: no non-missing arguments to max; returning -Inf
#> Warning: no non-missing arguments to max; returning -Inf
#> Warning: Removed 2 rows containing missing values.