Skip to content

Commit 27c6d0e

Browse files
rafaqzrafaqz
authored
Fill out docs (#628)
* write some docs * more docs * document basedims * fix 1 dim print matrix
1 parent fd2988b commit 27c6d0e

23 files changed

+908
-463
lines changed

‎docs/src/.vitepress/config.mts‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -43,10 +43,11 @@ export default defineConfig({
4343
{ text: 'Selectors', link: '/selectors' },
4444
{ text: 'Integrations',
4545
items: [
46-
{text: 'Dependants', link: '/integrations' },
46+
{ text: 'Integrations', link: '/integrations' },
4747
{ text: 'Tables and DataFrames', link: '/tables' },
4848
{ text: 'Plots with Makie', link: '/plots' },
49-
{ text: 'CUDA & GPUs', link: '/cuda.md' },
49+
{ text: 'CUDA & GPUs', link: '/cuda' },
50+
{ text: 'DiskArrays', link: '/diskarrays' },
5051
{ text: 'Extending DimensionalData', link: '/ext_dd' },
5152
],
5253
},
@@ -69,7 +70,13 @@ export default defineConfig({
6970
{ text: 'Extending DimensionalData', link: '/ext_dd' },
7071
{ text: 'Plots with Makie', link: '/plots' },
7172
{ text: 'CUDA & GPUs', link: '/cuda' },
72-
{ text: 'API Reference', link: '/reference' },
73+
{ text: 'API Reference',
74+
items: [
75+
{ text: 'General Reference', link: '/api/reference' },
76+
{ text: 'Dimensions Reference', link: '/api/dimensions' },
77+
{ text: 'LookupArrays Reference', link: '/api/lookuparrays' },
78+
],
79+
},
7380
]
7481
}
7582
],

‎docs/src/api/dimensions.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
2+
# Dimensions
3+
4+
Dimensions are kept in the sub-module `Dimensions`.
5+
6+
```@docs
7+
Dimensions.Dimensions
8+
```
9+
10+
Dimensions have a type-heirarchy that organises plotting and
11+
dimension matching.
12+
13+
```@docs
14+
Dimensions.Dimension
15+
Dimensions.DependentDim
16+
Dimensions.IndependentDim
17+
Dimensions.XDim
18+
Dimensions.YDim
19+
Dimensions.ZDim
20+
Dimensions.TimeDim
21+
X
22+
Y
23+
Z
24+
Ti
25+
Dim
26+
Coord
27+
Dimensions.AnonDim
28+
```
29+
30+
### Exported methods
31+
32+
These are widely useful methods for working with dimensions.
33+
34+
```@docs
35+
dims
36+
dimnum
37+
hasdim
38+
otherdims
39+
val
40+
```
41+
42+
### Non-exported methods
43+
44+
```@docs
45+
Dimensions.label
46+
DimensionalData.format
47+
DimensionalData.dims2indices
48+
DimensionalData.selectindices
49+
```
50+
51+
### Primitive methods
52+
53+
These low-level methods are really for internal use, but
54+
can be useful for writing dimensional algorithms.
55+
56+
They are not guaranteed to keep their interface, but usually will.
57+
58+
```@docs
59+
DimensionalData.commondims
60+
DimensionalData.dim2key
61+
DimensionalData.key2dim
62+
DimensionalData.reducedims
63+
DimensionalData.swapdims
64+
DimensionalData.slicedims
65+
DimensionalData.comparedims
66+
DimensionalData.combinedims
67+
DimensionalData.sortdims
68+
DimensionalData.basetypeof
69+
DimensionalData.basedims
70+
DimensionalData.setdims
71+
DimensionalData.dimsmatch
72+
DimensionalData.dimstride
73+
DimensionalData.refdims_title
74+
```

‎docs/src/api/lookuparrays.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
2+
# LookupArrays
3+
4+
```@docs
5+
LookupArrays.LookupArrays
6+
```
7+
8+
```@docs
9+
LookupArrays.LookupArray
10+
LookupArrays.Aligned
11+
LookupArrays.AbstractSampled
12+
LookupArrays.Sampled
13+
LookupArrays.AbstractCyclic
14+
LookupArrays.Cyclic
15+
LookupArrays.AbstractCategorical
16+
LookupArrays.Categorical
17+
LookupArrays.Unaligned
18+
LookupArrays.Transformed
19+
Dimensions.MergedLookup
20+
LookupArrays.NoLookup
21+
LookupArrays.AutoLookup
22+
LookupArrays.AutoIndex
23+
```
24+
25+
The generic value getter `val`
26+
27+
```@docs
28+
LookupArrays.val
29+
```
30+
31+
Lookup methods:
32+
33+
```@docs
34+
bounds
35+
hasselection
36+
LookupArrays.index
37+
LookupArrays.sampling
38+
LookupArrays.span
39+
LookupArrays.order
40+
LookupArrays.locus
41+
LookupArrays.shiftlocus
42+
```
43+
44+
## Selectors
45+
46+
```@docs
47+
LookupArrays.Selector
48+
LookupArrays.IntSelector
49+
LookupArrays.ArraySelector
50+
At
51+
Near
52+
Between
53+
Touches
54+
Contains
55+
Where
56+
All
57+
```
58+
59+
## LookupArray traits
60+
61+
```@docs
62+
LookupArrays.LookupArrayTrait
63+
```
64+
65+
### Order
66+
67+
```@docs
68+
LookupArrays.Order
69+
LookupArrays.Ordered
70+
LookupArrays.ForwardOrdered
71+
LookupArrays.ReverseOrdered
72+
LookupArrays.Unordered
73+
LookupArrays.AutoOrder
74+
```
75+
76+
### Span
77+
78+
```@docs
79+
LookupArrays.Span
80+
LookupArrays.Regular
81+
LookupArrays.Irregular
82+
LookupArrays.Explicit
83+
LookupArrays.AutoSpan
84+
```
85+
86+
### Sampling
87+
88+
```@docs
89+
LookupArrays.Sampling
90+
LookupArrays.Points
91+
LookupArrays.Intervals
92+
```
93+
94+
### Loci
95+
96+
```@docs
97+
LookupArrays.Locus
98+
LookupArrays.Center
99+
LookupArrays.Start
100+
LookupArrays.End
101+
LookupArrays.AutoLocus
102+
```
103+
104+
## Metadata
105+
106+
```@docs
107+
LookupArrays.AbstractMetadata
108+
LookupArrays.Metadata
109+
LookupArrays.NoMetadata
110+
```

‎docs/src/api/reference.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
2+
# API Reference
3+
4+
## Arrays
5+
6+
```@docs
7+
AbstractDimArray
8+
DimArray
9+
```
10+
11+
Shorthand `AbstractDimArray` constructors:
12+
13+
```@docs
14+
Base.fill
15+
Base.rand
16+
Base.zeros
17+
Base.ones
18+
```
19+
20+
Functions for getting information from objects:
21+
22+
```@docs
23+
dims
24+
refdims
25+
metadata
26+
name
27+
```
28+
29+
## Multi-array datasets
30+
31+
```@docs
32+
AbstractDimStack
33+
DimStack
34+
```
35+
36+
## Dimension generators
37+
38+
```@docs
39+
DimIndices
40+
DimKeys
41+
DimPoints
42+
```
43+
44+
## Tables.jl/TableTraits.jl interface
45+
46+
```@docs
47+
DimensionalData.AbstractDimTable
48+
DimTable
49+
DimensionalData.DimColumn
50+
```
51+
52+
# Utility methods
53+
54+
For transforming DimensionalData objects:
55+
56+
```@docs
57+
set
58+
rebuild
59+
modify
60+
broadcast_dims
61+
broadcast_dims!
62+
mergedims
63+
unmergedims
64+
reorder
65+
```
66+
67+
Base methods
68+
69+
```@docs
70+
Base.cat
71+
Base.map
72+
Base.copy!
73+
Base.eachslice
74+
```
75+
76+
77+
Most base methods work as expected, using `Dimension` wherever a `dims`
78+
keyword is used. They are not allspecifically documented here.
79+
80+
## Name
81+
82+
```@docs
83+
DimensionalData.AbstractName
84+
DimensionalData.Name
85+
DimensionalData.NoName
86+
```
87+
88+
## Internal interface methods
89+
90+
```@docs
91+
DimensionalData.rebuild_from_arrays
92+
DimensionalData.show_main
93+
DimensionalData.show_after
94+
```

‎docs/src/basics.md‎

Lines changed: 2 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,5 @@
1-
# Getting Started
1+
# Installation
22

3-
`DimensionalData.jl` provides tools and abstractions for working with datasets that have named dimensions, and optionally a lookup index.
4-
5-
## Installation
63
````shell
74
julia>]
85
pkg> add DimensionalData
@@ -12,65 +9,11 @@ Check the installed version:
129

1310
````shell
1411
julia>]
15-
pkg> st
12+
pkg> status DimensionalData
1613
````
1714

