rmellipse.arrschema

Submodules

Exceptions

ValidationError

Common base class for all non-exit exceptions.

Classes

ArraySchema

Specialized dict subclass to describe the shape an array.

AnnotatedArray

Interface for an array structure with annotate dimensions and coordinates.

ArrayClassRegistry

Organizes schema, classes, loaders, savers, and converters.

Package Contents

exception rmellipse.arrschema.ValidationError(*args, **kwargs)

Bases: Exception

Common base class for all non-exit exceptions.

Initialize self. See help(type(self)) for accurate signature.

class rmellipse.arrschema.ArraySchema(name: str, shape: tuple[str | int | types.EllipsisType, Ellipsis], dims: tuple[str | types.EllipsisType, Ellipsis], dtype: str | type[float] | type[complex], units: str | None = None, coords: Mapping = {}, uid: str | None = None, attrs_schema: Mapping | None = None)

Bases: dict

Specialized dict subclass to describe the shape an array.

Initialize an ArraySchema.

Parameters:

  • name (str) – Name of the array structure.

  • shape (tuple[str | int | EllipsisType, ...]) – Shape of structure. Ellipses indicate arbitrary dimensions, letters indicate a required dimension of unknown length, and integers indicate a required dimension of a required length.

  • dims (tuple[str | EllipsisType, ...]) – Names assigned to dimensions specified by shape. Any required dimension must be names, and arbitrary dimensions must also be ellipses.

  • dtype (str | type[float]) – Type must be parseable by numpy’s dtype (e.g. f8, c8, u8, etc)

  • units (Mapping, optional) – Mapping of units to the array structure. If the whole structure has a single unit, then a string can be passed. Optionally, a single required dimension can be mapped to a 1-d array of units. For example, if a dimension called “col” corresponds to columns in spread-sheet like data and each column has its own unit, you could specify that as {“col”:[“unit 1”, “unit 2”]}.

  • coords (Mapping, optional) – Mapping of required dimensions to a coordinate space. Must provide at least a dtype and a single unit as a string. Optionally, if the coordinates are fixed (i.e. the row and column indices of stacks of 2-d matrices) then you may specify those coordinates here.

  • uid (str, optional) – The uid of a schema can be provided here, it is created using uuid4 if it is not provided, by default None.

  • attrs_schema (mapping, optional) – JSON Schema for validating metadata attributes.

Returns:

Dictionary conforming to an arrschema specification.

Return type:

dict

Raises:

Exception – If some logical inconsistency or is found, or the provided schema doesn’t follow the specification for an array schema.

validate(arr: AnnotatedArray, attach_schema: bool = True)

Test if array conforms to schema.

Parameters:

  • arr (AnnotatedArray) – Array to check.

  • attach_schema (bool, optional) – If True, the schema is dumped into a string and attatched to the attrs of the input data array. The default is True.

Raises:

ValidationError – If a discrepancy is found between the data and the schema.

Return type:

None.

class rmellipse.arrschema.AnnotatedArray(*args, **kwargs)

Bases: xarray.DataArray

Interface for an array structure with annotate dimensions and coordinates.

Inspired by xarray DataArray. Classes conforming to this specification can be registered in an ArrayClassRegister.

schema: ArraySchema
registry: ArrayClassRegistry
validate()

Validate array data against the schema of this type.

save(path: str | pathlib.Path, *saver_args, saver_type: str | None = None, validate_schema: bool = True, verbose: bool = False, **saver_kwargs) → object

Save array using specified saver.

This function dispatches to saver functions supplied to the registry through add_saver.

Parameters:

  • path (str | Path) – Path to location where data should will be saved.

  • *saver_args (positional arguments) – Passed to saver as positional args.

  • saver_type (str, optional) – Used to pick which saver to use. The default is None.

  • validate_schema (bool, optional) – If True, raise an exception if data does not conform to schema. The default is True.

  • verbose (bool, optional) – DESCRIPTION. The default is False.

  • **saver_kwargs (keyword arguments) – Passed to saver as keyword arguments.

Returns:

Object returned by saver fuction.

Return type:

object

convert_to(output_type: type) → AnnotatedArray

Convert self to a specified type.

This function dispatches to converter functions supplied to the registry through add_converter.

output_schemaArraySchema | type

Schema for output array type or an array schema class built by a registry.

AnnotatedArray

Array matching output schema.

classmethod convert_from(input_array: AnnotatedArray) → Self

Initialize from an input array.

