Skip to contents

Plot Occurrence Trends or Range Size Trends for Individual Species

Source: R/plot_methods.R
plot_species_ts.Rd

Creates time series plots of species occurrences or species range sizes, with an optional smoothed trendline, and visualizes uncertainty.

Usage

plot_species_ts(
  x,
  species = NULL,
  single_plot = TRUE,
  min_year = NULL,
  max_year = NULL,
  title = "auto",
  auto_title = NULL,
  y_label_default = NULL,
  suppress_y = FALSE,
  smoothed_trend = TRUE,
  linecolour = NULL,
  linealpha = 0.8,
  ribboncolour = NULL,
  ribbonalpha = 0.2,
  error_alpha = 1,
  trendlinecolour = NULL,
  trendlinealpha = 0.5,
  envelopecolour = NULL,
  envelopealpha = 0.2,
  smooth_cialpha = 1,
  point_line = c("point", "line"),
  pointsize = 2,
  linewidth = 1,
  ci_type = c("error_bars", "ribbon"),
  error_width = 1,
  error_thickness = 1,
  smooth_linetype = c("solid", "dashed", "dotted", "dotdash", "longdash", "twodash"),
  smooth_linewidth = 1,
  smooth_cilinewidth = 1,
  gridoff = FALSE,
  x_label = NULL,
  y_label = NULL,
  x_expand = NULL,
  y_expand = NULL,
  x_breaks = 10,
  y_breaks = 6,
  title_wrap_length = 60
)

Arguments

x

An 'indicator_ts' object containing time series of indicator values matched to species names and/or taxon keys.

species

Species you want to map occurrences for. Can be either numerical taxonKeys or species names. Partial species names can be used (the function will try to match them).

single_plot

By default all species occurrence time series will be combined into a single multi-panel plot. Set this to FALSE to plot each species separately.

min_year

(Optional) Earliest year to include in the plot.

max_year

(Optional) Latest year to include in the plot.

title

Plot title. Replace "auto" with your own title if you want a custom title or if calling the function manually.

auto_title

Text for automatic title generation, provided by an appropriate S3 method (if calling the function manually, leave as NULL).

y_label_default

Default label for the y-axis, provided by an appropriate S3 method (if calling the function manually, leave as NULL).

suppress_y

If TRUE, suppresses y-axis labels.

smoothed_trend

If TRUE, plot a smoothed trendline over time (stats::loess()).

linecolour

(Optional) Colour for the indicator line or points. Default is darkorange.

linealpha

Transparency for indicator line or points. Default is 0.8.

ribboncolour

(Optional) Colour for the bootstrapped confidence intervals. Default is goldenrod1. Set to "NA" if you don't want to plot the CIs.

ribbonalpha

Transparency for indicator confidence interval ribbon (if ci_type = "ribbon"). Default is 0.2.

error_alpha

Transparency for indicator error bars (if ci_type = "error_bar"). Default is 1.

trendlinecolour

(Optional) Colour for the smoothed trendline. Default is blue.

trendlinealpha

Transparency for the smoothed trendline. Default is 0.5.

envelopecolour

(Optional) Colour for the uncertainty envelope. Default is lightsteelblue.

envelopealpha

Transparency for the smoothed trendline envelope. Default is 0.2.

smooth_cialpha

Transparency for the smoothed lines forming the edges of the trendline envelope. Default is 1.

point_line

Whether to plot the indicator as a line or a series of points. Options are "line" or "point". Default is "point".

pointsize

Size of the points if point_line = "point". Default is 2.

linewidth

Width of the line if point_line = "line". Default is 1.

ci_type

Whether to plot bootstrapped confidence intervals as a "ribbon" or "error_bars". Default is "error_bars".

error_width

Width of error bars if ci_type = "error_bars". Default is 1. Note that unlike the default 'width' parameter in geom_errorbar, 'error_width' is NOT dependent on the number of data points in the plot. It is automatically scaled to account for this. Therefore the width you select will be consistent relative to the plot width even if you change 'min_year' and 'max_year'.

error_thickness

Thickness of error bars if ci_type = "error_bars". Default is 1.

smooth_linetype

Type of line to plot for smoothed trendline. Default is "solid".

smooth_linewidth

Line width for smoothed trendline. Default is 1.

smooth_cilinewidth

Line width for smoothed trendline confidence intervals. Default is 1.

gridoff

If TRUE, hides gridlines.

x_label

Label for the x-axis.

y_label

Label for the y-axis.

x_expand

(Optional) Expansion factor to expand the x-axis beyond the data. Left and right values are required in the form of c(0.1, 0.2). Default is c(0.05,0.05).

y_expand

(Optional) Expansion factor to expand the y-axis beyond the data. Lower and upper values are required in the form of c(0.1, 0.2). Default is c(0.05,0.05).

x_breaks

Integer giving desired number of breaks for x axis. (May not return exactly the number requested.)

y_breaks

Integer giving desired number of breaks for y axis. (May not return exactly the number requested.)

title_wrap_length

Maximum title length before wrapping to a new line.

Value

A ggplot object representing species range or occurrence time series plot(s). Can be customized using ggplot2 functions.

Examples

spec_occ_ts_mammals_denmark <- spec_occ_ts(example_cube_1,
                                        level = "country",
                                        region = "Denmark")
#> [1] "All values of t are equal to  1 \n Cannot calculate confidence intervals"
#> [1] "All values of t are equal to  2 \n Cannot calculate confidence intervals"
#> [1] "All values of t are equal to  1 \n Cannot calculate confidence intervals"
#> [1] "All values of t are equal to  2 \n Cannot calculate confidence intervals"
#> [1] "All values of t are equal to  1 \n Cannot calculate confidence intervals"
#> [1] "All values of t are equal to  1 \n Cannot calculate confidence intervals"
#> [1] "All values of t are equal to  1 \n Cannot calculate confidence intervals"
#> [1] "All values of t are equal to  1 \n Cannot calculate confidence intervals"
#> [1] "All values of t are equal to  1 \n Cannot calculate confidence intervals"
#> [1] "All values of t are equal to  1 \n Cannot calculate confidence intervals"
#> [1] "All values of t are equal to  22 \n Cannot calculate confidence intervals"
#> [1] "All values of t are equal to  1 \n Cannot calculate confidence intervals"
#> [1] "All values of t are equal to  1 \n Cannot calculate confidence intervals"
#> [1] "All values of t are equal to  1 \n Cannot calculate confidence intervals"
#> [1] "All values of t are equal to  1 \n Cannot calculate confidence intervals"
#> [1] "All values of t are equal to  1 \n Cannot calculate confidence intervals"
#> [1] "All values of t are equal to  1 \n Cannot calculate confidence intervals"
#> [1] "All values of t are equal to  2 \n Cannot calculate confidence intervals"
#> [1] "All values of t are equal to  1 \n Cannot calculate confidence intervals"
#> [1] "All values of t are equal to  1 \n Cannot calculate confidence intervals"
#> [1] "All values of t are equal to  3 \n Cannot calculate confidence intervals"
#> [1] "All values of t are equal to  1 \n Cannot calculate confidence intervals"
#> [1] "All values of t are equal to  1 \n Cannot calculate confidence intervals"
#> [1] "All values of t are equal to  1 \n Cannot calculate confidence intervals"
# default colours:
plot_species_ts(spec_occ_ts_mammals_denmark, c(2440728, 4265185))


# custom colours:
plot_species_ts(spec_occ_ts_mammals_denmark, c(2440728, 4265185),
        linecolour = "thistle",
        trendlinecolour = "forestgreen",
        envelopecolour = "lightgreen")