update docs

docs/make.jl

@@ -2,7 +2,14 @@ using Documenter: Documenter, makedocs, deploydocs
 using CommonDataModel
 using Literate
 
-Literate.markdown("docs/src/tutorial1.jl","docs/src",execute = true, documenter = true)
+Literate.markdown(
+    "docs/src/tutorial1.jl","docs/src",
+    execute = true,
+    documenter = true,
+    # page already credits julia and Documenter; having an additional credit
+    # does not look nice
+    credit = false,
+)
 
 makedocs(;
     modules=[CommonDataModel],
@@ -12,9 +19,12 @@ makedocs(;
         prettyurls=get(ENV, "CI", "false") == "true",
         canonical="https://juliageo.github.io/CommonDataModel.jl",
         assets=String[],
+        footer = "Powered by [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl), [Literate.jl](https://github.com/fredrikekre/Literate.jl) and the [Julia Programming Language](https://julialang.org/)"
+
     ),
     pages=[
         "Home" => "index.md",
+        "Tutorials" => "tutorial1.md",
     ],
 )
 

docs/src/tutorial1.jl

@@ -12,10 +12,9 @@ using IntervalSets
 using NCDatasets
 using Statistics
 
-# Some helper functions for plotting with Makie
+# Some helper functions for plotting with Makie for plotting maps and timeseries.
 
 function nicemaps(v; timeindex = 1, lon = v["lon"][:], lat = v["lat"][:], title = nothing)
-
     fig, ax, hm = heatmap(lon,lat,v[:,:,timeindex],aspect_ratio = 1/cosd(mean(lat)))
     if !isnothing(title)
         ax.title[] = title
@@ -47,77 +46,101 @@ if !isfile(fname)
     download(url,fname)
 end
 
-# Open the dataset and access the variable sst
+# ## Select a subset by values from coordinate variables
+#
+# Open the dataset and access the variable `sst`. Select the domain from
+# 300°E to 360°E and 0°N to 46°N and the closest time instance to the
+# 1 April 2023.
 
 ds = NCDataset(fname)
 ncsst = ds["sst"]
 
-ncsst2 = @select(ncsst,300 <= lon <= 360 && 0 <= lat <= 46 && time ≈ DateTime(2023,12,24))
+ncsst2 = @select(ncsst,300 <= lon <= 360 && 0 <= lat <= 46 && time ≈ DateTime(2023,4,1))
 
 nicemaps(ncsst2, title = "NA SST")
 
+# One can also select a subset by indices and by values. Here we load the
+# first time instance and the domain from 300°E to 360°E and 0°N to 46°N
 
-# select by indices and by values
 ncsst_first = view(ncsst,:,:,1)
 ncsst_na = @select(ncsst_first,300 <= lon <= 360 && 0 <= lat <= 46)
 nicemaps(ncsst_na)
 
-# Select by month
+# Select all data from a given month
+
 ncsst_march = @select(ncsst,Dates.month(time) == 3)
-nicemaps(ncsst_march,title = "SST 1st March 2023")
+nicemaps(ncsst_march, timeindex = 1, title = "SST 1st March 2023")
 
 
-# Select by interval
+# Select multiple months using e.g. an interval (from [IntervalSets](https://github.com/JuliaMath/IntervalSets.jl)).
+# ∈ can be typed by writing `\in` directly followed by the TAB key.
+
 ncsst_march_april = @select(ncsst,Dates.month(time) ∈ 3..4)
 nicemaps(ncsst_march_april)
 
 # Use julia functions to extract data; here the `abs` function
 # polar regions north of 60°N and south of 60°S
+
 ncsst_polar = @select(ncsst,abs(lat) > 60)
 fig, ax, hm = heatmap(ncsst_polar[:,:,1])
 ax.title[] = "regions north of 60°N and south of 60°S ($(ncsst_polar[:time][1]))"
 Colorbar(fig[1,2],hm)
 
 
-# extract the time series of the closest point
+# Extract the time series of the closest point to a given point
+
 ncsst_timeseries = @select(ncsst,lon ≈ 330 && lat ≈ 38)
 lon = ncsst_timeseries["lon"][:]
 lat = ncsst_timeseries["lat"][:]
 nicetimeseries(ncsst_timeseries, title = "SST at $(lon) °E and $(lat) °N")
 
-# extract the time series of the closest point with a specified tolerance
+# Extract the time series of the closest point with a specified tolerance
 # If there is no data nearby an empty array is returned
+
 ncsst_outside = @select(ncsst,lon ≈ 330 && lat ≈ 93 ± 0.1)
 isempty(ncsst_outside)
 size(ncsst_outside)
 
 # Rather than selecting SST based on coordinates, we can also do the reverse:
-# select the longitude based on SST
+# select the longitude based on SST.
+# Find the longitudes where the SST exceeds 30 at the equator.
+# `sst` can contain missing values (e.g. on land).
+# `coalesce` is necessary here to replace the missing values by false in the boolean
+# expression.
+
 ds_equator = @select(ds,lat ≈ 0 && time ≈ DateTime(2023,1,1))
 lon_equator = @select(ds_equator,coalesce(sst > 30,false))["lon"]
 
-# the first 3 longitude where SST exceeds 30°C at the equator 2023-01-01
+# The first 3 longitude where SST exceeds 30°C at the equator for 2023-01-01
 
 lon_equator[1:3]
 
+# ## Grouping and reducing
+#
+# With the function ([`groupby`](@ref CommonDataModel.groupby) and macro [`@groupby`](@ref CommonDataModel.@groupby))
+# we can group the variable by a given criteria.
+# For each group, we can then apply a reducting function (`mean`, `sum`, `std`, ...).
+
+# For example group the SST by month and average per month:
 
-# group the SST by month and average
 sst_mean = mean(@groupby(ncsst,Dates.Month(time)))
-# or
-# sst_mean = mean(groupby(ncsst,:time => Dates.Month))
 
+# Instead of using the macro one can also use the function `groupby`:
+
+sst_mean = mean(groupby(ncsst,:time => Dates.Month))
 nicemaps(sst_mean, timeindex = 1, title = "Mean January SST")
 
 
 # Use custom julia function for grouping:
 # The [Atlantic hurricane season](https://en.wikipedia.org/w/index.php?title=Atlantic_hurricane_season&oldid=1189144955) is the period in a year, from June 1 through November 30, when tropical or subtropical cyclones are most likely to form in the North Atlantic Ocean.
+# The data will be grouped into two cases: false (time outside the Atlantic hurricane season) and true (time is within the Atlantic hurricane season).
+# We plot only the 2nd group.
 
 sst_na = @select(ncsst,300 <= lon <= 360 && 0 <= lat <= 46)
 sst_hs = mean(@groupby(sst_na,DateTime(year(time),6,1) <= time <= DateTime(year(time),11,30)))
 
 nicemaps(sst_hs,timeindex = 2, title = "mean SST during the Atlantic hurricane season")
 
-
 # Use a function without the `@groupby` macro
 
 is_atlantic_hurricane_season(time) =
@@ -140,4 +163,4 @@ is_atlantic_hurricane_season(time) =
 
 sst_my_mean = prob_hot(groupby(ncsst,:time => is_atlantic_hurricane_season));
 
-nicemaps(sst_my_mean,timeindex=2, title = "probability that temp. > 26°C during Atlantic hurricane season")
+nicemaps(sst_my_mean,timeindex=2, title = "probability(temp. > 26°C) during Atlantic hurricane season")