burakDiagrams

The burakDiagrams package creates interactive 3D Burak Diagrams for evaluating climatological and hydrological simulations.

Burak Diagrams extend the geometric framework of the Taylor Diagram (Taylor, 2001) by incorporating bias as an additional axis and representing selected performance metrics as surfaces within the resulting 3D space.

Available diagrams

The package provides three main functions:

• bd_clim() — BD-Clim

  Evaluates climatological simulations by representing correlation, standard deviation, centered root mean-square difference, bias, and root mean-square difference.

• bd_hyd_nse() — BD-HydNSE

  Evaluates hydrological simulations by representing correlation, standard deviation, centered root mean-square difference, percent bias, and Nash-Sutcliffe efficiency.

• bd_hyd_kge() — BD-HydKGE

  Evaluates hydrological simulations by representing correlation, standard deviation, centered root mean-square difference, percent bias, and Kling-Gupta efficiency.

The diagrams are generated using the plotly package and can optionally be saved as interactive HTML files by specifying the fileName argument.

Installation

The package is currently under development and is not yet publicly available. Installation instructions will be provided following its official release.

BD-Clim example

library(burakDiagrams)

set.seed(123)

reference <- rnorm(
  30,
  mean = 10,
  sd = 2
)

models <- data.frame(
  Model_1 = reference + rnorm(30, sd = 0.5),
  Model_2 = reference * 1.1 + rnorm(30, sd = 0.8),
  Model_3 = reference * 0.9 + 1 + rnorm(30, sd = 0.6)
)

bd_clim(
  reference = reference,
  models = models,
  fileName = "bd_clim_example.html"
)

BD-HydNSE example

library(burakDiagrams)

set.seed(123)

reference <- rnorm(
  30,
  mean = 120,
  sd = 100
)

models <- data.frame(
  Model_1 = reference + rnorm(30, sd = 10),
  Model_2 = reference * 1.5 + rnorm(30, sd = 20),
  Model_3 = reference * 0.5 + rnorm(30, sd = 15)
)

bd_hyd_nse(
  reference = reference,
  models = models,
  fileName = "bd_hyd_nse_example.html"
)

BD-HydKGE example

library(burakDiagrams)

set.seed(123)

reference <- rnorm(
  30,
  mean = 120,
  sd = 100
)

models <- data.frame(
  Model_1 = reference + rnorm(30, sd = 10),
  Model_2 = reference * 1.5 + rnorm(30, sd = 20),
  Model_3 = reference * 0.5 + rnorm(30, sd = 15)
)

bd_hyd_kge(
  reference = reference,
  models = models,
  fileName = "bd_hyd_kge_example.html"
)

Surface resolution

The gridCount argument controls the approximate number of grid points used to construct the metric surfaces.

The default and minimum recommended value is 20000. A value of 200000 is recommended for smoother surfaces, although higher values increase computation time.

Smaller values may be useful during testing or when reducing computation time is more important than surface smoothness.

Citation

The manuscript introducing the Burak Diagrams is currently undergoing revision. Formal citation information for the package and the accompanying article will be added after the article is published.

References

Taylor, K. E. (2001). Summarizing multiple aspects of model performance in a single diagram. Journal of Geophysical Research: Atmospheres, 106(D7), 7183–7192. https://doi.org/10.1029/2000JD900719