Package 'burakDiagrams'

Title: Interactive Burak Diagrams for Model Performance Evaluation
Description: Creates interactive 3D Burak Diagrams for evaluating climatological and hydrological simulations. The BD-Clim framework evaluates climatological simulations by representing correlation, standard deviation, centered root mean-square difference, bias, and root mean-square difference. The BD-HydNSE framework evaluates hydrological simulations using correlation, standard deviation, centered root mean-square difference, percent bias, and Nash-Sutcliffe efficiency. The BD-HydKGE framework evaluates hydrological simulations using correlation, standard deviation, centered root mean-square difference, percent bias, and Kling-Gupta efficiency. The frameworks extend the Taylor Diagram ( Taylor (2001) <doi:10.1029/2000JD900719> ) by introducing an orthogonal axis for bias and representing selected performance metrics as surfaces in the resulting 3D space. Nash-Sutcliffe efficiency was introduced by Nash and Sutcliffe (1970) <doi:10.1016/0022-1694(70)90255-6>, and Kling-Gupta efficiency was proposed by Gupta et al. (2009) <doi:10.1016/j.jhydrol.2009.08.003>. The diagrams are interactive and can optionally be saved as HTML files.
Authors: Omer Burak Akgun [aut, cre] (ORCID: <https://orcid.org/0000-0002-9856-9662>)
Maintainer: Omer Burak Akgun <[email protected]>
License: MIT + file LICENSE
Version: 0.1.0
Built: 2026-07-23 15:47:47 UTC
Source: https://github.com/cran/burakDiagrams

Help Index

Create a Burak Diagram for climatological simulations

Description

Creates an interactive 3D Burak Diagram for evaluating climatological simulations. The diagram represents model correlation, standard deviation, centered root mean-square difference, bias, and root mean-square difference within a 3D geometric framework.

Usage

bd_clim(
  reference,
  models,
  whichRMSDsurfaces = "default",
  gridCount = 20000,
  modelNames = "default",
  modelSymbols = "default",
  modelColors = "default",
  fileName = NULL,
  xlab = "Standard deviation",
  ylab = "",
  zlab = "Bias",
  surfaceOpacity = 0.2,
  refSDarc = FALSE,
  showSDarcs = TRUE
)

Arguments

reference

A numeric vector containing the reference or observed values.
models

A numeric matrix or data frame containing the simulated values. Each column represents a model, and each row must correspond to the same observation in reference.
whichRMSDsurfaces

A numeric vector specifying the RMSD surfaces to be displayed, or the character string "default" for automatically selected surfaces.
gridCount

A positive integer specifying the approximate number of grid points used to construct the metric surfaces. The default is 20000, which is also the minimum recommended value. For smoother surfaces, a value of 200000 is recommended. Larger values increase computation time.
modelNames

A character vector specifying the model names displayed in the legend, or the character string "default" to automatically use the column names of models. The vector must have the same length as the number of columns in models.
modelSymbols

A character vector specifying the Plotly marker symbols used for the models, or the character string "default" for automatically assigned symbols. Available symbols include "circle", "cross", "diamond", "square", "circle-open", "diamond-open", "square-open", and "x". The vector must have the same length as the number of columns in models. When custom symbols are supplied, custom colors must also be provided through modelColors.
modelColors

A character vector specifying the colors used for the models, or the character string "default" for automatically assigned colors. The vector must have the same length as the number of columns in models.
fileName

Either NULL or a character string specifying the path and file name of the HTML output (e.g., bd_clim.html). If NULL, the default, no HTML file is written.
xlab

A character string specifying the x-axis label.
ylab

A character string specifying the y-axis label.
zlab

A character string specifying the z-axis label.
surfaceOpacity

A numeric value between 0 and 1 specifying the opacity of the metric surfaces.
refSDarc

Logical. If TRUE, the reference standard-deviation arc is displayed.
showSDarcs

Logical. If TRUE, standard-deviation arcs are displayed.

Value

An interactive 3D Burak Diagram represented as htmlwidget. If fileName is not NULL, the diagram is also saved as an HTML file.

Examples

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,
  gridCount = 5000
)

Create a Burak Diagram for hydrological simulations with KGE

Description

Creates an interactive 3D Burak Diagram for evaluating hydrological simulations using the Kling-Gupta efficiency (KGE). The diagram represents model correlation, standard deviation, centered root mean-square difference, percent bias (PBias), and KGE within a 3D geometric framework.

Usage

bd_hyd_kge(
  reference,
  models,
  whichKGEsurfaces = c(0, 0.25, 0.5, 0.75),
  scalingFactor = c(1, 1, 1),
  gridCount = 20000,
  modelNames = "default",
  modelSymbols = "default",
  modelColors = "default",
  fileName = NULL,
  xlab = "Standard deviation",
  ylab = "",
  zlab = "PBias",
  surfaceOpacity = 0.2,
  CentRMSDcircles = TRUE,
  refSDarc = FALSE,
  showSDarcs = TRUE
)

Arguments

reference

