Display Forest Mortality and Recruitment Data with ggplot2

display_rates take either a rates rates table -obtained with compute_rates- or two tables -mortality and recruitment, obtained with the corresponding compute_* functions-, and returns a nice graph according to user-specified parameters. This function requires the installation of the package ggplot2.

display_rates(
  mortality = NULL,
  recruitment = NULL,
  rates = NULL,
  type = "line",
  time_col = "time",
  color_col = "plot",
  faceting = FALSE,
  title = "Annual mortality and recruitment rates in function of census intervals.",
  subtitle = NULL,
  save_graph = FALSE,
  device = "png",
  path_save = file.path("ForestGraphs", paste0("annual_mortality_recruitment_", type,
    ".png")),
  name = "annual_recruitment_mortality.png",
  create_folder = FALSE,
  overwrite = FALSE,
  ...
)

Arguments

mortality	data.frame, output of `compute_mortality`.
recruitment	data.frame, output of `compute_recruitment`.
rates	data.frame, output of compute_rates or merged outputs of compute_mortality and compute_recruitment.
type	character, partially matching one of the following: "line", "histogram", "bar", "smooth". For the moment, only "line" is implemented, being the most relevant in this case. Corresponds to the type of graph to be done, for examples see `ggplot2` examples for `geom_line`, `geom_histogram`, `geom_bar` and `geom_smooth`.
time_col	Character, name of the column corresponding to census time
color_col	Character, name of the colomn used to define lines' colors, defaults to "Plot".
faceting	Character, name of the variable used for faceting -see after- but defaults to FALSE i.e. no faceting. NB: faceting refers to using a grouping variable to layout multiple plots, each corresponding to a category of the grouping variable. See details for a pratical explanation. The scales are free on the x axis: t correspond to several groups not necessarily having the same censusing temporal resolution; but are bound on the y-axis: the values are displayed on the same scale for comparison purposes.
title	Character,title of the graph.
subtitle	Character, subtitle of the graph. Defaults to `NULL`
save_graph	Logical, indicates whether the graph must be saved or not. Defaults to `FALSE`. If `TRUE`, please set the above described arguments in an appropriate way.
device	Relevant if `save_graph=TRUE`. Character, the graphical device to be used to save the graph.
path_save	Relevant if `save_graph=TRUE`. Character, a path indicating in which FOLDER the graph has to be saved.
name	Relevant if `save_graph=TRUE`. Character, the name of the folder containing the graph. It can be followd by the extension corresponding to the device - avoid .jpg for the jpeg device, use .jpeg instead. If the extension is missing, it is automatically added according to the selected device.
create_folder	Relevant if `save_graph=TRUE`. Logical, indicated whether the folders in the given path must be created in case they do not exist yet, or not.
overwrite	Relevant if `save_graph=TRUE`. Logical, indicating whether a file already existing under the same name must be overwritten, or kept. In the second case, the function aborts with an explicit error message.
...	Additionnal arguments to be passed to inernals, and ggplot2 utilities.

Value

A ggplot2 graphical object. See ggplot2::ggplot.

Details

About displaying multiple variables and avoiding unreadability:

Imagine a mortality and recruitment table computed for 3 species in 4 different plots, for 20 censuses, with corresponding columns named "Plot", "Species" and "time". Then, imagine displaying it using type = 'line'. All this information can be displayed in one call of display_rates, with different possible combinations:

- One graph per forest plot, with the color of each line segregating species, and the linetype segregating mortality and recruitement rates. This can be done with the arguments color_col = "Species" and faceting = "Plot", with the argument linetype not specified, thus internally defaulted.

- One graph per species, with the color of each line segregating plots, and the linetype segregating mortality and recruitement rates. The function call has thus the arguments color_col = "Species" and faceting = "Plot" again without speciying linetype.

Mortality and recruitment are defaultly segregated with different line types -e.g. full and dotted-, but this variable type can also be used to facet, yielding one plot for mortality rates and another for recruitment: for example, using linetype = "Species", color_col = "Plot" faceting = "rate".

In this case, using the linetype additionnal argument to display another variable must be done with some caution: if there are too many categories in this other variable, they would hardly -if not impossibly- be visually segregated by line types.

Detail of the additionnal arguments

The arguments corresponding to ... here encompass a limited number of parameters that are internally set if not specified. These parameters are passed to different sub-functions. Here is the detailed list of these arguments.

x.axis.name and y.axis.name are the axis labels to be passed to ggplot2::xlab and ggplot2::ylab

transparence is the scalar value of alpha in ggplot2::geom_* functions.

linewidth is the scalar value of size in gplot2::geom_line -to be used with type='line'.

Note that a variable's name -in the dataset- can also be provided to make vary these parameters according to the data. In such case, these arguments are passed to ggplot2::aes instead.

linetype is originally set to differenciate the rates -mortality and recruitment- for use with type = 'line'. It means that linetype="rate" -a name set internally as the data is reshaped to long format before displaying. This argument is originally passed to ggplot2::aes_string. In case the user wants to e.g. facet rates into two separate plots and use a constant linetype instead, they just have to specify e.g. linetype=1 and it will be passed to geom_line instead.

x.text.angle and y.text.angle is the angle of the axis ticks' labels. It is set to be 0 -horizontal- for y and 90 -vertical- for x, because it helps reading census times by avoiding overlaps. These are passed to gplot2::element_text within ggplot2::theme