Add dim_on_y to kwargs :axis

Useful to plot vertical columns

docs/make.jl

@@ -22,7 +22,11 @@ makedocs(;
         canonical = "https://CliMA.github.io/ClimaAnalysis.jl",
     ),
     checkdocs = :exports,
-    pages = ["Home" => "index.md", "APIs" => "api.md"],
+    pages = [
+        "Home" => "index.md",
+        "APIs" => "api.md",
+        "How do I?" => "howdoi.md",
+    ],
 )
 
 deploydocs(; repo = "github.com/CliMA/ClimaAnalysis.jl")

docs/src/howdoi.md

@@ -0,0 +1,20 @@
+# How-to guide and cookbook
+
+## How do I make a line plot with variable on the y axis instead of the x one?
+
+By default, the plotting functions in `CairoMakieExt` place the variable on the
+x axis. If you want it on the y axis instead (e.g., you are plotting the
+vertical profile of a column), you can pass the `dim_on_y = true` argument to
+the axis.
+
+For instance,
+```julia
+plot!(var, more_kwargs = Dict(:axis => [:dim_on_y = true]))
+```
+
+`ClimaAnalysis.Utils` provides a convenience function `kwargs` to specify
+arguments a little bit more easily without having to think about `Symbol`s too
+much.
+```julia
+plot!(var, more_kwargs = Dict(:axis => kwargs(dim_on_y = true))
+```

ext/CairoMakieExt.jl

@@ -241,6 +241,10 @@ Additional arguments to the plotting and axis functions
 The values are splatted in the relevant functions. Populate them with a
 Dictionary of `Symbol`s => values to pass additional options.
 
+A special argument that can be passed to `:axis` is `:dim_on_y`, which puts the dimension on
+the y axis instead of the variable. This is useful to plot columns with `z` on the vertical
+axis instead of the horizontal one.
+
 """
 function Visualize.line_plot1D!(
     fig::CairoMakie.Figure,
@@ -265,8 +269,21 @@ function Visualize.line_plot1D!(
     xlabel = get(axis_kwargs, :xlabel, "$dim_name [$dim_units]")
     ylabel = get(axis_kwargs, :ylabel, "$short_name [$units]")
 
+    x, y = dim, var.data
+
+    if get(axis_kwargs, :dim_on_y, false)
+        xlabel, ylabel = ylabel, xlabel
+        x, y = y, x
+        # dim_on_y is not a real keyword for Axis, so we have to remove it from the
+        # arguments. Since axis_kwargs is a Pairs object, we have to go through its
+        # underlying dictionary first
+        axis_kwargs_dict = Dict(axis_kwargs)
+        pop!(axis_kwargs_dict, :dim_on_y)
+        axis_kwargs = pairs(axis_kwargs_dict)
+    end
+
     CairoMakie.Axis(fig[p_loc...]; title, xlabel, ylabel, axis_kwargs...)
-    CairoMakie.lines!(dim, var.data; title, plot_kwargs...)
+    CairoMakie.lines!(x, y; plot_kwargs...)
 end
 
 """

test/CairoMakieExt.jl

@@ -135,4 +135,18 @@ using OrderedCollections
     )
     output_name = joinpath(tmp_dir, "test_plot3D_sliced_once.png")
     CairoMakie.save(output_name, fig)
+
+    # Test dim_on_y
+    ClimaAnalysis.Visualize.plot!(
+        fig,
+        var3D;
+        time = 1,
+        lon = 30,
+        more_kwargs = Dict(
+            :plot => ClimaAnalysis.Utils.kwargs(colormap = :inferno),
+            :axis => ClimaAnalysis.Utils.kwargs(dim_on_y = true),
+        ),
+    )
+    output_name = joinpath(tmp_dir, "test_plot3D_sliced_swapped.png")
+    CairoMakie.save(output_name, fig)
 end