A numeric vector containing the reference or observed values.
models

A numeric matrix or data frame containing the simulated values. Each column represents a model, and each row must correspond to the same observation in reference.
whichKGEsurfaces

A numeric vector specifying the KGE surfaces to be displayed. The default is c(0, 0.25, 0.5, 0.75).
scalingFactor

A numeric vector of length three containing the scaling factors applied to correlation, standard deviation ratio, and mean ratio, respectively. The first two values must be non-negative. The third value must be greater than zero because the mean ratio is represented along the z-axis. The default is c(1, 1, 1).
gridCount

A positive integer specifying the approximate number of grid points used to construct the metric surfaces. The default is 20000, which is also the minimum recommended value. For smoother surfaces, a value of 200000 is recommended. Larger values increase computation time.
modelNames

A character vector specifying the model names displayed in the legend, or the character string "default" to automatically use the column names of models. The vector must have the same length as the number of columns in models.
modelSymbols

A character vector specifying the Plotly marker symbols used for the models, or the character string "default" for automatically assigned symbols. Available symbols include "circle", "cross", "diamond", "square", "circle-open", "diamond-open", "square-open", and "x". The vector must have the same length as the number of columns in models. When custom symbols are supplied, custom colors must also be provided through modelColors.
modelColors

A character vector specifying the colors used for the models, or the character string "default" for automatically assigned colors. The vector must have the same length as the number of columns in models.
fileName

Either NULL or a character string specifying the path and file name of the HTML output (e.g., bd_clim.html). If NULL, the default, no HTML file is written.
xlab

A character string specifying the x-axis label.
ylab

A character string specifying the y-axis label.
zlab

A character string specifying the z-axis label.
surfaceOpacity

A numeric value between 0 and 1 specifying the opacity of the metric surfaces.
CentRMSDcircles

Logical. If TRUE, centered RMSD circles are displayed.
refSDarc

Logical. If TRUE, the reference standard-deviation arc is displayed.
showSDarcs

Logical. If TRUE, standard-deviation arcs are displayed.

Value

An interactive 3D Burak Diagram represented as htmlwidget. If fileName is not NULL, the diagram is also saved as an HTML file.

Examples

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,
  gridCount = 5000
)

Create a Burak Diagram for hydrological simulations with NSE

Description

Creates an interactive 3D Burak Diagram for evaluating hydrological simulations using the Nash-Sutcliffe efficiency (NSE). The diagram represents model correlation, standard deviation, centered root mean-square difference, percent bias (PBias), and NSE within a 3D geometric framework.

Usage

bd_hyd_nse(
  reference,
  models,
  whichNSEsurfaces = c(0, 0.25, 0.5, 0.75),
  gridCount = 20000,
  modelNames = "default",
  modelSymbols = "default",
  modelColors = "default",
  fileName = NULL,
  xlab = "Standard deviation",
  ylab = "",
  zlab = "PBias",
  surfaceOpacity = 0.2,
  CentRMSDcircles = TRUE,
  refSDarc = FALSE,
  showSDarcs = TRUE
)

Arguments

reference

A numeric vector containing the reference or observed values.
models

A numeric matrix or data frame containing the simulated values. Each column represents a model, and each row must correspond to the same observation in reference.
whichNSEsurfaces

A numeric vector specifying the NSE surfaces to be displayed. The default is c(0, 0.25, 0.5, 0.75).
gridCount

A positive integer specifying the approximate number of grid points used to construct the metric surfaces. The default is 20000, which is also the minimum recommended value. For smoother surfaces, a value of 200000 is recommended. Larger values increase computation time.
modelNames

A character vector specifying the model names displayed in the legend, or the character string "default" to automatically use the column names of models. The vector must have the same length as the number of columns in models.
modelSymbols

A character vector specifying the Plotly marker symbols used for the models, or the character string "default" for automatically assigned symbols. Available symbols include "circle", "cross", "diamond", "square", "circle-open", "diamond-open", "square-open", and "x". The vector must have the same length as the number of columns in models. When custom symbols are supplied, custom colors must also be provided through modelColors.
modelColors

A character vector specifying the colors used for the models, or the character string "default" for automatically assigned colors. The vector must have the same length as the number of columns in models.
fileName

Either NULL or a character string specifying the path and file name of the HTML output (e.g., bd_clim.html). If NULL, the default, no HTML file is written.
xlab

A character string specifying the x-axis label.
ylab

A character string specifying the y-axis label.
zlab

A character string specifying the z-axis label.
surfaceOpacity

A numeric value between 0 and 1 specifying the opacity of the metric surfaces.
CentRMSDcircles

Logical. If TRUE, centered RMSD circles are displayed.
refSDarc

Logical. If TRUE, the reference standard-deviation arc is displayed.
showSDarcs

Logical. If TRUE, standard-deviation arcs are displayed.

Value

An interactive 3D Burak Diagram represented as htmlwidget. If fileName is not NULL, the diagram is also saved as an HTML file.

Examples

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,
  gridCount = 5000
)