This function dispatches to converter functions supplied to the registry through add_converter.

input_arrayAnnotatedArray

Input data.

Self

New array.

classmethod load(path: pathlib.Path | str, *load_args, loader_type: str | None = None, validate_schema: bool = True, verbose=False, **load_kwargs) → Self

Save a dataset.

This function dispatches to loader functions supplied to the registry through add_loader.

pathPath | str

Path to data to load.

loader_typestr, optional

If there are mulitple loaders, specify which one.

validate_schemabool, optional

If True, raise an exception if data do not conform to schema. The default is True.

verbosebool, optional

If True, print debugging messages. The default is False.

Self

Loaded data.

classmethod from_dataarray(array: xarray.DataArray) → Self

Cast an array into an annotated array.

Parameters:

array (xr.DataArray) – Array that can be cast into this format.

Returns:

New array.

Return type:

Self

class rmellipse.arrschema.ArrayClassRegistry

Organizes schema, classes, loaders, savers, and converters.

All of these objects are stored in dictionaries, indexed by unique ids. The unique ids correspond to the schema’s unique id attribute.

classes
schema
loaders
savers
converters
find_schema(schema_name: str | None = None, schema_uid: str | None = None) → ArraySchema

Find a schema.

Name of uid must be provided. Will throw an error if only the name is provided and multiple schema in the registry share a name.

Parameters:

  • name (str) – Name of the schema to look for.

  • uid (str) – uid of the schema to find.

Returns:

Requested schema

Return type:

ArraySchema

Raises:

ValueError – If multiple schemas in the regsitry have the same name.

show_schema()

Show schema.

Return type:

None.

import_saver(schema_name=None, schema_uid: str | None = None, extension: str | None = None, saver_type: str | None = None, verbose: bool = False)

Get a loader function associated with a schema.

Parameters:

  • schema_name (str, optional) – Name of the schema being saved, by default None

  • schema_uid (str, optional) – Unique id of the schema being saved, by default None

  • extension (str, optional) – File extension, by default None

  • saver_type (str, optional) – Type of saver to use, by default None

  • verbose (bool, optional) – Print info, by default False

Returns:

Saver function imported from the registry

Return type:

callable

import_loader(schema_name=None, schema_uid: str | None = None, extension: str | None = None, loader_type: str | None = None, verbose: bool = False)

Get a loader function associated with a schema.

Parameters:

  • schema_name (str, optional) – Name of the schema being saved, by default None

  • schema_uid (str, optional) – Unique id of the schema being saved, by default None

  • extension (str, optional) – File extension, by default None

  • loader_type (str, optional) – Type of loader to use, by default None

  • verbose (bool, optional) – Print info, by default False

Returns:

_description_

Return type:

_type_

add_converter(funspec: str, input_schema: dict, output_schema: dict)

Add a converting functiom between two schema.

Converting functions take in exactly one argument and output exactly 1

Parameters:

  • funspec (str) – Path spec of function in dot-notation (module.submodule:function)

  • input_schema (dict, optional) – name of schema (or provide the uid) for converter

  • output_schema (dict, optional) – output_schema for converter

import_converter(input_schema_uid: str | None = None, output_schema_uid: str | None = None) → Callable

Add a converting functiom between two schema.

Converting functions take in exactly one argument and output exactly 1

Parameters:

  • input_schema_uid (str, optional) – uid of input schema (or provide the name), by default None

  • output_schema_uid (str, optional) – _description_, by default None

add_saver(funspec: str, extension: str, saver_type: str, schema: dict)

Add a saving function to the registry.

Parameters:

  • funspec (str) – _description_

  • extension (list[str], optional) – _description_, by default None

  • saver_type (str, optional) – Specify the type of saver (e.g. csv like, HDF5, group_saveable). If notprovided, ‘’ is used.

  • schema (dict, optional) – Schema, by default None

Raises:

ValueError – _description_

add_loader(funspec: str, extension: str, loader_type: str, schema: dict | Mapping)
Parameters:

  • funspec (str) – _description_

  • extension (list[str], optional) – _description_, by default None

  • loader_type (str, optional) – Specify the type of loader (e.g. csv like, HDF5, group_saveable). If notprovided, ‘’ is used.

  • schema (dict | Mapping) – Schema to use

Raises:

ValueError – _description_

add_schema(schema: dict | Mapping | pathlib.Path)
add_class(class_to_add: type[AnnotatedArray], schema: ArraySchema)