radiometry.metadata module

Metadata: Information on numeric data stored in a structured way.

Metadata

In this module, the individual metadata classes are defined which contain the metadata for the different types of datasets:

EveDatasetMetadata

What may sound like a minor detail is one key aspect of the radiometry package: The metadata and their structure provide a unified interface for all functionality operating on datasets. Reproducible research is only possible if all information necessary is always recorded, and this starts with all the metadata accompanying a measurement. Defining what kind of metadata is important and needs to be recorded, together with metadata formats easily writable by the experimenters during recording the data requires a thorough understanding of both, the method and the setup(s) used. For an overview of the structures of the dataset classes and their corresponding metadata, see the dataset structure section.

Module documentation

class radiometry.metadata.EveDatasetMetadata

Bases: ExperimentalDatasetMetadata

Set of all metadata for a dataset object representing an eve HDF5 file.

Metadata as a unified structure of information coupled to the dataset are necessary for the understanding, analysis and processing of data.

experiment

Metadata of the experiment carried out

Type:: Experiment

measurement

Metadata of the measurement as a result of carrying out the experiment

Type:: Measurement

setup

Metadata of the setup the experiment was carried out on

Type:: Setup

from_dict(dict_=None)

Set properties from dictionary, e.g., from metadata.

Only parameters in the dictionary that are valid properties of the class are set accordingly.

Keys in the dictionary are converted to lower case and spaces converted to underscores to fit the naming scheme of attributes.

Parameters:

dict (dict) –

Dictionary with metadata.

Each key of this dictionary corresponds to a class attribute and is in itself a dictionary with the correct set of attributes for the particular class.

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class radiometry.metadata.Experiment(dict_=None)

Bases: Metadata

General information available for an experiment.

In contrast to Measurement, an experiment is a more general description of an experiment, while a measurement is the act/result of performing such an experiment.

comment

Comment on the level of the entire experiment

In contrast to comments during a measurement that are added to the list of aspecd.dataset.Dataset.annotations (and dubbed “life comment” or “log message” in eve), a comment on this level refers to the experiment as such.

Type:: str

procedure

Actionable description of the procedure underlying the experiment

Type:: ScanDescription

from_dict(dict_=None)

Set properties from dictionary, e.g., from metadata.

Only parameters in the dictionary that are valid properties of the class are set accordingly.

Keys in the dictionary are converted to lower case and spaces converted to underscores to fit the naming scheme of attributes.

If a property is of class aspecd.metadata.PhysicalQuantity, it is set accordingly.

Parameters:: dict (dict) – Dictionary containing properties to set

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class radiometry.metadata.Measurement(dict_=None)

Bases: Measurement

General information available for each type of measurement.

Note

Currently, only a relevant subset of the attributes of the class are documented here. For a full list of attributes, see the documentation of the parent class aspecd.metadata.Measurement.

start

Date and time of start of measurement

Type:: datetime.datetime

end

Date and time of end of measurement

Type:: datetime.datetime

property duration

Duration of the measurement.

Returns:

duration – Time difference between start and end of measurement

Note

If either start or end are not set (e.g., as a result of reading a file with eveH5 structure version <7), the result (and correspondingly the return type) is None.

Return type:

datetime.timedelta

from_dict(dict_=None)

Set properties from dictionary, e.g., from metadata.

Only parameters in the dictionary that are valid properties of the class are set accordingly.

For the “start” and “end” items, there are two different conventions available how the dictionary can be structured. Either those fields are dictionaries themselves, with fields “date” and “time” accordingly, such as:

{"start": {"date": "yyyy-mm-dd", "time": "HH:MM:SS"},
 "end": {"date": "yyyy-mm-dd", "time": "HH:MM:SS"}}

Alternatively, those fields can be strings containing a representation of both, date and time:

{"start": "yyyy-mm-dd HH:MM:SS", "end": "yyyy-mm-dd HH:MM:SS"}

Use whichever is more appropriate for you.

Parameters:: dict (dict) – Dictionary with keys corresponding to properties of the class.

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class radiometry.metadata.Device(dict_=None)

Bases: Device

Information on the device contributing device data.

This class contains the metadata of the corresponding devices whose data are of type radiometry.dataset.DeviceData. That class contains an attribute radiometry.dataset.DeviceData.metadata.

name

Name of the device

TODO: What is this name? And how does it differ from label?

Type:: str

type

Device type

Channel or Axis

TODO: Needs to become an enum type

Type:: str

xmlid

XML id

Some more description is necessary.

Type:: str

access

PV name for CA

Some more description is necessary.

Type:: str

from_dict(dict_=None)

Set properties from dictionary, e.g., from metadata.

Only parameters in the dictionary that are valid properties of the class are set accordingly.

Keys in the dictionary are converted to lower case and spaces converted to underscores to fit the naming scheme of attributes.

If a property is of class aspecd.metadata.PhysicalQuantity, it is set accordingly.

Parameters:: dict (dict) – Dictionary containing properties to set

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class radiometry.metadata.ScanDescription(dict_=None)

Bases: Metadata

Actionable description of a scan used in a measurement.

A scan in eve is described using an XML file with a specific schema termed “SCML”.

Note

Depending on the actual requirements, this class may eventually do much more than being a container for SCML files. Possible behaviour includes (partially) parsing the contained SCML/XML and extracting information, such as a list of devices.

filename

Name of the SCML file describing the scan.

Type:: str

description

Actual description of the scan.

This is the (multiline) string containing the actual XML/SCML.

Type:: str

from_dict(dict_=None)

Set properties from dictionary, e.g., from metadata.

Only parameters in the dictionary that are valid properties of the class are set accordingly.

Keys in the dictionary are converted to lower case and spaces converted to underscores to fit the naming scheme of attributes.

If a property is of class aspecd.metadata.PhysicalQuantity, it is set accordingly.

Parameters:: dict (dict) – Dictionary containing properties to set

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class radiometry.metadata.Setup(dict_=None)

Bases: Metadata

General information of the setup an experiment was carried out on.

The setup is basically the sum of the hardware used to carry out an experiment resulting in a measurement/measured data.

name

Descriptive and concise name of the setup

Example: Name of the beamline.

Hint: This information is typically contained in the Location attribute of the eveH5 file.

Type:: str

from_dict(dict_=None)

Set properties from dictionary, e.g., from metadata.

Only parameters in the dictionary that are valid properties of the class are set accordingly.

Keys in the dictionary are converted to lower case and spaces converted to underscores to fit the naming scheme of attributes.

If a property is of class aspecd.metadata.PhysicalQuantity, it is set accordingly.

Parameters:: dict (dict) – Dictionary containing properties to set

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class radiometry.metadata.EveSoftware(dict_=None)

Bases: Metadata

General information regarding the eve software used at the setup.

More description comes here…

TODO: Decide whether to add the version number of the eveH5 file format as well.

engine_version

Version number of the evEngine used at the setup

Type:: str

xml_schema_version

Version number of the XML schema the setup description and SCML files are validated against

Type:: str

from_dict(dict_=None)

Set properties from dictionary, e.g., from metadata.

Only parameters in the dictionary that are valid properties of the class are set accordingly.

Keys in the dictionary are converted to lower case and spaces converted to underscores to fit the naming scheme of attributes.

If a property is of class aspecd.metadata.PhysicalQuantity, it is set accordingly.

Parameters:: dict (dict) – Dictionary containing properties to set

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.