AbstractMetaArrays

module AbstractMetaArrays

A Julia package providing an abstract interface and utilities for arrays with attached metadata and optional column metadata.

Overview

AbstractMetaArrays defines the abstract type AbstractMetaArray, which extends the standard AbstractArray interface to support:

• Metadata: Arbitrary key-value pairs describing the array as a whole.
• Column Metadata: Metadata associated with individual columns or components (optional).

Concrete implementations (such as SimpleMetaArray) inherit from AbstractMetaArray and provide storage and trait-based control over metadata support.

Main Types

• AbstractMetaArray: Abstract type for meta arrays.
• AbstractMetaVector, AbstractMetaMatrix: Aliases for 1D and 2D meta arrays.
• SimpleMetaArray: A concrete implementation with full metadata and column metadata support.
• MetaType: Alias for the metadata dictionary type.

Traits

• ColMetadataTrait: Indicates if column metadata is supported.
• ColMetadataStyle: Controls read/write access to column metadata.
• MetadataStyle: Controls read/write access to array metadata.

Utilities

• create_metaarray: Helper for constructing metadata and column metadata dictionaries for new arrays.

Integration

The package integrates with DataAPI.jl for a standard metadata interface, and provides extensions for compatibility with packages like StaticArrays and StructArrays.

Example

using AbstractMetaArrays, StaticArrays

arr = SimpleMetaArray(SVector{3}(1,2,3), Dict("description" => ("test", :entry)), Dict(:x => Dict("unit" => ("m", :default))))
desc = metadata(arr, "description")  # returns "test"

See the documentation for details on implementing custom meta arrays and extending metadata support.

AbstractMetaArray{T,N,A<:AbstractArray{T,N}} <: AbstractArray{T,N}

AbstractMetaArray is an abstract type that represents a meta array with metadata and optional column metadata. It is a subtype of AbstractArray and provides a common interface for all meta arrays. All the concrete implementations of AbstractMetaArray should inherit from this type. The type parameters are:

• T: The element type of the array.
• N: The number of dimensions of the array.
• A: The concrete type of the array. It should be a subtype of AbstractArray{T,N}.

The concrete implementations of AbstractMetaArray should define the following fields:

• _data: The underlying data of the array. It should be a subtype of AbstractArray{T,N}.
• _metadata: The metadata of the array. It should be a dictionary with string keys and values of type Tuple{Any,Symbol}.
• _colmetadata: The column metadata of the array. It should be a dictionary with symbol keys and values of type MetaType.

The concrete implementations of AbstractMetaArray should also define the following traits:

• ColMetadataTrait: Defines if the meta array supports column metadata or not. It should be a subtype of ColMetadataTrait. By default, it is NoColMetadata().
• ColMetadataStyle: Defines the access to the column metadata (reading, writing, both, or none). It should be a subtype of ColMetadataStyle.
• MetadataTrait: Defines if the meta array supports metadata or not. It should be a subtype of MetadataTrait. By default, it is NoMetadata().

For simplicity a non exported function create_metaarray is defined to create the metadata and colmetadata for the meta array. It is used in the constructor of the meta array.

See also SimpleMetaArray for a concrete implementation of the AbstractMetaArray. create_metaarray for a helper function to create the metadata and colmetadata for the meta array. ColMetadataTrait for the trait that defines if the meta array supports column metadata or not. ColMetadataStyle for the trait that defines the access to the column metadata. MetadataStyle for the trait that defines the access to the metadata.

AbstractMetaMatrix{T}

Alias for AbstractMetaArray{T,2}. Represents a 2-dimensional meta array.

AbstractMetaVector{T}

Alias for AbstractMetaArray{T,1}. Represents a 1-dimensional meta array.

AbstractMetaArrays.ColMetadataStyle(x::Type) AbstractMetaArrays.ColMetadataStyle(x)

A trait function used to determine the column metadata support of a type or an instance x. This is used by the implementation of DataAPI.colmetadatasupport implemented by this module, to define reading and writing permissions for column metadata. Default behavior is to return ReadWriteColMetadata().

Note: If the ColMetadataTrait is NoColMetadata, this function will be ignored.

Arguments

• x::Type: A type to check for column metadata support.
• x: An instance to check for column metadata support.

Return

• ReadWriteColMetadata(): Indicates that the type or instance has read and write column metadata support.
• ReadOnlyColMetadata(): Indicates that the type or instance has read-only column metadata support.
• WriteOnlyColMetadata(): Indicates that the type or instance has write-only column metadata support.
• PrivateColMetadata(): Indicates that the type or instance does not have column metadata support.

See also: ColMetadataTrait for more information on column metadata support.

AbstractMetaArrays.ColMetadataTrait(x::Type) AbstractMetaArrays.ColMetadataTrait(x)

A trait function used to determine if a type or an instance x has column metadata associated with it. This can be used to dispatch on types or instances that support column metadata. Default behavior is to return NoColMetadata().

Arguments

• x::Type: A type to check for column metadata support.
• x: An instance to check for column metadata support.

Return

• HasColMetadata(): Indicates that the type or instance has column metadata support.
• NoColMetadata(): Indicates that the type or instance does not have column metadata support.

MetaType<: Dict{<:AbstractString,Tuple{Any,Symbol}}

