mammos_entity quickstart#
mammos_entity provides tools to work with ontology-enriched data. This is in particular important for data storage and exchange. Data exchange includes both exchanging files as well as passing data between (Python) functions.
from pathlib import Path
import mammos_entity as me
import mammos_units as u
Entity#
The central object is the Entity class, which combines quantities (values and unit) with their definition in an ontology (typically EMMO or the domain ontology for magnetic materials).
Creating an entity can take the following arguments:
the ontology label
the value(s)
the unit (optional but highly recommended; if not provided default units are taken from the ontology)
a description (optional, empty string if not provided)
me.Entity("SpontaneousMagnetization", 0.7, "MA/m", "Measured with technique ABC")
For entities commonly used in a magnetics context short-hand functions are provided:
me.Ms(0.7, "MA/m")
Data can have arbitrary shape:
Ms = me.Ms([1, 2, 3], "A/m", description="Measured with technique ABC")
Ms
The entity provides a number of attributes to access ontology information:
Ms.ontology_label
'SpontaneousMagnetization'
Ms.ontology_label_with_iri
'SpontaneousMagnetization https://w3id.org/emmo/domain/magnetic-materials#EMMO_032731f8-874d-5efb-9c9d-6dafaa17ef25'
print(Ms.ontology.elucidation[0])
The spontaneous magnetization, Ms, of a ferromagnet is the result
of alignment of the magnetic moments of individual atoms. Ms exists
within a domain of a ferromagnet.
Entities are immutable. To work with the underlying data, use the embedded mammos_units.Quantity object:
Ms.q
Ms.q * 2
If you only need the numerical values use:
Ms.value
array([1., 2., 3.])
Searching for available entities#
Several functions are provided to search for available entities in the ontology.
To search for all ontology labels (prefLabel and altLabels) that contain a given substring use:
me.search_labels("CurieTemperature")
['CurieTemperature']
me.search_labels("Magnetization")
['MagneticMomentPerUnitMass',
'Magnetization',
'MassMagnetizationUnit',
'Remanence',
'SaturationMagnetization',
'SpontaneousMagnetization']
In the second example we see one surprising entry: “MagneticMomentPerUnitMass” does not contain the substring “Magnetization”. It appears in the results because one of the altLabels contains the word “Magnetization”:
me.mammos_ontology.MagneticMomentPerUnitMass.altLabel
[locstr('sigma', ''),
locstr('SpecificMagneticMoment', 'en'),
locstr('MassMagnetisation', 'en-GB'),
locstr('MassMagnetization', 'en-US')]
EntityCollection#
Multiple entities can be grouped into an EntityCollection. The collection additionally carries a description (empty string by default).
me.EntityCollection(
Ms=me.Ms([600, 500, 400], "kA/m"),
T=me.T([100, 200, 300], "K"),
)
EntityCollection(
description='',
Ms=Entity(ontology_label='SpontaneousMagnetization', value=array([600., 500., 400.]), unit='kA / m'),
T=Entity(ontology_label='ThermodynamicTemperature', value=array([100., 200., 300.]), unit='K'),
)
EntityCollection is not limited to Entity objects. It can also store mammos_units.Quantity objects or any other scalar or array-like object. We summarize these with the term “entity-like”:
collection = me.EntityCollection(
description="Some random test data",
Ms=Ms, # entity
T=me.T([100, 200, 300], "K"), # entity
x=u.Quantity([1, 2, 3], "mm"), # quantity
comment=["", "", "defect in the sample"], # list
)
collection
EntityCollection(
description='Some random test data',
Ms=Entity(ontology_label='SpontaneousMagnetization', value=array([1., 2., 3.]), unit='A / m', description='Measured with technique ABC'),
T=Entity(ontology_label='ThermodynamicTemperature', value=array([100., 200., 300.]), unit='K'),
x=<Quantity [1., 2., 3.] mm>,
comment=['', '', 'defect in the sample'],
)
Entity-likes in a collection do not have to have the same shape.
Individual elements of the collection can be accessed as follows:
collection.Ms
collection.x
If all entity-likes are one-dimensional and have the same length, the collection can be converted into a pandas.DataFrame:
collection.to_dataframe(include_units=True)
| Ms (A / m) | T (K) | x (mm) | comment | |
|---|---|---|---|---|
| 0 | 1.0 | 100.0 | 1.0 | |
| 1 | 2.0 | 200.0 | 2.0 | |
| 2 | 3.0 | 300.0 | 3.0 | defect in the sample |
We can add a new element to the collection using:
collection.Tc = me.Tc(1000, "K")
collection
EntityCollection(
description='Some random test data',
Ms=Entity(ontology_label='SpontaneousMagnetization', value=array([1., 2., 3.]), unit='A / m', description='Measured with technique ABC'),
T=Entity(ontology_label='ThermodynamicTemperature', value=array([100., 200., 300.]), unit='K'),
x=<Quantity [1., 2., 3.] mm>,
comment=['', '', 'defect in the sample'],
Tc=Entity(ontology_label='CurieTemperature', value=1000.0, unit='K'),
)
Reading and writing files#
mammos_entity supports storing entity collections in YAML, CSV and HDF5, details for each file format are explained in the respective notebook.
Here, we show just one example of saving an entity collection as YAML:
collection.to_yaml("file.yaml")
The file has the following content:
print(Path("file.yaml").read_text())
# mammos yaml v2
metadata: null
description: Some random test data
data:
Ms:
ontology_label: SpontaneousMagnetization
description: Measured with technique ABC
ontology_iri: https://w3id.org/emmo/domain/magnetic-materials#EMMO_032731f8-874d-5efb-9c9d-6dafaa17ef25
unit: A / m
value: [1.0, 2.0, 3.0]
T:
ontology_label: ThermodynamicTemperature
description: ''
ontology_iri: https://w3id.org/emmo#EMMO_affe07e4_e9bc_4852_86c6_69e26182a17f
unit: K
value: [100.0, 200.0, 300.0]
x:
unit: mm
value: [1.0, 2.0, 3.0]
comment:
value: ['', '', defect in the sample]
Tc:
ontology_label: CurieTemperature
description: ''
ontology_iri: https://w3id.org/emmo#EMMO_6b5af5a8_a2d8_4353_a1d6_54c9f778343d
unit: K
value: 1000.0
The file can be read using from_yaml(). The returned object is always an EntityCollection:
me.from_yaml("file.yaml")
EntityCollection(
description='Some random test data',
Ms=Entity(ontology_label='SpontaneousMagnetization', value=array([1., 2., 3.]), unit='A / m', description='Measured with technique ABC'),
T=Entity(ontology_label='ThermodynamicTemperature', value=array([100., 200., 300.]), unit='K'),
x=<Quantity [1., 2., 3.] mm>,
comment=['', '', 'defect in the sample'],
Tc=Entity(ontology_label='CurieTemperature', value=1000.0, unit='K'),
)
