display_rates: Display Forest Mortality and Recruitment Data with ggplot2
In EcoFoG/ForestData: Post-inventory processing of Forest Census datasets

Description Usage Arguments Details Value

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,
  ...
)

`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.

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

A ggplot2 graphical object. See ggplot2::ggplot.

EcoFoG/ForestData documentation built on Jan. 20, 2021, 10:04 a.m.