Display Forest Mortality and Recruitment Data with ggplot2

display_ba take a basal area table, obtained with thes compute_ba function, and returns a nice graph according to user-specified parameters. This function requires the installation of the package ggplot2.

display_ba(
  basal_area,
  type = "line",
  time_col = "time",
  color_col = "PlotSub",
  faceting = FALSE,
  title = "Basal area per hectare measured at each census",
  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

basal_area	data.frame, output of compute_ba, or if obtained another way, with a column named "basal_area_per_ha" or adding an argument variable.name, containing the corresponding column name, to the function call. Note that if the basal_area have been computed other than by plot, the arguments of this function must be set accordingly.
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

Details

Displaying multiple variables to avoid unreadability

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

- One graph per forest plot, with the color of each line segregating species. This can be done with the arguments color_col = "Species" and faceting = "Plot".

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

The linetype,defaults to 1 -i.e. solid line- but can also be used to display additional categories, simply adding e.g. linetype = "Species" to the function call. In this case, it must be done with some caution: if there are too many categories in the grouping 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 ggplot2::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_string instead.

display_ba originally uses linetype=1 with type = 'line'. It means that linetype is passed to ggplot2::geom_line as it is a constant scalar. In case the user wants to use it to differenciate groups, and use a variable linetype they just have to specify e.g. linetype="variable_name" and it will be passed to ggplot2::aes_string 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 ggplot2::element_text within ggplot2::theme.