Visualizing Results
plot_sumz() and
plot_sumz_density()
The community-level output may be viewed using the plot_sumz() or plot_sumz_density()
functions. The plot_sumz_density()
function is new to this version of TITAN2. We recommend
its use because we think it will be both easier to understand than
previous output and encourage appropriate interpretation of results.
There are many options for changing the look of the graphs; see their
full documentations with ?plot_sumz or
?plot_sumz_density. An abbreviated
version is presented below. To begin, here’s how you use plot_sumz_density():
plot_sumz_density()
plots community level change identified with TITAN2.
There are three component panels in the default output and we will
consider them from the bottom to the top. The first plot is a slight
modification of the original sum(z) plot first presented by Baker and
King (2010). It shows the magnitude of change among taxa declining along
the gradient (z-) and those increasing along the gradient. Peaks in the
values indicate points along the environmental gradient that produce
large amounts of change in community composition and/or structure. These
are the nominal community change points. Plateaus denote regions of
similar change. The sums are converted to areas using the logical
argument ribbon, a line plot can be
obtained by setting ribbon to FALSE, and the
original point plot can be obtained by setting the logical argument
points to TRUE.
The second change from earlier versions of TITAN2 is
that the logical argument filter
defaults to TRUE. This argument
ensures that the only taxa contributing to patterns in the sum(z) are
pure and reliable taxa identified by the bootstrap results rather than
all taxa. Setting filter to FALSE allows impure
or unreliable taxa to contribute to apparent patterns of community
change. In general, the filtered scores should show a similar pattern
but be somewhat lower in magnitude depending on contributions from
impure or unreliable taxa.
The middle panel shows the estimated probability density of the sum(z) across all bootstrap replicates. Previously these distributions were represented by cumulative frequency distributions of the sum(z) maxima. A narrow spread indicates a high degree of precision regarding the location of the community change point.
The top panel shows the observed sum(z-) and sum(z+) maxima as circles with the 95th percentile of their distributions as horzontal lines. The primary reason for this plot is to illustrate how much information is hidden by this technique relative to the probability density functions.
There are several additional plotting options in plot_sumz_density().
First, any of the three panels can be dropped by setting logical
arguments sumz, density, or change_points to FALSE. Second, it is
possible to display only the z- or z+ taxa through the use of the
logical arguments sumz1 and sumz2. Finally, the x axis label can be
edited using the xlabel argument.
plot_sumz_density(glades.titan,
ribbon = TRUE, points = FALSE, sumz1 = FALSE, change_points = FALSE,
xlabel = expression(paste("Surface Water Total Phosphorus ("*mu*"g/l)"))
)
Besides the mandatory titan object, arguments include:
filter- controls whether filtered (default) or unfiltered sum(z) scores are plottedsumz- logical whether sum(z) values are plottedpoints- logical whether point values of the sum(z) should be plottedribbon- logical whether values of sum(z) should be plotted as a ribbondensity- logical whether estimated probability densities should be plottedchange_points- logical whether community change points should be plottedsumz1- logical whether sum(z) formaxgrp == 1should be plottedsumz2- logical whether sum(z) formaxgrp == 2should be plottedxmin- controls the x-axis minimumxmax- controls the x-axis maximumxlabel- text string for x-axis labely1label- text string for sum(z) y-axis, default labels are providedy2label- text string for density plotalpha1- controls the transparancy of sum(z-)alpha2- controls the transparancy of sum(z+)col1- color formaxgrp == 1col2- color formaxgrp == 2axis_lab_size- controls size of axis labelslegend.position- controls location of legend
For plot_sumz, the older plotting
function in TITAN2, filled and hollow symbols denote
the magnitude of summed z scores of increasing (z+) or decreasing (z-)
taxa. Peaks in the values indicate points along the environmental
gradient that produce large amounts of change in community composition
and/or structure. Solid and dashed lines are cumulative frequency
distributions of sum(z-) and sum(z+) maxima (respectively) across
bootstrap replicates. Vertical CFDs indicate narrow uncertainty about
where the maximum chnage occurs, sloping or stair-step CFDs suggest
broad uncertainty regarding the location of maximum change.
Note that users can adjust colors (e.g. col1 and fil1) and labels for
the left hand y-axis using the argument y1label or the x-axis with xlabel. Setting filter = TRUE
will display the filtered sum(z) scores. In general, the filtered scores
should show a similar pattern but be somewhat lower in magnitude
depending on contributions from impure or unreliable taxa:
Besides the mandatory titan object, arguments include:
filter- logical whether filtered or unfiltered sum(z) scores are plotted (defaultFALSE, unfiltered)cumfrq- logical whether cumulative frequencies are plottedbootz1- logical whether cumulative frequencies formaxgrp == 1should be plottedbootz2- logical whether cumulative frequencies formaxgrp == 2should be plottedsumz1- logical whether sum(z) formaxgrp == 1should be plottedsumz2- logical whether sum(z) formaxgrp == 2should be plottedxmin- controls the x-axis minimumxmax- controls the x-axis maximumxlabel- text string for x-axis labely1label- text string for first y-axis, default labels are filtered or unfiltered sum(z)y2label- text string for second y-axislog- whether any axis should be log transformed for display (default" ")at- controls coordinates of x-axis locationtck- controls length and direction of tick marks; set to pointbty- controls box type around plot (default"u")ntick- number of tick marks to be plotted per axisprtty- controls whetherpretty()is used to plot axis labelsdig- controls number of decimal digits in axescex- controls size of points in graphcex.leg- controls size of legend text/symbolscex.laband cex.axis - control size of text on axesleg.x - xcoordinate of legendleg.y - ycoordinate of legendlegend- logical whether legend should be plottedpch1- point symbols formaxgrp == 1pch2- point symbols formaxgrp == 2col1- color formaxgrp == 1col2- color formaxgrp == 2(unfilled)
plot_taxa_ridges()
Pure (purity>=0.95 or higher) and reliable (reliability>=0.95
or higher) indicator taxa that contribute to the overall sum(z) scores
can be plotted using the function plot_taxa_ridges().
Taxa that meet purity (pur.cut) and reliability (rel.cut) criteria
are extracted from the full taxa output object titan.out$sppmax,
separated into two groups: z- (negative responders, or decliners) and z+
(positive responders, or increasers).
These two groups of negative and positive responders are arranged into separate, stacked panels for plotting. Within each panel, taxa change points (values of x resulting in the largest indicator z value) are visualized as a probability density function of the nBoot bootstrapped replicates (n=500 or however many nBoot replicates specified by the user).
Taxa names are arranged discretely along the y-axis based on the rank order of the median (i.e., 50th percentile or 2nd quantile) change-point value from n bootstrap replicates. The rank order of taxa is low-to-high (ascending) for z- (negative, decliners) but high-to-low (descending) for z+ (positive, increasers), respectively.
There are many options for changing the look of the graph, so see the
full documentation with ?plot_taxa_ridges, but you can get started
by simply calling plot_taxa_ridges()
on the output of titan():
plot_taxa_ridges(glades.titan, axis.text.y = 8)
# → There are 90 indicator taxa of 90 possible for plotting
# ↘ Number of Decreasers = 41
# ↗ Number of Increasers = 49
Optional arguments include:
z1- logical whethermaxgrp == 1taxa (z-, negative, decliners) should be plottedz2- logical whethermaxgrp == 2taxa (z-, negative, decliners) should be plottedz1_fill_low- low value of the color fill gradient for z- (negative) taxaz1_fill_high- high value of the color fill gradient for z- (negative) taxaz2_fill_low- low value of the color fill gradient for z+ (positive) taxaz2_fill_high- high value of the color fill gradient for z+ (positive) taxa
xlabel- the x axis label; the default is “Environmental Gradient”n_ytaxa- the maximum number of taxa that can be plotted on the y-axes (combined between the two panels if bothz1andz2 == TRUE, or just for one panel if z1 or z2 = FALSE). If the total number of pure and reliable indicator taxa exceeds the value of n_ytaxa, then the function will select only the most pure and reliable taxa to match the value of n_ytaxa based on rank order of purity, reliability, and finally z.med (sequential sorting, respectively). The selection of n_ytaxa is independent of group membership, so that only the best indicators are displayed, regardless of z- or z+ grouping. default = 90.printspp- a logical determining whether the sppmax output for the plotted taxa is printed to the console; default = FALSE.grid- a logical determining whether gridlines are plotted; default=TRUExlim- the upper and lower limits of the x-axis, e.g., xlim=c(0,180). The default is computed internally based on the lower and upper limits of the x variable.bw- short for “bandwidth”, it controls the degree of smoothing of the probability density plots. This is computed internally but can be adjusted manually using this argument. We strongly advise against changing this parameter from the default.d_lines- short for “density lines”, a logical determining whether the median change point values estimated from each taxon’s density function, is plotted. If TRUE, a dashed, black vertical line will be plotted. default = FALSE (The solid vertical line represents the median from the actual bootstrap changepoint distribution).trans- applies “identity”, “log10” or “sqrt” transformation to the x-axis. Set minimum value of xlim(,) to > 0 if trans = “log10”. default=“identity”xaxis- logical for plotting solid black line and tick marks for x-axis (single panel) or x-axes (multi-panel). When FALSE, only the gray grid lines are plotted. default=FALSEbreaks- specify x-axis breaks and tick mark labels with a string of values, e.g., breaks = c(10, 20, 40, 80). Defaults to values generated by geom_density_ridges().rel_heights- determines the relative height of panels if z1 and z2 = TRUE. Allows user to scale z1 and z2 panels in proportion to the number of taxa plotted on y. default = (0.5, 0.5).axis.text.x- size of tick labels on x-axisaxis.text.y- size of the taxa labels on the y-axis. Defaults to axis.text.y=10. Depending upon the height and width of the plot, labels may need to set to a smaller size to avoid overlap (e.g., see the plot above; here, axis.text.y= 8).axis.title.x- size of text of x-axis title
Below is the same function with a user-specified x-label and n_ytaxa set to 50
plot_taxa_ridges(glades.titan,
xlabel = expression(paste("Surface water total phosphorus ("*mu*"g/l)")),
n_ytaxa = 50
)
# → There are 90 indicator taxa of 50 possible for plotting
# ↘ Number of Decreasers = 41
# ↗ Number of Increasers = 49
There are a total of 90 pure and reliable indicator taxa in the glades.titan output, thus 40 taxa were
excluded from this plot because we set n_ytaxa = 50. The 50
taxa plotted are the top 50 out of 90 taxa based on descending rank
order of purity, reliability, and z.median, respectively. This argument can be
useful when there are too many pure and reliable taxa to effectively
visualize in one plot.
Alternatively, set z1 or
z2 = FALSE.
plot_taxa_ridges(glades.titan,
xlabel = expression(paste("Surface water total phosphorus ("*mu*"g/l)")),
z2 = FALSE
)
# → There are 90 indicator taxa of 90 possible for plotting
# ↘ Number of Decreasers = 41
# ↗ Number of Increasers = 49
Gridlines are set to TRUE as the default,
but can be removed if desired:
plot_taxa_ridges(glades.titan,
xlabel = expression(paste("Surface water total phosphorus ("*mu*"g/l)")),
z2 = FALSE, grid = FALSE
)
# → There are 90 indicator taxa of 90 possible for plotting
# ↘ Number of Decreasers = 41
# ↗ Number of Increasers = 49
Here’s a final example with additional arguments: 1) d_lines = TRUE
(dashed vertical line corresponding to the median change point from the
density distribution function), 2) rel_heights set in proportion to the number
of decreaser and increaser taxa, respectively, 3) xaxis = TRUE,
4) log-10 scaling of the x-axis, 5) specification of x-axis limits, 6)
specification of x-axis breaks and tick mark values, and 7) resizing of
x and y axes text and and x-axis title (axis.text.x, axis.text.y, and axis.title.x).
plot_taxa_ridges(
glades.titan,
axis.text.x = 12, axis.text.y = 8, axis.title.x = 14,
rel_heights = c(0.45, 0.55), xaxis = TRUE, d_lines = TRUE, trans = "log10",
xlim = c(4, 200), breaks = c( 10, 20, 40, 80, 160),
xlabel = expression(paste("Surface water total phosphorus ("*mu*"g/l)"))
)
# → There are 90 indicator taxa of 90 possible for plotting
# ↘ Number of Decreasers = 41
# ↗ Number of Increasers = 49
plot_taxa()
Pure and reliable indicator taxa change points can be plotted using
an older plotting function that was integral to the original TITAN2
release, plot_taxa(). We have
replaced this plot with the distributions in plot_taxa_ridges()
because it tended to emphasize the observed change points over the
distribution of change points from the bootstrap replicates. Again,
there are many options for changing the look of the graph, so see the
full documentation with ?plot_taxa,
but you can get started by simply calling plot_taxa() on the
output of titan():
Each plot includes robust declining taxa on the left axis, increasers
on the right. Each median change point (50th percentile) of bootstrap
replicates (or observed change point if z.med = FALSE) is
indicated by the circular symbol; the horizontal lines suggest 5-95%
quantiles from the bootstrapped change point distribution.
Optional arguments include:
z1- logical whethermaxgrp == 1taxa change points should be plottedz2- logical whethermaxgrp == 2taxa change points should be plottedinterval- logical whether 5%-95% quantile intervals should be plottedprob95- controls whether change point symbols are plotted at observed value or at quantile extremes, the extremes are useful for thinking about change from a risk perspectivez.med- controls whether change point symbols are plotted at median of bootstrap replicates and using median \(z\) score instead of observed value.default = TRUE(recommended).cex.taxa- controls size of taxon names in graph.
log, at, xmin,
xmax, xlabel, tck, bty,
ntick, prtty, dig, leg.x, leg.y, cex, cex.axis, cex.leg, cex.lab, legend, col1, fil1, col2, and fil2 are the same as in plot_sumz()
above.
Here is the same function with z.med = FALSE
(plots points at observed change-point value instead of 50% of bootreps;
we recommend the default (TRUE), however, as
it more robust, particularly in small data sets):
plot_taxa(
glades.titan, z.med = FALSE,
xlabel = expression(paste("Surface water total phosphorus ("*mu*"g/l)"))
)
A more complete illustration of plot_taxa(), with z.med = TRUE
(default), no legend, decreased size of taxa labels, increased size of
x-axis labels, and added colored points and fill.
plot_taxa(
glades.titan,
xlabel = expression(paste("Surface water total phosphorus ("*mu*"g/l)")),
cex.taxa = 0.5, cex = 1.25, cex.axis = 1.1, legend = FALSE,
col1 = "black", col2 = "red", fil2 = "red"
)
Alternatively, with prob95 = TRUE:
plot_taxa(
glades.titan,
xlabel = expression(paste("Surface water total phosphorus ("*mu*"g/l)")),
cex.taxa = 0.5, cex = 1.25, cex.axis = 1.1, legend = FALSE,
prob95 = TRUE, col1 = "black", col2 = "red", fil2 = "red"
)
Importantly, some of the control over the plotting that was optional
in the original version has been internalized and warnings are issued
when users plot results without using the bootstrap results. Tables of
significant z- and z+ taxa used to make graph are automatically returned
but no longer automatically written as text files (these can be easily
extracted from the glades.titan$sppmax
table).
plot_cps()
In TITAN2 2.0 and later, there are several plotting options; all contained within a single function centered on interpreting taxon-specific change points in the context of the results from the bootstrap resampling procedure.
taxa.dist- logical controls if taxon-specific change point distributions are plottedz.weights- logical controls if the median z-sore magnitude is used to weight the PDF from the distribution of resampled change pointstaxaID- if a number or name, creates a single taxon-specific abundance plotcp.med- logical controls if change point locations should be plotted using the median value across all bootstrap replicates instead of the observed valuecp.trace- logical controls if IndVal and zscores are plotted for all candidate change pointscp.hist- logical controls if histogram of change point PDF is plottedstacked- logical controls if change point PDFs for increasing and decreasing taxa are stacked or plotted separately
The remaining arguments: xlabel,
xmin, xmax, tck,
bty, ntick, cex, cex.axis, cex.leg, cex.lab, leg.x, leg.y and legend are the same as in the previous
plotting functions.
The default graphic from plot_cps() is a
\(z\)-score weighted probability
density function derived from the empirical distribution of change
points across all bootstrap replicates plotted as a histogram for each
pure and reliable taxon (blue for decreasers and red for increasers).
NOTE: When you try to plot the matrix of plots consecutively you can
generate an error about “Figure margins too large”. This is easily
addressed by closing the plot window, or turning the graphics device
off.
Typically, these histograms are visually scanned to distinguish those
taxa whose bootstrapped change point distributions are clearly unimodal
from those that are multimodal or more uniform. For any taxon of
interest, a closer inspection can be achieved by setting the argument
“taxaID” to a taxon ID number or label name. For example, in the plot
above, if the declining (i.e., maxgrp == 1)
taxon "ENALCIVI"
is of interest, the user can set taxaID = 57
or taxaID = "ENALCIVI" and either will produce the plot
below. Again, you may need to close the plotting window or turn graphics
off because we are switching plot margins.
The base plot is simply taxon-specific abundance (black circles)
along the environmental gradient. Overlaid near the top of the plot in
red is the observed change point, or if cp.med = TRUE,
the median change point across all bootstrap replicates. Overlaid on the
abundance plot is the \(z\)-weighted
(if z.weights = TRUE)
probability density function of change point locations across all
bootstrap replicates (blue histogram). Setting cp.hist = FALSE
will remove the histogram. On the other hand, setting cp.trace = TRUE
will plot the observed IndVal \(z\)
scores (in red; what TITAN2 uses by default if imax = FALSE)
and the observed IndVal scores (in grey) for every candidate change
point along the environmental gradient (see Baker and King
2013 for examples):
Below is an increasing taxon from the same data set with a conspicuously bimodal distribution of replicate change points:
Here it appears as if two potential change points were predominantly identified: one that kept nearly all of the abundance to the right, and another (the observed) than kept nearly all the absences to the left.
Finally, if taxa.dist = FALSE,
instead of a taxon-specific plot, plot_cps() will
produce a plot of the summed \(z\)-weighted (if z.weights = TRUE)
probability densities across increasing (maxgrp == 1;
blue) decreasing (maxgrp = 2; red) and all pure and
reliable taxa (filter>0; grey):
plot_cps(glades.titan, taxa.dist = FALSE, xlabel = "Surface Water TP (ug/l)")
# [1] "Summary of Summed Density Functions"
# uw.env uw.max zw.env zw.max
# Group 1 14.55 1.00 14.55 10.22
# Group 2 28.80 1.34 28.80 11.13
# P&R Taxa 28.80 2.01 28.80 17.14
The accompanying table summarizes the location of both the \(z\)-weighted and unweighted maxima along
the environmental gradient, as well as the magnitude of those maxima for
decreasing taxa (maxgrp == 1),
increasing taxa (maxgrp == 2),
and all pure and reliable taxa combined. In this case there appears to
be good correspondence between the sum(z) maxima and the summed \(z\)-weighted PDF maxima. In other words,
the points at which community change appears to be greatest corresponds
to where the sum of individual taxa changes tend to occur, even when
different sets of observations are used. In practice, this is a
desirable result we would expect to occur most of the time, yet
exceptions to this pattern can also be informative. For example, in the
plot above, there appears to be another candidate change point closer to
~10 ug/l where declining taxa tend to change frequently, and at both ~25
ug/l and ~40 ug/l there are large numbers of frequently occurring change
points across both decliners and increasers even though they are not
particularly large for either group by itself.
Alternatively, these different sums can be represented as a stacked
bar chart by setting stacked = TRUE:
plot_cps(glades.titan, taxa.dist = FALSE, xlabel = "Surface Water TP (ug/l)", stacked = TRUE)
# [1] "Summary of Summed Density Functions"
# uw.env uw.max zw.env zw.max
# Group 1 14.55 1.00 14.55 10.22
# Group 2 28.80 1.34 28.80 11.13
# P&R Taxa 28.80 2.01 28.80 17.14
Here the blue and red circles correspond to the location of the
respective maxima for decreasing and increasing taxa change points. In
either case, the summed PDFs are meant to provide complementarity to the
plot_sumz()
graphic about where there are key values along the environmental
gradient where many coincident change points occur regardless of the
sample.
Citations:
Baker, M.E. and R. S. King. 2010. A new method for detecting and interpreting biodiversity and ecological community thresholds. Methods in Ecology and Evolution 1: 25-43.Z
Baker, M.E. and R. S. King. 2013. Of TITAN and strawmen: an appeal for greater understanding of community data. Freshwater Science 32(2):489-506.
King, R.S. and C. J. Richardson. 2003. Integrating bioassessment and ecological risk assessment: an approach to developing numerical water-quality criteria. Environmental Management 31(6):795-809.
Dufrene, M. and P. Legendre. 1997. Species assemblages and indicator species: the need for a flexible asymmetrical approach. Ecological Monographs. 67:345-366.