From aba4e97fc987cbb94ea3c20f0966b5bfc0706adb Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Sat, 11 Jan 2025 11:53:58 -0100 Subject: [PATCH] A bit more documentation on auto things and lookups and format (#898) --- docs/src/extending_dd.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/src/extending_dd.md b/docs/src/extending_dd.md index a4dcc5cce..4a8762b7b 100644 --- a/docs/src/extending_dd.md +++ b/docs/src/extending_dd.md @@ -7,7 +7,7 @@ Nearly everything in DimensionalData.jl is designed to be extensible. - `AbstractDimStack` is easily extended to custom mixed array datasets. `RasterStack` or `ArViZ.Dataset` are examples. - `Lookup` can have new types added, e.g. to `AbstractSampled` or - `AbstractCategorical`. `Rasters.Projected` is a lookup that knows + `AbstractCategorical`. For example, `Rasters.Projected` is a lookup that knows its coordinate reference system, but otherwise behaves as a regular `Sampled` lookup. @@ -16,7 +16,7 @@ Nearly everything in DimensionalData.jl is designed to be extensible. ## `dims` Objects extending DimensionalData.jl that have dimensions must return -a `Tuple` of constructed `Dimension`s from `dims(obj)`. +a `Tuple` of constructed `Dimension`s from `dims(obj)`, like `(X(), Y())`. ### `Dimension` axes @@ -44,7 +44,7 @@ implemented. ## `rebuild` Rebuild methods are used to rebuild immutable objects with new field values, -in a way that is more flexible and extensible than just using ConstructionBase.jl +in a more flexible and extensible way than just using ConstructionBase.jl reconstruction. Developers can choose to ignore some of the fields passed by `rebuild`. @@ -85,11 +85,14 @@ format(dims, array) This lets DimensionalData detect the lookup properties, fill in missing fields of a `Lookup`, pass keywords from `Dimension` to detected `Lookup` constructors, and accept a wider range of dimension inputs like tuples of `Symbol` -and `Type`. +and `Type`. The way you indicate that something needs to be filled is by using the `Auto` types, +like [`AutoOrder`](@ref) or [`AutoSampling`](@ref) Not calling `format` in the outer constructors of an `AbstractDimArray` has undefined behaviour. +When creating lookup types, you need to define `DimensionalData.format` on your lookup type. + ## Interfaces.jl interface testing