1815
Start using the package:
1916

2017
````@example basics
2118
using DimensionalData
2219
````
23-
24-
## Philosophy
25-
26-
DimensionalData is a pluggable, generalised version of
27-
[AxisArrays.jl](https://github.com/JuliaArrays/AxisArrays.jl) with a cleaner
28-
syntax, and additional functionality found in NamedDims.jl. It has similar goals
29-
to pythons [xarray](http://xarray.pydata.org/en/stable/), and is primarily
30-
written for use with spatial data in [Rasters.jl](https://github.com/rafaqz/Rasters.jl).
31-
32-
::: info
33-
34-
- Clean, readable syntax. Minimise required parentheses, minimise of exported
35-
- Zero-cost dimensional indexing `a[Y(4), X(5)]` of a single value.
36-
methods, and instead extend Base methods whenever possible.
37-
- Plotting is easy: data should plot sensibly and correctly with useful labels, by default.
38-
- Least surprise: everything works the same as in Base, but with named dims. If
39-
a method accepts numeric indices or `dims=X` in base, you should be able to
40-
use DimensionalData.jl dims.
41-
- Minimal interface: implementing a dimension-aware type should be easy.
42-
- Maximum extensibility: always use method dispatch. Regular types over special
43-
syntax. Recursion over @generated. Always dispatch on abstract types.
44-
- Type stability: dimensional methods should be type stable _more often_ than Base methods
45-
- Functional style: structs are always rebuilt, and other than the array data,
46-
fields are not mutated in place.
47-
48-
:::
49-
50-
## Data types and the interface
51-
52-
DimensionalData.jl provides the concrete `DimArray` type. But its
53-
behaviours are intended to be easily applied to other array types.
54-
55-
::: details more
56-
57-
The main requirement for extending DimensionalData.jl is to define a `dims` method
58-
that returns a `Tuple` of `Dimension` that matches the dimension order
59-
and axis values of your data. Define `rebuild` and base methods for `similar`
60-
and `parent` if you want the metadata to persist through transformations (see
61-
the `DimArray` and `AbstractDimArray` types). A `refdims` method
62-
returns the lost dimensions of a previous transformation, passed in to the
63-
`rebuild` method. `refdims` can be discarded, the main loss being plot labels
64-
and ability to reconstruct dimensions in `cat`.
65-
66-
Inheriting from `AbstractDimArray` in this way will give nearly all the functionality
67-
of using `DimArray`.
68-
69-
:::
70-
71-
## LookupArrays and Dimensions
72-
73-
Sub modules `LookupArrays` and `Dimensions` define the behaviour of
74-
dimensions and their lookup index.
75-
76-
[`LookupArrays`](@ref) and [`Dimensions`](@ref).

0 commit comments

Comments
 (0)