Bugle plot

Display a bugle plot of modelled pollution.

Usage

buglePlot(
  data = NULL,
  x = NULL,
  y = NULL,
  type = "error",
  pollutant = "PM10",
  groupby = NULL,
  title = NULL,
  subtitle = NULL
)

Arguments

data

a data.frame or data.table with Mean Fractional Error (MFE) or Mean Fractional Bias (MFB), and average values per station.

x

Character vector with the name of column with the concentration average values.

y

Character vector with the name of MFE or MFB column, i.e. the model performance.

type

character vector indicating if the plot is intended for MFE ("error") or MFB ("bias"). Default is "error".

pollutant

Character vector indicating pollutant name, to set the parameters for goal and criterion curves. It is currently not used and parameters for PM10 are used (see details for documentation). Default is "PM10".

groupby

Optional character vector indicating the grouping of data.

title

Character vector with the plot title.

subtitle

Character vector with plot subtitle.

Value

A ggplot2 graphic object.

Details

The bugle plot displays the model performance versus the observed average concentration along with the corresponding model performance goal and criterion.

The “average concentration” (x-axes in these plots) is the average concentration. It can be either the mean observed concentration or the average of the mean modelled and mean observed concentration. observed concentrations The model performance (y-axis) is either the Mean Fractional Error (MFE) or the Mean Fractional Bias (MFB). The goal and criterion are displayed as exponential curves as functions of the concentration. Criteria and goals are shown in red and green, respectively.

For further details, see Boylan, James W., and Armistead G. Russell. "PM and Light Extinction Model Performance Metrics, Goals, and Criteria for Three-Dimensional Air Quality Models". Atmospheric Environment 40, no. 26 (August 2006): 4946–59. https://doi.org/10.1016/j.atmosenv.2005.09.087 and Tesche, T.W., Ralph Morris, Gail Tonnesen, Dennis McNally, James Boylan, and Patricia Brewer. "CMAQ/CAMx Annual 2002 Performance Evaluation over the Eastern US". Atmospheric Environment 40, no. 26 (August 2006): 4906–19. https://doi.org/10.1016/j.atmosenv.2005.08.046.

The result of the function is a ggplot object which can be further customised with its directives.

Examples

if (FALSE) {
# *myData* is a `data.table` with *avg*, *mfe* and *city* columns.
buglePlot(myData, type = "error", x = "avg", y = "mfe", groupby = "city") +
    scale_x_continuous(name = NULL) +
    scale_y_continuous(name = NULL)
}