Terminology Tutorial

The code in this tutorial can also be found in the terminology ipython notebook.

TODO write some text for each code listing

Create a document with terms

import datetime as dt
from odml2 import Document, TerminologyStrategy, SB, Value

terms = Document()

# some section types with their properties
terms.type_definitions.set("RecordingSession",
                           "An experimental procedure",
                           properties=[
                                "subject",
                                "recording_date",
                                "session_nr"])
terms.type_definitions.set("Animal",
                           "A non human, animal individual",
                           properties=[
                                "subject_id",
                                "date_of_birth",
                                "species"])

# define properties with their types
terms.property_definitions.set("subject",
                               types=["Animal"])
terms.property_definitions.set("session_nr",
                               types=["int"])
terms.property_definitions.set("recording_date",
                               types=["date", "datetime"])
terms.property_definitions.set("subject_id",
                               types=["int"])
terms.property_definitions.set("species",
                               types=["string"])
terms.property_definitions.set("date_of_birth",
                               types=["date", "datetime"])

terms.save("terms.yml")

with open("terms.yml") as f:
    print(f.read())

date: null
document_version: 1
format_version: 2
author: null
namespaces: null
definitions:
  date_of_birth:
    types:
    - date
    - datetime
  recording_date:
    types:
    - date
    - datetime
  session_nr:
    types:
    - int
  species:
    types:
    - string
  subject:
    types:
    - Animal
  subject_id:
    types:
    - int
  Animal:
    properties:
    - subject_id
    - date_of_birth
    - species
    definition: A non human, animal individual
  RecordingSession:
    properties:
    - session_nr
    - recording_date
    - subject
    definition: An experimental procedure
metadata: null

Alter existing terms

recd = terms.property_definitions["recording_date"]
terms.property_definitions["recording_date"] = recd.copy(definition="Date of a recording")

terms.save("terms.yml")

Use terms from another document

session = Document(strategy=TerminologyStrategy.Ignore)
session.namespaces.set("terms", "terms.yml")

session.root = SB(
    "terms:RecordingSession",
    **{
        "terms:session_nr": 42,
        "terms:recording_date": dt.date.today(),
        "terms:subject": SB(
            "terms:Animal",
            **{
                "terms:subject_id": 12,
                "terms:date_of_birth": dt.date(2015, 11, 25),
                "terms:species": "Mus musculus"
            }
        )
    }
)

# It's ok to add things not defined in a terminology
session.root["quality_level"] = "medium"

Make sure a document sticks to known terms

session = Document(strategy=TerminologyStrategy.Strict)

try:
    session.root = SB(
        "terms:RecordingSession",
        **{
            "terms:session_nr": 42,
            "terms:recording_date": dt.date.today(),
            "terms:subject": SB(
                "terms:Animal",
                **{
                    "terms:subject_id": 12,
                    "terms:date_of_birth": dt.date(2015, 11, 25),
                    "terms:species": "Mus musculus"
                }
            )
        }
    )
except Exception as e:
    print(e.message)
    print("Does not work because no terms are defined")

The namespace 'terms:RecordingSession' is not known in this document
Does not work because no terms are defined

session.namespaces.set("terms", "terms.yml")
session.root = SB(
    "terms:RecordingSession",
    **{
        "terms:session_nr": 42,
        "terms:recording_date": dt.date.today(),
        "terms:subject": SB(
            "terms:Animal",
            **{
                "terms:subject_id": 12,
                "terms:date_of_birth": dt.date(2015, 11, 25),
                "terms:species": "Mus musculus"
            }
        )
    }
)

try:
    session.root["quality_level"] = "medium"
except Exception as e:
    print(e.message)
    print("Does not work because no property is defined")

The property 'quality_level' is not defined for type 'terms:RecordingSession'
Does not work because no property is defined