Refactor and Simplify Documentation

docs/Project.toml

@@ -1,6 +1,7 @@
 [deps]
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 Bonito = "824d6782-a2ef-11e9-3a09-e5662e0c26f8"
+CFTime = "179af706-886a-5703-950a-314cd64e0468"
 CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"

docs/src/.vitepress/config.mts

@@ -11,16 +11,17 @@ export default defineConfig({
   cleanUrls: true,
   outDir: 'REPLACE_ME_DOCUMENTER_VITEPRESS', // This is required for MarkdownVitepress to work correctly...
   ignoreDeadLinks: true,
-  
+
   markdown: {
     math: true,
     config(md) {
       md.use(tabsMarkdownPlugin),
-      md.use(mathjax3)
+        md.use(mathjax3)
     },
     theme: {
       light: "github-light",
-      dark: "github-dark"}
+      dark: "github-dark"
+    }
   },
   themeConfig: {
     outline: 'deep',
@@ -34,73 +35,81 @@ export default defineConfig({
     },
     nav: [
       { text: 'Home', link: '/' },
-      { text: 'Getting Started', link: '/getting_started' },
-      { text: 'User Guide',
+      { text: 'Get Started', link: '/get_started' },
+      {
+        text: 'User Guide',
         items: [
-          { text: 'Creating YAXArrays and Datasets', link: '/UserGuide/creating' },
-          { text: 'Indexing and subsetting', link: '/UserGuide/indexing_subsetting' },
-          { text: 'Saving YAXArrays and Datasets', link: '/UserGuide/saving' },
-          { text: 'Setting chunks size', link: '/UserGuide/setchuncks' },
-          { text: 'Apply functions on YAXArrays', link: '/UserGuide/applyfunctions' },
-          { text: 'Create Cube from function', link: '/UserGuide/create_cube_from_function' },
-          { text: 'Group by', link: '/UserGuide/group_by' },
-          { text: 'Distributed computing', link: '/UserGuide/distributed' },
-          { text: 'Open NetCDF', link: '/UserGuide/openNetCDF' },
-          { text: 'Open Zarr (Store)', link: '/UserGuide/openZarr' },
-      ]},
-      { text: 'Tutorials',
+          { text: 'Read', link: '/UserGuide/read' },
+          { text: 'Create', link: '/UserGuide/create' },
+          { text: 'Write', link: '/UserGuide/write' },
+          { text: 'Subset', link: '/UserGuide/subset' },
+          { text: 'Compute', link: '/UserGuide/compute' },
+          { text: 'Group', link: '/UserGuide/group' },
+          { text: 'Combine', link: '/UserGuide/combine' },
+          { text: 'Chunk', link: '/UserGuide/chunk' },
+          { text: 'FAQ', link: '/UserGuide/faq' }
+        ]
+      },
+      {
+        text: 'Tutorials',
         items: [
           { text: 'Overview', link: '/tutorials/tutorial' },
           { text: 'Plotting maps', link: '/tutorials/plottingmaps' },
           { text: 'Mean Seasonal Cycle', link: '/tutorials/mean_seasonal_cycle' },
-          { text: 'ESDL studies',
+          {
+            text: 'ESDL studies',
             items: [
               { text: 'ESDL study 1', link: 'https://github.com/JuliaDataCubes/YAXArrays.jl/blob/master/docs/src/tutorials/esdl/examples_from_esdl_study_1.jl' },
               { text: 'ESDL study 2', link: 'https://github.com/JuliaDataCubes/YAXArrays.jl/blob/master/docs/src/tutorials/esdl/examples_from_esdl_study_2.jl' },
               { text: 'ESDL study 3', link: 'https://github.com/JuliaDataCubes/YAXArrays.jl/blob/master/docs/src/tutorials/esdl/examples_from_esdl_study_3.jl' },
               { text: 'ESDL study 4', link: 'https://github.com/JuliaDataCubes/YAXArrays.jl/blob/master/docs/src/tutorials/esdl/examples_from_esdl_study_4.jl' },
             ]
           },
-      ]},
-      { text: 'How do I?',
-      items: [
-        { text: 'How do I ...', link: '/HowdoI/howdoi' },
-        { text: 'Contribute to docs', link: '/HowdoI/contribute' },
-        { text: 'Contributors', link: '/contributors' }
-    ]},
+          { text: 'Other Tutorials', link: '/tutorials/other_tutorials' },
+        ]
+      },
+      {
+        text: 'Development',
+        items: [
+          { text: 'Contribute', link: 'development/contribute' },
+          { text: 'Contributors', link: 'development/contributors' }
+        ]
+      },
     ],
 
     sidebar: [
-      { text: 'Getting Started', link: '/getting_started' },
-      { text: 'User Guide',
+      { text: 'Get Started', link: '/get_started' },
+      { text: 'API Reference', link: 'api' },
+      {
+        text: 'User Guide',
         items: [
-          { text: 'Creating YAXArrays and Datasets', link: '/UserGuide/creating' },
-          { text: 'Indexing and subsetting', link: '/UserGuide/indexing_subsetting' },
-          { text: 'Saving YAXArrays and Datasets', link: '/UserGuide/saving' },
-          { text: 'Setting chunks size', link: '/UserGuide/setchuncks' },
-          { text: 'Apply functions on YAXArrays', link: '/UserGuide/applyfunctions' },
-          { text: 'Create Cube from function', link: '/UserGuide/create_cube_from_function' },
-          { text: 'Group by', link: '/UserGuide/group_by' },
-          { text: 'Distributed computing', link: '/UserGuide/distributed' },
-          { text: 'Open NetCDF', link: '/UserGuide/openNetCDF' },
-          { text: 'Open Zarr (Store)', link: '/UserGuide/openZarr' },
-      ]},
-      { text: 'Tutorials',
+          { text: 'Types', link: '/UserGuide/types' },
+          { text: 'Create', link: '/UserGuide/create' },
+          { text: 'Read', link: '/UserGuide/read' },
+          { text: 'Write', link: '/UserGuide/write' },
+          { text: 'Subset', link: '/UserGuide/subset' },
+          { text: 'Compute', link: '/UserGuide/compute' },
+          { text: 'Group', link: '/UserGuide/group' },
+          { text: 'Combine', link: '/UserGuide/combine' },
+          { text: 'Chunk', link: '/UserGuide/chunk' },
+          { text: 'FAQ', link: '/UserGuide/faq' }
+        ]
+      },
+      {
+        text: 'Tutorials',
         items: [
-          { text: 'Overview', link: '/tutorials/tutorial' },
           { text: 'Plotting maps', link: '/tutorials/plottingmaps' },
-          { text: 'Mean Seasonal Cycle', link: '/tutorials/mean_seasonal_cycle' }
-      ]},
-      { text: 'How do I?',
-      items: [
-        { text: 'How do I ...', link: '/HowdoI/howdoi' },
-        { text: 'Contribute to docs', link: '/HowdoI/contribute' },
-    ]},
-    { text: 'Contributors', link: '/contributors' },
-    { text: 'API',
-    items: [
-      { text: 'API Reference', link: 'api' },
-    ]},
+          { text: 'Mean Seasonal Cycle', link: '/tutorials/mean_seasonal_cycle' },
+          { text: 'Other Tutorials', link: '/tutorials/other_tutorials' },
+        ]
+      },
+      {
+        text: 'Development',
+        items: [
+          { text: 'Contribute', link: 'development/contribute' },
+          { text: 'Contributors', link: 'development/contributors' }
+        ]
+      },
     ],
     editLink: {
       pattern: 'https://github.com/JuliaDataCubes/YAXArrays.jl/edit/master/docs/src/:path'

docs/src/UserGuide/setchuncks.md → docs/src/UserGuide/chunk.md

@@ -1,4 +1,4 @@
-# Set chunks
+# Chunk YAXArrays
 
 > [!IMPORTANT]
 > Thinking about chunking is important when it comes to analyzing your data, because in most situations this will not fit into memory, hence having the fastest read access to it is crucial for your workflows. For example, for geo-spatial data do you want fast access on time or space, or... think about it.

docs/src/UserGuide/combine.md

@@ -0,0 +1,33 @@
+# Combine YAXArrays
+
+Data is often scattered across multiple files and corresponding arrays, e.g. one file per time step.
+This section describes methods on how to combine them into a single YAXArray.
+
+## Concatenate YAXArrays along an existing dimension
+
+Here we use `cat` to combine two arrays consisting of data from the first and the second half of a year into one single array containing the whole year.
+We glue the arrays along the first dimension using `dims = 1`:
+The resulting array `whole_year` still has one dimension, i.e. time, but with 12 instead of 6 elements.
+
+````@example cat
+using YAXArrays
+
+first_half = YAXArray((Dim{:time}(1:6),), rand(6))
+second_half = YAXArray((Dim{:time}(7:12),), rand(6))
+whole_year = cat(first_half, second_half, dims = 1)
+````
+
+## Combine YAXArrays along a new dimension
+
+Here we use `concatenatecubes` to combine two arrays of different variables that share the same time dimension.
+The resulting array `combined` has an additional dimension `variable` indicating from which array the element values originates.
+
+````@example concatenatecubes
+using YAXArrays
+
+temperature = YAXArray((Dim{:time}(1:6),), rand(6))
+precipitation = YAXArray((Dim{:time}(1:6),), rand(6))
+cubes = [temperature,precipitation]
+var_axis = Dim{:variable}(["temp", "prep"])
+combined = concatenatecubes(cubes, var_axis)
+````

docs/src/UserGuide/compute.md

@@ -0,0 +1,102 @@
+# Compute YAXArrays
+
+This section describes how to create new YAXArrays by performing operations on them.
+
+- Use [arithmetics](#Arithmetics) to add or multiply numbers to each element of an array
+- Use [map](#map) to apply a more complex functions to every element of an array
+- Use [mapslices](#mapslices) to reduce a dimension, e.g. to get the mean over all time steps
+- Use [mapCube](#mapCube) to apply complex functions on an array that may change any dimensions
+
+
+Let's start by creating an example dataset:
+
+````@example compute
+using YAXArrays
+using Dates
+
+axlist = (
+    Dim{:time}(Date("2022-01-01"):Day(1):Date("2022-01-30")),
+    Dim{:lon}(range(1, 10, length=10)),
+    Dim{:lat}(range(1, 5, length=15)),
+)
+data = rand(30, 10, 15)
+properties = Dict(:origin => "user guide")
+a = YAXArray(axlist, data2, properties)
+````
+
+## Modify elements of a YAXArray
+
+````@example compute
+a[1,2,3]
+````
+
+````@example compute
+a[1,2,3] = 42
+````
+
+````@example compute
+a[1,2,3]
+````
+
+::: warning
+
+Some arrays, e.g. those saved in a cloud object storage are immutable making any modification of the data impossible.
+
+:::
+
+
+## Arithmetics
+
+Add a value to all elements of an array and save it as a new array:
+
+````@example compute
+a2 = a .+ 5
+````
+
+````@example compute
+a2[1,2,3] == a[1,2,3] + 5
+````
+
+## map
+
+Apply a function on every element of an array individually:
+
+````@example compute
+offset = 5
+map(a) do x
+    (x + offset) / 2 * 3
+end
+````
+
+This keeps all dimensions unchanged.
+Note, that here we can not access neighboring elements.
+In this case, we can use `mapslices` or `mapCube` instead.
+Each element of the array is processed individually.
+
+The code runs very fast, because `map` applies the function lazily.
+Actual computation will be performed only on demand, e.g. when elements were explicitly requested or further computations were performed.
+
+
+## mapslices
+
+Reduce the time dimension by calculating the average value of all time points:
+
+````@example compute
+import Statistics: mean
+mapslices(mean, a, dims="Time")
+````
+There is no time dimension left, because there is only one value left after averaging all time steps.
+We can also calculate spatial means resulting in one value per time step:
+
+````@example compute
+import Statistics: mean
+mapslices(mean, a, dims=("lat", "lon"))
+````
+
+## mapCube
+
+
+
+## Distributed Computation
+
+parallel