Visualizing OutputVars

This page is under construction, in the meantime, consult Visualize.

Masking part of the output in GeoMakie

When performing ocean or land simulations, it is often convenient to hide the other component (e.g., hide the ocean and focus on the continents). For GeoMakie plots, there is a direct way to accomplish this. In this section, we discuss this feature.

The main GeoMakie plots are Visualize.contour2D_on_globe! and Visualize.heatmap2D_on_globe!. Both these functions take a mask argument. By default, mask is nothing, meaning that the entire output is displayed on the globe. Alternatively, mask can be a collection of polygons that can be plotted with Makie.poly. ClimaAnalysis comes with the most important ones Visualize.oceanmask and Visualize.landmask, to hide ocean and continents respectively.

For example, suppose var it the variable we want to plot with a ocean mask

import ClimaAnalysis.Visualize: contour2D_on_globe!, oceanmask
import ClimaAnalysis.Utils: kwargs as ca_kwargs
import GeoMakie
import CairoMakie

fig = CairoMakie.Figure()

contour2D_on_globe!(fig,
                    var,
                    mask = oceanmask(),
                    more_kwargs = Dict(:mask => ca_kwargs(color = :blue)),
                   )

CairoMakie.save("myfigure.pdf", fig)

In this example, we plotted var on the globe and overplotted a blue ocean. ca_kwargs (Utils.kwargs) is a convenience function to pass keyword arguments more easily.

The output might look something like:

Plotting bias

After computing the bias between observational and simulation data, you may want to plot the bias and display information such as the root mean squared error (RMSE) and the global bias in the plot. To do this, you use the function plot_bias_on_globe!(fig, sim, obs). In the example below, we plot the bias between our simulation and some observations stored in ta_1d_average.nc.

import ClimaAnalysis
import ClimaAnalysis.Visualize: plot_bias_on_globe!
import GeoMakie
import CairoMakie

obs_var = ClimaAnalysis.OutputVar("ta_1d_average.nc")
sim_var = ClimaAnalysis.get(ClimaAnalysis.simdir("simulation_output"), "ta")

fig = CairoMakie.Figure()
plot_bias_on_globe!(fig, sim_var, obs_var)
CairoMakie.save("myfigure.pdf", fig)

The output produces something like:

We can also plot the bias using an ocean mask. This also means we compute the bias only over land.

import ClimaAnalysis
import ClimaAnalysis.Visualize: plot_bias_on_globe!, oceanmask
import GeoMakie
import CairoMakie

obs_var = ClimaAnalysis.OutputVar("ta_1d_average.nc")
sim_var = ClimaAnalysis.get(ClimaAnalysis.simdir("simulation_output"), "ta")

fig = CairoMakie.Figure()
plot_bias_on_globe!(fig,
                    var,
                    mask = oceanmask(),
                    more_kwargs = Dict(:mask => ca_kwargs(color = :blue)),
                   )
CairoMakie.save("myfigure.pdf", fig)

The output produces something like:

We can also plot the bias using a custom mask generated from make_lonlat_mask.

import ClimaAnalysis
import ClimaAnalysis.Visualize: plot_bias_on_globe!, oceanmask
import GeoMakie
import CairoMakie

mask_var = ClimaAnalysis.OutputVar("ocean_mask.nc")
mask_fn = ClimaAnalysis.generate_lonlat_mask(mask_var, NaN, 1.0)

obs_var = ClimaAnalysis.OutputVar("ta_1d_average.nc")
sim_var = ClimaAnalysis.get(ClimaAnalysis.simdir("simulation_output"), "ta")

fig = CairoMakie.Figure()
plot_bias_on_globe!(fig, var, mask = mask_fn)
CairoMakie.save("myfigure.pdf", fig)

The output produces something like:

Makie integration

In versions of ClimaAnalysis after v0.5.22, Makie functions can be used natively with OutputVars. In the example below, we use the CairoMakie backend and the CairoMakie.plot function to plot var. The type of the plot is automatically determined by the number of dimensions of the OutputVar. This supports OutputVar representing one dimensional or two dimensional data.

import ClimaAnalysis
import CairoMakie

CairoMakie.plot(var2d; colormap = :vik10)

You can also use other plotting functions in Makie such as heatmap and lines. In this example, we use heatmap to plot a OutputVar with the longitude and latitude dimensions and lines to plot a weighted latitude-averaged OutputVar. You can expect most plotting functions from Makie to work out of the box.

fig = CairoMakie.Figure(; size = (1000, 400))
# If no axis is provided, then a default axis is added
CairoMakie.heatmap(fig[1,1], var2d)

# You can make your own axis for more customization
lat_weighted_var = ClimaAnalysis.weighted_average_lat(var2d)
long_name = ClimaAnalysis.long_name(lat_weighted_var)
lon_units = ClimaAnalysis.dim_units(lat_weighted_var, "longitude")
short_name = ClimaAnalysis.short_name(lat_weighted_var)
var_units = ClimaAnalysis.units(lat_weighted_var)
ax = CairoMakie.Axis(fig[1, 2], title = long_name, xlabel = "Longitude ($lon_units)", ylabel = "$short_name ($var_units)")
CairoMakie.lines!(ax, lat_weighted_var; color = :blue)
fig