Readme content update

[Raphael-Gazzotti]

See below for suggested content:

openMINDS Python Library

The openMINDS Python library provides a simple and convenient way to create, manage, validate, and serialize openMINDS metadata models in Python. It supports importing and exporting metadata in JSON-LD format and offers direct access to the openMINDS metadata models and schemas.

Installation

Install the latest release from PyPI:

pip install openMINDS

Importing schemas

The package structure follows a simple hierarchy:

1. openminds
2. The schema version (for example, latest)
3. The schema module (core, controlled_terms, etc.)

For example:

import openminds.latest.core as omcore

Python naming conventions

Unlike the openMINDS specification, the openMINDS Python library follows the conventions defined in the Python PEP 8 style guide.

As a result:

• Property names, instance identifiers and schema modules that use camelCase in the openMINDS specification are converted to lowercase letters with underscores (snake_case).
• Class names use PascalCase, following standard Python and openMINDS conventions.
• Properties representing lists are named using the plural form.
• Schema versions are represented using Python compatible module names. For example, openMINDS version v4.0 is available under the module v4, with the trailing .0 omitted.

For example, the openMINDS property preferredName is represented as preferred_name in Python, while the instance organizational unit is exposed as organizational_unit. Likewise, properties that contain multiple values, such as memberships, are pluralized to distinguish them from single-valued properties.

Creating instances

To create an openMINDS object, import the module containing the desired schema and instantiate it with the required metadata.

import openminds.latest.core as omcore

person = omcore.Person(
    preferred_name="Prostetnic Vogon Jeltz"
)

For a detailed introduction, see the openMINDS documentation on creating instances:
https://openminds.docs.om-i.org/en/latest/shared/getting_started/minimal_openMINDS_instance.html#creating-a-minimal-instance

Connecting openMINDS instances

The library abstracts away many implementation details of the openMINDS data model. In particular, the distinction between linked instances and embedded typed objects is handled automatically and only becomes visible when serializing or saving metadata.

from datetime import date

import openminds.latest.core as omcore

organization.memberships = [
    omcore.Membership(
        member=person,
        start_date=date(1978, 4, 1),
    )
]

Additional details can be found in the documentation:
https://openminds.docs.om-i.org/en/latest/shared/getting_started/connecting_openMINDS_instances.html

Using curated library instances

For selected schemas, openMINDS provides curated instance libraries. These predefined instances can be referenced in exactly the same way as user-created instances.

Accessing a library instance directly

import openminds.latest.controlled_terms as omcontrolled

organization.type = omcontrolled.OrganizationType.organizational_unit

Looking up an Instance by name

The by_name() method searches registered names and synonyms and returns the matching instance.

import openminds.latest.controlled_terms as omcontrolled

organization.type = omcontrolled.OrganizationType.by_name(
    "organizational unit"
)

Working with collections

openMINDS objects are often interconnected. The Collection class provides utilities for managing, validating, saving, and loading openMINDS metadata objects.

For more information, see:
https://openminds.docs.om-i.org/en/latest/shared/getting_started/openMINDS_collections.html

Creating a collection

from openminds import Collection

collection = Collection()
collection.add(person, organization)

Validating metadata

collection.validate()

Serializing an instance

organization.to_jsonld()

Saving a collection

Save all metadata to a single JSON-LD file:

collection.save("my_collection.jsonld")

Save each instance to an individual file:

collection.save(
    "my_collection",
    individual_files=True,
)

Loading a collection

new_collection.load("my_collection.jsonld")

License

This work is licensed under the MIT License.

Getting help

In case of questions about openMINDS, please contact us at support@openmetadatainitiative.org.
If you find a bug in the Python library or would like to suggest an enhancement or new feature,
please open a ticket in the openMINDS Python library issue tracker.

If you identify a problem or would like to suggest changes to the openMINDS specification itself,
please open a ticket in the openMINDS issue tracker.

Development

Contributions are welcome, please see our contribution guidelines.

This repository has two main branches: pipeline and main.
The pipeline contains the code for building the Python package from the openMINDS schemas.
The build process is triggered by changes to the schemas, and runs as a GitHub action.
The resultant package is copied to the main branch, and at intervals is published on PyPI.

Acknowledgements

The openMINDS metadata framework development started in the Human Brain Project (HBP), funded from the European Union’s Horizon 2020 Framework Programme for Research and Innovation under the Specific Grant Agreements SGA-1 (No.720270), SGA-2 (No.785907), and SGA-3 (No. 945539).

The framework is further developed as part of the EBRAINS 2.0 project, funded from the European Union's Research and Innovation Program Horizon Europe under Grant Agreement GA (No.101147319).

The framework also receives support from the BigBrain Project, funded by HIBALL.