diff --git a/docs/make.jl b/docs/make.jl index a3383899..c0eee3b2 100644 --- a/docs/make.jl +++ b/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") diff --git a/docs/src/howdoi.md b/docs/src/howdoi.md new file mode 100644 index 00000000..1c71662a --- /dev/null +++ b/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)) +``` diff --git a/ext/CairoMakieExt.jl b/ext/CairoMakieExt.jl index 4bace06b..c62b85a7 100644 --- a/ext/CairoMakieExt.jl +++ b/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 """ diff --git a/test/CairoMakieExt.jl b/test/CairoMakieExt.jl index f8b3ae5b..d55f3c41 100644 --- a/test/CairoMakieExt.jl +++ b/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