openMINDS Metadata Models for MATLAB

Installation • Getting Started • Tutorials • Extending • Upgrading • Acknowledgements

---

A MATLAB toolbox for creating openMINDS metadata: typed classes for every openMINDS metadata type, linked into a graph, and read from or written to JSON-LD.

Every openMINDS type is a MATLAB class. Properties are validated against the schema as you assign them, links between instances are real object references, and a collection of instances serializes to JSON-LD documents that any openMINDS tool can read. Every version of the metadata model ships in the toolbox; you choose which one is active.

Try it without installing anything: open the getting-started live script in MATLAB Online.

Installation

Requires MATLAB R2022a or later.

From the Add-On Explorer (recommended) — in MATLAB, open Home → Add-Ons → Get Add-Ons, search for openminds, and add openMINDS Metadata Models for MATLAB. Step-by-step screenshots are below.

From a release — download the .mltbx from the latest release or File Exchange and open it in MATLAB.

From source — clone and run the setup script, which adds the toolbox to your path and saves it:

!git clone https://github.com/openMetadataInitiative/openMINDS_MATLAB
run(fullfile("openMINDS_MATLAB", "code", "setup.m"))

Check the installation with openminds.toolboxversion.

Getting Started

Before you start

Check that openMINDS_MATLAB is installed and on the search path.

disp( openminds.toolboxversion )

Version 0.10.0

Choose a version of the metadata model

The toolbox ships the types of every version of the openMINDS metadata model, and only one version can be on the search path at a time. If you installed the toolbox, the latest version is already selected and you can skip this. If you cloned the repository, select one:

openminds.startup("latest")

Initializing openMINDS_MATLAB...
Added classes for version "latest" of the openMINDS metadata model to the search path.

Describe a subject

Every openMINDS type is a MATLAB class, and its properties are validated against the schema as you assign them. Here is an adult female mouse. The species and sex are controlled terms and can be given by name.

import openminds.core.*
mouse = Subject( ...
    'lookupLabel', 'mouse_01', ...
    'species', 'musMusculus', ...
    'biologicalSex', 'female');
disp(mouse)

  Subject (_:1) with properties:


         biologicalSex: female (BiologicalSex)
    internalIdentifier: ""
              isPartOf: [None] (SubjectGroup)
           lookupLabel: "mouse_01"
               species: Mus musculus (Species)
          studiedState: [None] (SubjectState)


  Required Properties: species, studiedState

Describe the subject at the time of recording

Age and weight belong to a subject state rather than to the subject, because they change. Each is a quantity with a unit, and an age also says what it is counted from.

age = SpecimenAge( ...
    'age', QuantitativeValue('value', 12, 'unit', 'week'), ...
    'reference', 'birth');
weight = SpecimenWeight( ...
    'weight', QuantitativeValue('value', 24, 'unit', 'gram'), ...
    'type', 'bodyWeight');
recordingState = SubjectState( ...
    'lookupLabel', 'mouse_01_recording', ...
    'ageCategory', 'adult', ...
    'age', age, ...
    'weight', weight);
disp(recordingState)

  SubjectState (_:2) with properties:


         additionalRemarks: ""
                       age: 12 weeks (birth) (SpecimenAge)
               ageCategory: adult (AgeCategory)
        associatedProtocol: [None] (Any of: BehavioralProtocol, Protocol)
                 attribute: [None] (SubjectAttribute)
             descendedFrom: [None] (SubjectState)
                handedness: [None] (Handedness)
        internalIdentifier: ""
               lookupLabel: "mouse_01_recording"
                 pathology: [None] (Any of: Disease, DiseaseModel)
    relativeTimeIndication: [None] (One of: QuantitativeValue, QuantitativeValueRange)
                    weight: 24 grams (body weight) (SpecimenWeight)


  Required Properties: ageCategory

Link the state to the subject

Assigning an instance to a property links the two. A linked property can hold several instances, so a subject can have a state per session.

mouse.studiedState = recordingState;
disp(mouse)

  Subject (_:1) with properties:


         biologicalSex: female (BiologicalSex)
    internalIdentifier: ""
              isPartOf: [None] (SubjectGroup)
           lookupLabel: "mouse_01"
               species: Mus musculus (Species)
          studiedState: mouse_01_recording (SubjectState)


  Required Properties: species, studiedState

Save the metadata as JSON-LD

A collection holds a set of instances and writes them as JSON-LD documents. Adding the mouse brings everything it links to along with it.

collection = openminds.Collection(mouse);
jsonldFile = fullfile(tempdir, "mouse_01.jsonld");
collection.save(jsonldFile);

Load it back

Loading from the file rebuilds the instances and the links between them.

loaded = openminds.Collection(jsonldFile);
fprintf("Loaded %d instances\n", numel(loaded.getAll()))

Loaded 9 instances

Tutorials

Longer worked examples, exported from the live scripts in code/livescripts:

• Crew member collection — build a small linked collection from a table, save it, and load it back.
• Basic neuroscience dataset — describe a dataset, its subjects and their states the way a data repository expects.

Each is also available to run directly in MATLAB Online from the links inside.

Extending the toolbox

Two extension points are public and stable:

• Link resolvers. Implement openminds.interface.LinkResolver and register it with openminds.registerLinkResolver to resolve references to instances that live somewhere else — a knowledge graph, a local store, an archive.
• Metadata stores. Implement openminds.interface.MetadataStore to read and write collections to a backend of your own.

To ask what a type looks like — which properties are links, which are embedded, which accept several types — use openminds.introspection. It is what the toolbox's own serializers use.

Names under openminds.internal are implementation details and may change between releases.

Upgrading

Releases before 1.0.0 may rename public names. Each release with renames ships a migration guide under docs/migration, listing every old name and its replacement; the guide is linked from the release notes.

Detailed Installation Instructions

(Back to top)

The easiest way to install the openMINDS for MATLAB is to use the Add-on Explorer:

1. Launch the Add-on Explorer from MATLAB's Home tab. Click Add-Ons -> Get Add-Ons
2. Search for "openminds"
3. Select openMINDS Metadata Models for MATLAB
4. Press the "Add" button.

Acknowledgements

(Back to top)

This open source software code was developed in part or in whole in the Human Brain Project, funded from the European Union's Horizon 2020 Framework Programme for Research and Innovation under Specific Grant Agreements No. 945539 (Human Brain Project SGA3).