mammos_entity.io#

Support for reading and writing Entity files.

Currently only a single file format is supported: a CSV file with additional commented metadata lines. Comments start with #.

  • The first line is commented and contains the file version in the form:

    mammos csv v<VERSION>

    The reading code checks the version number (using regex vd+) to ensure compatibility.

  • The second line is commented and contains the preferred ontology label.

  • The third line is commented and contains the ontology IRI.

  • The fourth line is commented and contains units.

  • The fifth line contains the short labels used to refer to individual columns when working with the data, e.g. in a pandas.DataFrame. Omitting spaces in this string is advisable.

    Ideally this string is the short ontology label.

  • All remaining lines contain data

Elements in a line are separated by a comma without any surrounding whitespace. A trailing comma is not permitted.

If a column has no ontology entry lines 1 and 2 are empty for this column.

If a column has no units (with or without ontology entry) line 3 has no entry for this column.

Here is an example with five columns, an index with no units or ontology label, the entity spontaneous magnetization with an entry in the ontology, a made-up quantity alpha with a unit but no ontology label, demagnetizing factor with an ontology entry but no unit, and a column description containing a string description without units or ontology label. To keep this example short the actual IRIs are omitted:

#mammos csv v1
#,SpontaneousMagnetization,,DemagnetizingFactor,description
#,https://w3id.org/emm/...,,https://w3id.org/emmo/...,
#,kA/m,s^2,,
index,Ms,alpha,DemagnetizingFactor,
0,1e2,1.2,1,Description of the first data row
1,1e2,3.4,0.5,Description of the second data row
2,1e2,5.6,0.5,Description of the third data row

Functions

entities_from_csv(filename)

Read CSV file with ontology metadata.

entities_to_csv(filename, **entities)

Write tabular data to csv file.

Classes

EntityCollection(**kwargs)

Container class storing entity-like objects.
class mammos_entity.io.EntityCollection(**kwargs)[source]#

Container class storing entity-like objects.

Initialize EntityCollection, keywords become attributes of the class.

to_dataframe(include_units=True)[source]#

Convert values to dataframe.

Parameters:

include_units (bool)

mammos_entity.io.entities_from_csv(filename)[source]#

Read CSV file with ontology metadata.

Reads a file as defined in the module description. The returned container provides access to the individual columns.

Parameters:

filename (str | Path)

Return type:

EntityCollection

mammos_entity.io.entities_to_csv(filename, **entities)[source]#

Write tabular data to csv file.

The file structure is explained in the module-level documentation.

Column names are keys of the dictionary. If an element is of type mammos_entity.Entity ontology label, IRI and unit are added to the header, if an element is of type mammos_units.Quantity its unit is added to the header, otherwise all headers are empty.

Parameters:
Return type:

None