Add RMSEVariable struct

This commit adds a struct called `RMSEVariable` which hold all the
information necessary for comparing the root mean square errors between
different models across different categories for a single variable.

Author: ph-kev

NEWS.md

@@ -276,6 +276,53 @@ plot_bias_on_globe!(fig, sim_var, obs_var)
 CairoMakie.save("myfigure.pdf", fig)
 ```
 
+### RMSEVariable
+
+To facilitate analysis of root mean squared errors (RMSEs) over different models and
+categories (e.g., seasons) for a single variable of interest, `RMSEVariable` is introduced in
+this release. See the examples below of constructing a `RMSEVariable` using a short name, a
+vector of model names, a vector of categories, and a dictionary mapping model names to units
+or a string of the name of the unit.
+
+```julia
+import ClimaAnalysis
+
+rmse_var = ClimaAnalysis.RMSEVariable("ta", ["ACCESS-CM2", "ACCESS-ESM1-5"])
+rmse_var = ClimaAnalysis.RMSEVariable(
+    "ta",
+    ["ACCESS-CM2", "ACCESS-ESM1-5"],
+    Dict("ACCESS-CM2" => "K", "ACCESS-ESM1-5" => "K"),
+)
+rmse_var = ClimaAnalysis.RMSEVariable(
+    "ta",
+    ["ACCESS-CM2", "ACCESS-ESM1-5"],
+    ["DJF", "MAM", "JJA", "SON", "ANN"],
+    Dict("ACCESS-CM2" => "K", "ACCESS-ESM1-5" => "K"),
+)
+# Convenience functions if models all share the same unit
+rmse_var = ClimaAnalysis.RMSEVariable(
+    "ta",
+    ["ACCESS-CM2", "ACCESS-ESM1-5"],
+    "K",
+)
+rmse_var = ClimaAnalysis.RMSEVariable(
+    "ta",
+    ["ACCESS-CM2", "ACCESS-ESM1-5"],
+    ["DJF", "MAM", "JJA", "SON", "ANN"],
+    "K",
+)
+rmse_var = ClimaAnalysis.RMSEVariable(
+    "ta",
+    ["ACCESS-CM2", "ACCESS-ESM1-5"],
+    ["DJF", "MAM", "JJA", "SON", "ANN"],
+    ones(2, 5),
+    "K",
+)
+```
+
+A `RMSEVariable` can be inspected using `model_names`, `category_names`, and `rmse_units`
+which provide the model names, the category names, and the units respectively.
+
 ## Bug fixes
 
 - Increased the default value for `warp_string` to 72.

docs/make.jl

@@ -30,6 +30,7 @@ makedocs(;
         "Home" => "index.md",
         "OutputVars" => "var.md",
         "Visualizing OutputVars" => "visualize.md",
+        "RMSEVariables" => "rmse_var.md",
         "APIs" => "api.md",
         "How do I?" => "howdoi.md",
     ],

docs/src/api.md

@@ -67,6 +67,21 @@ Var.global_mse
 Var.global_rmse
 ```
 
+## Leaderboard
+```@docs
+Leaderboard.RMSEVariable
+Leaderboard.RMSEVariable(short_name, model_names::Vector{String})
+Leaderboard.RMSEVariable(short_name, model_names::Vector{String}, units::Dict)
+Leaderboard.RMSEVariable(short_name, model_names::Vector{String}, category_names::Vector{String}, units::Dict)
+Leaderboard.RMSEVariable(short_name::String, model_names::Vector{String}, category_names::Vector{String}, RMSEs, units::Dict)
+Leaderboard.RMSEVariable(short_name, model_names::Vector{String}, units::String)
+Leaderboard.RMSEVariable(short_name, model_names::Vector{String}, category_names::Vector{String}, units::String)
+Leaderboard.RMSEVariable(short_name::String, model_names::Vector{String}, category_names::Vector{String}, RMSEs, units::String)
+Leaderboard.model_names
+Leaderboard.category_names
+Leaderboard.rmse_units
+```
+
 ## Utilities
 
 For development and not

docs/src/rmse_var.md

@@ -0,0 +1,66 @@
+# `RMSEVariable`s
+
+`RMSEVariable`s contain all the information needed to process and compare root mean squared
+errors (RMSEs) between different models and categories (e.g., seasons) for a single variable
+of interest.
+
+`ClimaAnalysis` provides several constructors for making a `RMSEVariable`. For all
+constructors, a short name and a vector of model names must be provided. If units are not
+provided, then each model will have no unit which denotes the missing unit. See the examples
+below where the constructor can take in a short name, a vector of model names, a vector of
+categories, and a dictionary mapping model names to units or a string of the name of the
+unit.
+
+```@example rmse_var
+import ClimaAnalysis
+
+rmse_var = ClimaAnalysis.RMSEVariable("ta", ["ACCESS-CM2", "ACCESS-ESM1-5"])
+rmse_var = ClimaAnalysis.RMSEVariable(
+    "ta",
+    ["ACCESS-CM2", "ACCESS-ESM1-5"],
+    Dict("ACCESS-CM2" => "K", "ACCESS-ESM1-5" => "K"),
+)
+rmse_var = ClimaAnalysis.RMSEVariable(
+    "ta",
+    ["ACCESS-CM2", "ACCESS-ESM1-5"],
+    ["DJF", "MAM", "JJA", "SON", "ANN"],
+    Dict("ACCESS-CM2" => "K", "ACCESS-ESM1-5" => "K"),
+)
+rmse_var = ClimaAnalysis.RMSEVariable(
+    "ta",
+    ["ACCESS-CM2", "ACCESS-ESM1-5"],
+    ["DJF", "MAM", "JJA", "SON", "ANN"],
+    ones(2, 5),
+    Dict("ACCESS-CM2" => "K", "ACCESS-ESM1-5" => "K"),
+)
+# Convenience functions if models all share the same unit
+rmse_var = ClimaAnalysis.RMSEVariable(
+    "ta",
+    ["ACCESS-CM2", "ACCESS-ESM1-5"],
+    "K",
+)
+rmse_var = ClimaAnalysis.RMSEVariable(
+    "ta",
+    ["ACCESS-CM2", "ACCESS-ESM1-5"],
+    ["DJF", "MAM", "JJA", "SON", "ANN"],
+    "K",
+)
+rmse_var = ClimaAnalysis.RMSEVariable(
+    "ta",
+    ["ACCESS-CM2", "ACCESS-ESM1-5"],
+    ["DJF", "MAM", "JJA", "SON", "ANN"],
+    ones(2, 5),
+    "K",
+)
+
+nothing # hide
+```
+
+The `RMSEVariable` can be inspected using `model_names`, `category_names`, and `rmse_units`
+which provide the model names, the category names, and the units respectively.
+
+```@repl rmse_var
+ClimaAnalysis.model_names(rmse_var)
+ClimaAnalysis.category_names(rmse_var)
+ClimaAnalysis.rmse_units(rmse_var)
+```

src/ClimaAnalysis.jl

@@ -10,6 +10,8 @@ include("Var.jl")
 @reexport using .Var
 include("Sim.jl")
 @reexport using .Sim
+include("Leaderboard.jl")
+@reexport using .Leaderboard
 
 include("Visualize.jl")
 @reexport using .Visualize