Add datawrangling tutorial

docs/make.jl

@@ -18,9 +18,9 @@ const EXAMPLES_DIR = joinpath(@__DIR__, "..", "examples")
 const OUTPUT_DIR   = joinpath(@__DIR__, "src/literated")
 
 to_be_literated = [
-    "single_column_os_papa_simulation.jl",
-    "one_degree_simulation.jl",
-    "near_global_ocean_simulation.jl"
+    # "single_column_os_papa_simulation.jl",
+    # "one_degree_simulation.jl",
+    # "near_global_ocean_simulation.jl"
 ]
 
 for file in to_be_literated
@@ -44,13 +44,15 @@ pages = [
     "Home" => "index.md",
 
     "Examples" => [
-        "Single-column ocean simulation" => "literated/single_column_os_papa_simulation.md",
-        "One-degree ocean--sea ice simulation" => "literated/one_degree_simulation.md",
-        "Near-global ocean simulation" => "literated/near_global_ocean_simulation.md",
+        # "Single-column ocean simulation" => "literated/single_column_os_papa_simulation.md",
+        # "One-degree ocean--sea ice simulation" => "literated/one_degree_simulation.md",
+        # "Near-global ocean simulation" => "literated/near_global_ocean_simulation.md",
         ],
 
     "Vertical grids" => "vertical_grids.md",
 
+    "Datasets" => "datasets.md",
+
     "Interface fluxes" => "interface_fluxes.md",
 
     "Library" => [
@@ -67,10 +69,10 @@ makedocs(sitename = "ClimaOcean.jl";
          pages,
          plugins = [bib],
          modules = [ClimaOcean],
-         doctest = true,
+         doctest = false,
          clean = true,
          warnonly = [:cross_references, :missing_docs],
-         checkdocs = :exports)
+         checkdocs = :none)
 
 @info "Clean up temporary .jld2 and .nc output created by doctests or literated examples..."
 

docs/src/datasets.md

@@ -0,0 +1,59 @@
+# Datasets
+
+The [`DataWrangling`](@ref ClimaOcean.DataWrangling) module allows us to use various datasets
+in ClimaOcean simulations.
+
+A central concept in the `DataWrangling` module is that of [`Metadata`](@ref).
+Metadata is a collection of information for the dataset, like the dataset's name, the variable
+that it involves, the date range, where the dataset is stored locally.
+
+For example, below we construct a metadata for the temperature variable from the EN4Monthly dataset.
+
+```@example metadata
+using ClimaOcean
+using Dates
+
+T_meta = Metadata(:temperature, dataset=EN4Monthly())
+```
+
+We can use `start_date` and `end_date` keyword arguments to select only some of the data
+available in the dataset. For example, to get only the first quarter of 2010 we do
+
+```@example metadata
+T_meta = Metadata(:temperature, dataset=EN4Monthly(),
+                  start_date = Date(2010, 1),
+                  end_date = Date(2010, 3))
+```
+
+We can use `set!` on a field or a model
+
+```@example metadata
+using Oceananigans
+
+Nx, Ny, Nz = 720, 360, 4
+underlying_grid = LatitudeLongitudeGrid(size=(Nx, Ny, Nz),
+                                        longitude = (0, 360),
+                                        latitude = (-90, 90),
+                                        z = (-5000, 0))
+
+bottom_height = regrid_bathymetry(underlying_grid)
+
+grid = ImmersedBoundaryGrid(underlying_grid, GridFittedBottom(bottom_height))
+
+T = CenterField(grid)
+```
+
+Note that `T` field above is empty. Now we can set it to the first time slice of `T_meta`.
+
+```@example metadata
+set!(T, first(T_meta))
+```
+
+Now `T` has values. Also note how `set!` above triggered downloading the dataset that
+corresponds to `T_meta`.
+
+```@example metadata
+using CairoMakie
+
+heatmap(view(T, :, :, grid.Nz))
+```

src/DataWrangling/DataWrangling.jl

@@ -1,3 +1,7 @@
+"""
+Incorporate various datasets to be used for bathymetry, initialization, forcing,
+restoring, or validation.
+"""
 module DataWrangling
 
 export Metadata, Metadatum, ECCOMetadatum, EN4Metadatum, all_dates, first_date, last_date

src/DataWrangling/ECCO/ECCO.jl

@@ -83,7 +83,6 @@ const ECCO2_url = "https://ecco.jpl.nasa.gov/drive/files/ECCO2/cube92_latlon_qua
 const ECCO4_url = "https://ecco.jpl.nasa.gov/drive/files/Version4/Release4/interp_monthly/"
 
 # The whole range of dates in the different dataset datasets
-all_dates(dataset::SomeECCODataset) = all_dates(dataset, nothing)
 all_dates(::ECCO4Monthly, variable) = DateTime(1992, 1, 1) : Month(1) : DateTime(2017, 12, 1)
 all_dates(::ECCO2Monthly, variable) = DateTime(1992, 1, 1) : Month(1) : DateTime(2024, 12, 1)
 all_dates(::ECCO2Daily,   variable) = DateTime(1992, 1, 1) : Day(1)   : DateTime(2024, 12, 31)