Merge pull request #568 from JuliaDataCubes/continue_cf_conventions

Author: lazarusA

docs/src/.vitepress/config.mts

@@ -27,6 +27,7 @@ const navTemp = {
         { text: 'Create', link: '/UserGuide/create' },
         { text: 'Select', link: '/UserGuide/select' },
         { text: 'Compute', link: '/UserGuide/compute' },
+        { text: 'Plot', link: '/UserGuide/plot' },
         { text: 'Chunk', link: '/UserGuide/chunk' },
         { text: 'Cache', link: '/UserGuide/cache' },
         { text: 'Group', link: '/UserGuide/group' },
@@ -86,7 +87,7 @@ export default defineConfig({
   // cleanUrls: true,
   outDir: 'REPLACE_ME_DOCUMENTER_VITEPRESS', // This is required for MarkdownVitepress to work correctly...
   head: [
-    ['link', { rel: 'icon', href: '/favicon.ico' }],
+    ['link', { rel: 'icon', href: `${baseTemp.base}favicon.ico` }],
     ['script', {src: `${getBaseRepository(baseTemp.base)}versions.js`}],
     ['script', {src: `${baseTemp.base}siteinfo.js`}]
   ],

docs/src/UserGuide/plot.md

@@ -0,0 +1,74 @@
+# Plot YAXArrays
+
+This section describes how to visualize YAXArrays.
+See also the [Plotting maps tutorial](../tutorials/plottingmaps.md) to plot geospatial data.
+All [plotting capabilities](https://rafaqz.github.io/DimensionalData.jl/stable/plots) of `AbstractDimArray` apply to a `YAXArrays` as well, because every `YAXArray` is also an `AbstractDimArray`.
+
+## Plot a YAXArrray
+
+Create a simple YAXArray:
+
+```@example plot
+using CairoMakie
+using YAXArrays
+using DimensionalData
+
+data = collect(reshape(1:20, 4, 5))
+axlist = (X(1:4), Y(1:5))
+a = YAXArray(axlist, data)
+```
+
+Plot the entire array:
+
+```@example plot
+plot(a)
+```
+
+This will plot a heatmap, because the array is a matrix.
+
+Plot the first column:
+
+```@example plot
+plot(a[Y=1])
+```
+
+This results in a scatter plot, because the subarray is a vector.
+
+## Plot a YAXArrray with CF conventions
+
+[Climate and Forecast Metadata Conventions](https://cfconventions.org/) are used to generate appropriate labels for the plot whenever possible.
+This requires the YAXArray to have metadata properties like `standard_name` and `units`.
+
+Get a `Dataset` with CF meta data:
+
+```@example plot
+using NetCDF
+using Downloads: download
+
+path = download("https://archive.unidata.ucar.edu/software/netcdf/examples/tos_O1_2001-2002.nc", "example.nc")
+ds = open_dataset(path)
+```
+
+Plot the first time step of the sea surface temperature with CF metadata:
+
+```@example plot
+plot(ds.tos[time=1])
+```
+
+Time in [Climate and Forecasting (CF) conventions](https://cfconventions.org/Data/cf-conventions/cf-conventions-1.12/cf-conventions.html#time-coordinate-units) requires conversion before plotting, e.g., to plot the sea surface temperature over time at a given location (e.g. the null island):
+
+```@example plot
+a = ds.tos[lon = Near(0), lat = Near(0)]
+times = Ti(map(x -> DateTime(string(x)), a.time.val))
+a = YAXArray((times,), collect(a.data), a.properties)
+```
+
+```@example plot
+plot(a)
+```
+
+Or as as an explicit line plot:
+
+```@example plot
+lines(a)
+```

docs/src/tutorials/plottingmaps.md

@@ -134,7 +134,7 @@ nothing # hide
 and now plot
 
 ````@example AoG
-data(dim_data) * mapping(:lon, :lat; color=:value) * visual(Scatter) |> draw
+data(dim_data) * mapping(:lon, :lat; color=Symbol("Near-Surface Air Temperature")) * visual(Scatter) |> draw
 ````
 
 ::: warning
@@ -146,7 +146,7 @@ Note that we are using a `Scatter` type per point and not the `Heatmap` one. The
 set other attributes
 
 ````@example AoG
-plt = data(dim_data) * mapping(:lon, :lat; color=:value)
+plt = data(dim_data) * mapping(:lon, :lat; color=Symbol("Near-Surface Air Temperature"))
 draw(plt * visual(Scatter, marker=:rect), scales(Color = (; colormap = :plasma));
     axis = (width = 600, height = 400, limits=(0, 360, -90, 90)))
 ````
@@ -166,14 +166,15 @@ nothing # hide
 ````
 
 ````@example AoG
-plt = data(dim_time) * mapping(:lon, :lat; color = :value, layout = :time => nonnumeric)
+plt = data(dim_time) * mapping(:lon, :lat; color=Symbol("Near-Surface Air Temperature"), layout = :time => nonnumeric)
 draw(plt * visual(Scatter, marker=:rect))
 ````
 
 again, let's add some additional attributes
 
 ````@example AoG
-plt = data(dim_time) * mapping(:lon, :lat; color = :value, layout = :time => nonnumeric)
+plt = data(dim_time) * mapping(:lon, :lat; color=Symbol("Near-Surface Air Temperature"),
+    layout = :time => nonnumeric)
 draw(plt * visual(Scatter, marker=:rect), scales(Color = (; colormap = :magma));
     axis = (; limits=(0, 360, -90, 90)),
     figure=(; size=(900,600)))
@@ -182,14 +183,16 @@ draw(plt * visual(Scatter, marker=:rect), scales(Color = (; colormap = :magma));
 most [Makie plot functions](https://docs.makie.org/stable/reference/plots/overview) should work. See `lines` for example
 
 ````@example AoG
-plt = data(dim_data[lon=50..100]) * mapping(:lat, :value => "tas"; color=:value => "tas")
+plt = data(dim_data[lon=50..100]) * mapping(:lat, Symbol("Near-Surface Air Temperature") => "tas";
+    color=Symbol("Near-Surface Air Temperature") => "tas")
 draw(plt * visual(Lines); figure=(; size=(650,400)))
 ````
 
 or faceting them
 
 ````@example AoG
-plt = data(dim_data[lon=50..59]) * mapping(:lat, :value => "tas"; color=:value => "tas",
+plt = data(dim_data[lon=50..59]) * mapping(:lat, Symbol("Near-Surface Air Temperature") => "tas";
+    color=Symbol("Near-Surface Air Temperature") => "tas",
     layout = :lon => nonnumeric)
 draw(plt * visual(Lines); figure=(; size=(650,400)))
 ````
@@ -204,7 +207,7 @@ dim_series = c[time=DateTime("2015-01-01") .. DateTime("2015-01-04"), lon = 150
 and plot
 
 ````@example AoG
-plt = data(dim_series) * mapping(:time, :value => "tas"; color=:lon => nonnumeric)
+plt = data(dim_series) * mapping(:time, Symbol("Near-Surface Air Temperature") => "tas"; color=:lon => nonnumeric)
 draw(plt * visual(ScatterLines), scales(Color = (; palette = :tableau_colorblind));
     figure=(; size=(800,400)))
 ````
@@ -214,7 +217,7 @@ draw(plt * visual(ScatterLines), scales(Color = (; palette = :tableau_colorblind
 Basic statistical [analysis](https://aog.makie.org/stable/generated/analyses/) can also be done, for example:
 
 ````@example AoG
-specs = data(dim_data[lat=50..55]) * mapping(:lon, :value => "tas"; color=:lat => nonnumeric)
+specs = data(dim_data[lat=50..55]) * mapping(:lon, Symbol("Near-Surface Air Temperature") => "tas"; color=:lat => nonnumeric)
 specs *= (smooth() + visual(Scatter))
 draw(specs;  figure=(; size=(700,400)))
 ````