Alias for the metadata type. It is a dictionary with string keys and values of type Tuple{Any,Symbol}.

AbstractMetaArrays.MetadataStyle(x::Type) AbstractMetaArrays.MetadataStyle(x)

A trait function used to determine the metadata support of a type or an instance x. This is used by the implementation of DataAPI.metadatasupport implemented by this module, to define reading and writing permissions for metadata. Default behavior is to return ReadWriteMetadata().

Arguments

• x::Type: A type to check for metadata support.
• x: An instance to check for metadata support.

Return

• ReadWriteMetadata(): Indicates that the type or instance has read and write metadata support.
• ReadOnlyMetadata(): Indicates that the type or instance has read-only metadata support.
• WriteOnlyMetadata(): Indicates that the type or instance has write-only metadata support.
• PrivateMetadata(): Indicates that the type or instance does not have metadata support.

SimpleMetaArray{T,N,A<:AbstractArray{T,N}} <: AbstractMetaArray{T,N,A<:AbstractArray{T,N}}

Concrete implementation of AbstractMetaArray for a simple array with metadata. This is a concrete type that can be used to create instances of AbstractMetaArray. It has metadata and colmetadata fields that are dictionaries with string keys and values of type Tuple{Any,Symbol}.

It uses the following traits:

AbstractMetaArrays.ColMetadataTrait(::Type{<:SimpleMetaArray}) = HasColMetadata() AbstractMetaArrays.ColMetadataStyle(::Type{<:SimpleMetaArray}) = ReadWriteColMetadata() AbstractMetaArrays.MetadataStyle(::Type{<:SimpleMetaArray}) = ReadWriteMetadata()

See also AbstractMetaArray for more information on the abstract type and its methods.

SimpleMetaArray{T,N}(data::A, metadata::DictOrNothing=nothing, colmetadata::Union{NTuple{N,DictOrNothing},DictOrNothing}=nothing) where {T,N,A<:AbstractArray{T,N}} =
SimpleMetaArray(data, metadata, colmetadata)

Construct a SimpleMetaArray with the given data, metadata and colmetadata.

Example

julia> using StaticArrays
julia> s=SimpleMetaArray(SVector{3}(1,1,1), Dict("description" => ("test array", :entry)),
              Dict("unit" => ("m", :default)))
3-element SimpleMetaArray{Int64, 1} with indices SOneTo(3):
 1
 1
 1

julia> metadata(s)
Dict{String, String} with 1 entry:
  "description" => "test array"

julia> colmetadata(s)
Dict{Symbol, Dict{String, String}} with 3 entries:
  :y => Dict("unit"=>"m")
  :z => Dict("unit"=>"m")
  :x => Dict("unit"=>"m")

SimpleMetaArray(T::Type, dims::Dims{N}, metadata::DictOrNothing=nothing, colmetadata::Union{NTuple{N,DictOrNothing},DictOrNothing}=nothing) where N
SimpleMetaArray(A::Type{<:AbstractArray{T,N}}, dims::Dims{N}, metadata::DictOrNothing=nothing, colmetadata::Union{NTuple{N,DictOrNothing},DictOrNothing}=nothing) where {T,N}

Construct a SimpleMetaArray with the given type, dimensions, metadata and colmetadata. The type can be a concrete type or a comcrete subtype of AbstractArray.

AbstractMetaArrays.create_metaarray(::Type{MA}, A::AbstractArray, meta=nothing, colmeta=nothing) where {MA<:AbstractMetaArray}

helper function to the metadata and colmetadata constructors given a concrete implemetation of the AbstractMetaArray and of the AbstractArray it contains. The function returns a tuple of metadata and colmetadata. The metadata is a dictionary with string keys and values of type Tuple{Any,Symbol}. The colmetadata is a dictionary with symbol keys and values of type MetaType if the MetaArray has column metadata, otherwise it is return nothing.

Note: The format of the metatada is given bt the MetaType type as a dictionary with string keys and values of type Tuple{Any,Symbol}. If the dictionary provided is in the value in not in the form of a Tuple{Any,Symbol} it will be converted to this format by appending the :default key to the value.

Arguments

• MA: Type of the metaarray.
• A: Abstract array to be wrapped.
• meta: Default metadata to be used if not provided. It can be a Dict or Nothing.
• colmeta: Default column metadata to be used if not provided. It can be a Dict or Nothing or a Tuple of Dicts.

Returns

A tuple containing the metadata and colmetadata.

Example

```jldoctest julia> using StaticArrays julia> create_metaarray(SimpleMetaArray, SVector{3}(1,1,1), Dict("description" => ("test array", :entry)), Dict("unit" => ("m", :default))) (Dict("description" => ("test array", :entry)), Dict(:x => Dict("unit" => ("m", :default)), :y => Dict("unit" => ("m", :default)), :z => Dict("unit" => ("m", :default))))

julia>create_metaarray(SimpleMetaArray, SVector{3}(1,1,1),Dict("description" => ("test array", :entry)), (Dict("unit" => ("m", :default)), Dict("unit" => ("km", :default)), Dict("unit" => ("cm", :default)))) (Dict("description" => ("test array", :entry)), Dict(:x => Dict("unit" => ("m", :default))), :y => Dict("unit" => ("km", :default)), :z => Dict("unit" => ("cm", :default))) ```