Merge pull request #503 from JuliaDataCubes/la/merge_xcompute

Author: lazarusA

docs/make.jl

@@ -17,9 +17,9 @@ makedocs(; sitename="YAXArrays.jl",
     )
 # To edit the sidebar, you must edit `docs/src/.vitepress/config.mts`.
 
-deploydocs(; 
+DocumenterVitepress.deploydocs(; 
     repo="github.com/JuliaDataCubes/YAXArrays.jl.git", # this must be the full URL!
-    target="build", # this is where Vitepress stores its output
+    target=joinpath(@__DIR__, "build"),
     branch = "gh-pages",
     devbranch="master",
     push_preview = true

docs/src/.vitepress/config.mts

@@ -91,6 +91,9 @@ export default defineConfig({
   ],
   // ignoreDeadLinks: true,
   vite: {
+    define: {
+      __DEPLOY_ABSPATH__: JSON.stringify('REPLACE_ME_DOCUMENTER_VITEPRESS_DEPLOY_ABSPATH'),
+    },
     build: {
       assetsInlineLimit: 0, // so we can tell whether we have created inlined images or not, we don't let vite inline them
     },

docs/src/UserGuide/compute.md

@@ -147,6 +147,30 @@ note that the following can be extended to arbitrary `YAXArrays` with additional
 
 Let's generate a new `cube` using `mapCube` and saving the output directly into disk.
 
+:::tabs
+
+== xmap (DAE)
+
+````@ansi mapCube
+r = f.(lon_yax, lat_yax, time_yax)
+````
+
+or as 
+
+````@ansi mapCube
+r = xmap(f, lon_yax, lat_yax, time_yax, output=XOutput(outtype=Float32), inplace=false)
+````
+
+and triggering the computation and saving to `zarr` is done with `compute_to_zarr`:
+
+````@ansi mapCube
+gen_cube = compute_to_zarr(Dataset(layer=r), "my_gen_cube.zarr", overwrite=true, max_cache=1e9)
+````
+
+note that it takes as input a `Dataset`.
+
+== mapCube
+
 ````@ansi mapCube
 gen_cube = mapCube(g, (lon_yax, lat_yax, time_yax);
     indims = (InDims(), InDims(), InDims("time")),
@@ -163,6 +187,7 @@ Note that currently the `time` axis in the output cube goes first.
 :::
 
 
+
 Check that it is working
 
 ````@ansi mapCube
@@ -233,26 +258,49 @@ end
 f1(xin) = xin + 1
 f2(xin) = xin + 2
 ````
+
+````@example outdims
+properties_one = Dict{String, Any}("name" => "plus_one")
+properties_two = Dict{String, Any}("name" => "plus_two");
+nothing # hide
+````
+
+:::tabs
+
+== xmap (DAE)
+
+````@example outdims
+output_one = XOutput(yax_test.time; properties=properties_one)
+output_two = XOutput(yax_test.time; properties=properties_two)
+output_flat = XOutput(;) 
+
+ds = xmap(one_to_many, yax_test⊘:time,
+    output=(output_one, output_two, output_flat)
+    );
+nothing # hide
+````
+
+== mapCube
+
 now, we define `InDims` and `OutDims`:
 
 ````@example outdims
 indims_one   = InDims("Time")
 # outputs dimension
-properties_one = Dict{String, Any}("name" => "plus_one")
-properties_two = Dict{String, Any}("name" => "plus_two")
-
 outdims_one = OutDims("Time"; properties=properties_one)
 outdims_two = OutDims("Time"; properties=properties_two)
 outdims_flat = OutDims(;) # it will get the default `layer` name if open as dataset
+nothing # hide
 ````
-
 ````@example outdims
 ds = mapCube(one_to_many, yax_test,
     indims = indims_one,
     outdims = (outdims_one, outdims_two, outdims_flat));
 nothing # hide
 ````
 
+:::
+
 let's see the second output
 
 ````@example outdims
@@ -278,17 +326,36 @@ function many_to_many(xout_one, xout_two, xout_flat, xin_one, xin_two, xin_drei)
     return nothing
 end
 f2mix(xin_xyt, xin_xy) = xin_xyt - xin_xy
+nothing # hide
 ````
 
+:::tabs
+
+== xmap (DAE)
+
+````@example outdims
+output_time = XOutput(yax_test.time)
+output_flat = XOutput()
+
+r1, r2, r3 = xmap(many_to_many, yax_test⊘:time, yax_2d, yax_test⊘"time",
+    output =(output_time, output_time, output_flat), inplace=true);
+dsout = Dataset(many_to_many_two=r2)
+
+compute_to_zarr(dsout, "test_mm.zarr", overwrite=true)
+````
+
+== mapCube
+
 #### Specify path in OutDims
 
 ````@example outdims
 indims_one   = InDims("Time")
 indims_2d   = InDims() # ? it matches only to the other 2 dimensions and uses the same values for each time step
 properties = Dict{String, Any}("name"=> "many_to_many_two")
 outdims_one = OutDims("Time")
-outdims_two = OutDims("Time"; path = "test_mm.zarr", properties)
-outdims_flat = OutDims()
+outdims_two = OutDims("Time"; path = "test_mm.zarr", properties, overwrite=true)
+outdims_flat = OutDims();
+nothing # hide
 ````
 
 ````@example outdims
@@ -304,6 +371,9 @@ And we can open the one that was saved directly to disk.
 ds_mm = open_dataset("test_mm.zarr")
 ````
 
+:::
+
+
 ### Different InDims names
 
 Here, the goal is to operate at the pixel level (longitude, latitude), and then apply the corresponding function to the extracted values. Consider the following toy cubes:
@@ -322,8 +392,11 @@ and
 Random.seed!(123)
 data = rand(3.0:5.0, 5, 4, 3)
 
-axlist = (YAX.time(Date("2022-01-01"):Day(1):Date("2022-01-05")),
-    lon(1:4), lat(1:3),)
+axlist = (
+    YAX.time(Date("2022-01-01"):Day(1):Date("2022-01-05")),
+    lon(1:4),
+    lat(1:3),
+    )
 
 properties = Dict("description" => "multi dimensional test cube")
 yax_test = YAXArray(axlist, data, properties)
@@ -345,12 +418,26 @@ end
 
 with the final mapCube operation as follows
 
+:::tabs
+
+== xmap (DAE)
+
+````@example outdims
+ds = xmap(mix_time_depth, yax_test ⊘ :time, yax_2d ⊘ :depth,
+    output = XOutput(yax_test.time), inplace=false)
+````
+
+== mapCube
+
 ````@example outdims
 ds = mapCube(time_depth, (yax_test, yax_2d),
     indims = (InDims("Time"), InDims("depth")), # ? anchor dimensions and then map over the others.
     outdims = OutDims("Time"))
 ````
 
+:::
+
+
 - TODO:
     - Example passing additional arguments to function. 
     - MovingWindow
@@ -463,9 +550,27 @@ end
      output[:] .= mean(pixel)
 end
 
+````
+
+:::tabs
+
+== xmap (DAE)
+
+````julia
+meantime = xmap(mymean, a⊘:time)
+# and save!
+compute_to_zarr(Dataset(time_mean=meantime), tempname())
+````
+
+== mapCube
+
+````julia
 mapCube(mymean, a, indims=InDims("time"), outdims=OutDims())
 ````
 
+:::
+
+
 In the last example, `mapCube` was used to map the `mymean` function. `mapslices` is a convenient function that can replace `mapCube`, where you can omit defining an extra function with the output argument as an input (e.g. `mymean`). It is possible to simply use `mapslice`
 
 ````julia