Format-metadata framework: vocabulary, formats and conversions (without wiring)

docs/api/datamodel/metadata-formats.md

@@ -0,0 +1,17 @@
+# Metadata for format authors
+
+The public names of [`brainhops.datamodel.metadata`](metadata.md) are
+those a user of the library needs, and the vocabulary groups that a
+format names in `supports=`. The names below are for whoever adds
+the metadata of a file format; the
+[format author's guide](../../dev/metadata-formats.md) explains how they
+fit together. They are imported from the private modules that define
+them.
+
+# ::: brainhops.datamodel.metadata._vocabulary
+# ::: brainhops.datamodel.metadata._operations
+# ::: brainhops.datamodel.metadata._field
+# ::: brainhops.datamodel.metadata._report
+# ::: brainhops.datamodel.metadata._dtype
+# ::: brainhops.datamodel.metadata._sentinel
+# ::: brainhops.io.base._metadata_parser

docs/api/datamodel/metadata.md

@@ -0,0 +1 @@
+# ::: brainhops.datamodel.metadata

docs/api/io/metadata/base.md

@@ -0,0 +1 @@
+# ::: brainhops.io.metadata._base

docs/api/io/metadata/bids.md

@@ -0,0 +1 @@
+# ::: brainhops.io.metadata.bids

docs/api/io/metadata/index.md

@@ -0,0 +1 @@
+# ::: brainhops.io.metadata

docs/api/io/transformations/itk-h5.md

@@ -1 +1,3 @@
 # ::: brainhops.io.transformations.itk.h5
+
+# ::: brainhops.io.transformations.itk._metadata

pyproject.toml

@@ -14,7 +14,7 @@ dependencies = [
     # typed inverses declare; 0.1 raises on it. 0.3 registers a subclass
     # with every polymorphic level above it and conjoins the constraints
     # it inherits, which the axes and coordinate systems rely on.
-    "bagof-magic >= 0.3.dev0",
+    "bagof-magic >= 0.3.dev2",
     "bagof-paths >= 0.2",
     # Units are parsed by pint, imported on first use. 0.21.1 is the last
     # release for Python 3.8; 0.24 is the first to support numpy 2.

src/brainhops/datamodel/__init__.py

@@ -26,6 +26,7 @@
     "enums",
     "kinds",
     "images",
+    "metadata",
     "orientation",
     "systems",
     "transformations",
@@ -39,6 +40,7 @@
     enums,
     images,
     kinds,
+    metadata,
     orientation,
     systems,
     transformations,

src/brainhops/datamodel/metadata/__init__.py

@@ -0,0 +1,100 @@
+"""
+Non-spatial metadata, shared across file formats.
+
+Every file format keeps descriptive metadata, such as a description, a
+repetition time, a slice timing or a provenance, under its own names
+and types. This package gives that metadata one representation, in a
+class hierarchy that mirrors the hierarchy of the images (`Image`,
+`FileBasedImage`, `NiftiImage`):
+
+- [`Metadata`][brainhops.datamodel.metadata.Metadata] holds the common
+  vocabulary, one field per concept, named after its BIDS key in snake
+  case and stored in BIDS units, plus `extra`, a free-form store of
+  string keys. In-memory images and transformations carry it, and
+  formats convert through it.
+- [`FileBasedMetadata`][brainhops.io.metadata.FileBasedMetadata], which
+  lives in `brainhops.io.metadata` as `FileBasedImage` lives in
+  `brainhops.io.images`, is the base of the metadata of a file format,
+  which reads its fields from the raw record of the format (a `nibabel`
+  header, the attributes of a Zarr array, ...) and writes them back.
+- Each format has its own `<Fmt>Metadata` class, next to its parser
+  under `brainhops.io`. `FileBasedMetadata.load(path)` reads the
+  metadata of a file without its data, and `brainhops.io.metadata.bids`
+  reads and writes BIDS sidecars. The data model does no input or
+  output.
+
+A vocabulary field holds a value, `None` when the value is unknown, or
+[`UNSUPPORTED`][brainhops.datamodel.metadata.UNSUPPORTED] when the format
+has no slot for the field. Converting into a format, with
+`metadata.to(NiftiMetadata)`, records what the format cannot hold in a
+[`ConversionReport`][brainhops.datamodel.metadata.ConversionReport], and
+the loss policy (`"ignore"`, `"warn"` or `"raise"`, see
+[`metadata_loss_policy`][brainhops.datamodel.metadata.metadata_loss_policy])
+decides what happens to the report. A
+[`Scope`][brainhops.datamodel.metadata.Scope] says how each field
+propagates to a derived image, through the
+[`Operation`][brainhops.datamodel.metadata.Operation] an image operation
+describes (an [`Indexed`][brainhops.datamodel.metadata.Indexed] image or
+a [`Resampled`][brainhops.datamodel.metadata.Resampled] one).
+
+The names exported here are those a user of the library needs, and the
+vocabulary groups (`ProvenanceVocabulary`, `MRIVocabulary`, ..., and
+their base `Vocabulary`), which a format names in its `supports=`
+declaration. What else a format author needs (the field annotations,
+the `metadata` field of images, the loss helpers) is imported from the
+private modules of this package, which the format author's guide lists
+(`docs/dev/metadata-formats.md`). The user guide is
+`docs/start/metadata.md`.
+"""
+
+__all__ = [
+    "Metadata",
+    "UNSUPPORTED",
+    "Scope",
+    "Operation",
+    "Indexed",
+    "Resampled",
+    "GeneratedBy",
+    "Channel",
+    "EncodingDirection",
+    "ConversionReport",
+    "MetadataLossWarning",
+    "MetadataLossError",
+    "metadata_loss_policy",
+    "Vocabulary",
+    "ProvenanceVocabulary",
+    "MRIVocabulary",
+    "DiffusionVocabulary",
+    "DisplayVocabulary",
+    "StorageVocabulary",
+    "MicroscopyVocabulary",
+    "TransformVocabulary",
+]
+
+from ._base import Metadata
+from ._operations import Indexed, Operation, Resampled
+from ._report import (
+    ConversionReport,
+    MetadataLossError,
+    MetadataLossWarning,
+    metadata_loss_policy,
+)
+from ._sentinel import UNSUPPORTED
+from ._terms import Channel, EncodingDirection, GeneratedBy
+from ._vocabulary import (
+    DiffusionVocabulary,
+    DisplayVocabulary,
+    MicroscopyVocabulary,
+    MRIVocabulary,
+    ProvenanceVocabulary,
+    Scope,
+    StorageVocabulary,
+    TransformVocabulary,
+    Vocabulary,
+)
+
+# The public names keep the `__module__` of the private module that
+# defines them: rewriting it to this package's name would break
+# `inspect.getsource`, IPython's `??` and doctest discovery, which look
+# the source up through `__module__`. Pickles name the private module,
+# and load as well.