The NBO Model¶
This page describes the metadata model the library implements, and states which parts of nbo.xsd reach the generated classes and which do not. For the XSD-to-language mapping, see Code Generation.
Why metadata¶
Two images of the same sample can come from different stands, detectors, light sources, objectives, filters, and stages, acquired under different settings, and nothing in the pixel data distinguishes them. Multidimensional acquisitions widen the gap: a single experiment combining timepoints, Z positions, channels, and conditions becomes a large collection of images, and without metadata nothing states which condition each image belongs to.
A structured description of the instrument, the acquisition, and the sample supports five requirements a publication depends on.
| Concern | What the metadata answers |
|---|---|
| Provenance | Which instrument and which settings produced this image |
| Interpretation | What a value in the file means, and in which unit |
| Reproducibility | What another group needs in order to repeat the acquisition |
| Sharing | What a repository or a journal receives alongside the pixels |
| Reuse | Whether a dataset can be compared with, or combined with, another |
Microscopes do record metadata on their own, but what they record, and how they name it, differs between manufacturers. A common model is what makes those descriptions comparable.
Scope and governance¶
The NBO (4DN-BINA-OME) model extends the OME Data Model. It was specified by Hammer et al. in Nature Methods 1, and it is maintained by the 4D Nucleome (4DN) Imaging Standards Working Group, the Bioimaging North America (BINA) Quality Control and Data Management Working Group, and QUAREP-LiMi. The three parts it describes, instrument hardware, acquisition settings, and experimental context, are summarized on the Overview.
nbo.xsd is self-contained: it declares a single target namespace and carries the OME elements it extends inside that namespace, rather than importing ome.xsd. The library therefore generates one class hierarchy, not an OME hierarchy plus an NBO hierarchy, and OME:-prefixed types in the schema resolve to the same namespace as the NBO types.
Tiers, extensions, and other schema annotations¶
NBO is a tiered specification. Rather than requiring every field of a large model from every experiment, it assigns elements to tiers of increasing experimental and analytical complexity, so a simple acquisition is described completely without answering the questions that only a complex one raises. It also groups elements into extensions (Core, Basic, Advanced+Confocal, and Calibration and Performance) and tags them by domain and category.
All of this is carried in nbo.xsd as <xsd:documentation> strings inside <xsd:annotation> blocks, in a Key=Value form:
<xsd:annotation>
<xsd:appinfo>
<xsdfu xmlns=""><plural>Experimenters</plural><global/></xsdfu>
</xsd:appinfo>
<xsd:documentation>Extension=Core</xsd:documentation>
<xsd:documentation>Domain=Experimental</xsd:documentation>
<xsd:documentation>Category=SamplePreparation</xsd:documentation>
<xsd:documentation>Description=This element describes a person who performed an imaging experiment...</xsd:documentation>
<xsd:documentation>Tier=1</xsd:documentation>
</xsd:annotation>
The generator reads exactly one of these keys, Description=, which becomes the docstring of the generated class or accessor in all three languages. Where an element carries no Description=, the docstring reads No description available in the XSD standard.
Every other annotation key is discarded. Tier=, Extension=, Domain=, Category=, and Split=, along with the <xsd:appinfo> hints (plural, global, manytomany), do not appear in the generated classes in any form. There is no getTier(), no tier-derived subset of the API, and no way to ask an object which extension it belongs to.
The consequence for an application: the library exposes the full model, flat. Which tier an application targets, which elements it fills, and how it reports its own tier compliance are the application's responsibility, and must be tracked against the specification rather than against the library. Reading the tier of an element means reading nbo.xsd.
What the library implements¶
The generator maps the structural constructs of the schema, and the value constraints that can be checked on a single field.
Construct in nbo.xsd |
Reaches the generated classes as |
|---|---|
complexType, element, sequence |
A class per type, with the same nesting as the document |
complexContent / extension |
Class inheritance |
attribute |
A typed accessor; use="required" is checked on import and on export |
minOccurs="0" |
An optional accessor set: has, get, set, and reset |
maxOccurs="unbounded" |
A typed vector, with addTo<Name>_List() |
choice |
A variant, with generated is<T>(), as<T>(), and set<T>() helpers |
abstract="true" with substitutionGroup |
A generic base type with concrete subtypes, and a virtual getTypeName() |
enumeration |
A validated string type, with getAllowedValues() |
pattern |
A validated string type, with getPattern() |
minInclusive, maxInclusive, minExclusive, maxExclusive, length |
A bounds check on set() |
documentation beginning with Description= |
The docstring of the class or accessor |
Value validation raises InscoperNBOValidationException. It applies when a value is set, and again when a document is imported or exported. Every entry point that validates takes a validate flag, defaulting to true; passing false builds or reads a tree without the checks. See Restricted Types and Validation.
What the library does not implement¶
Four constraints of the schema are not enforced. An application that must guarantee a schema-valid document should validate the exported XML against nbo.xsd with an XML Schema validator.
Construct in nbo.xsd |
Status | Consequence |
|---|---|---|
key, keyref, unique, with their selector and field |
Not generated | ID references are not resolved. A <...Ref ID="Detector:99"> that points at no existing Detector is accepted on import and written on export |
minOccurs="1" on an element |
Shapes the accessor, not a check | A required child element left unset is not reported. Only required attributes raise InscoperNBOValidationException |
maxOccurs="N" with a finite N |
Becomes an unbounded vector | An upper bound on repetition is not enforced |
whiteSpace |
Not applied | String values are stored as read, without collapsing |
There is also no schema validation step in the library. XML is parsed with pugixml, which carries no XML Schema validator, so a validated document here means that every field the library checks passed its own check, not that the document satisfies nbo.xsd as a whole. A document that an external validator would reject can still round-trip through the library without an exception.
Two consequences of the model¶
An acquisition resolves to hardware. A channel recorded as Channel 2 is a label, and it carries no reference to the hardware that produced it. In the NBO model, that channel references the detector it was read out on, the light source and its wavelength, the power setting used, and the optical components in the path. The image stays readable years later, and comparable with an image from another instrument. Because the library does not resolve references, holding those links intact is the application's responsibility.
The instrument is described once. Because instrument hardware, acquisition settings, and experimental context are separate parts of the model, a facility describes its microscope once and references that description from every acquisition, instead of re-entering it per experiment. Acquisition metadata then records only what actually varied.
References¶
-
Hammer M, Huisman M, Rigano A, et al. Towards community-driven metadata standards for light microscopy: tiered specifications extending the OME model. Nature Methods 18, 1427-1440 (2021). doi:10.1038/s41592-021-01327-9 ↩