You're reading an old version of this documentation. For up-to-date information, please have a look at v0.8.

aspecd.annotation module

Annotations of data, e.g. characteristics, that cannot be automated.

Annotations of data are eventually something that cannot be automated. Nevertheless, they can be quite important for the analysis and hence for providing new scientific insight.

The simplest form of an annotation is a comment applying to an entire dataset, such as comments stored in the metadata written during data acquisition. Hence, those comments do not belong to the metadata part of a dataset, but to the annotations in form of a aspecd.annotation.Comment object.

Other frequent types of annotations are artefacts and characteristics, for which dedicated classes are available within the ASpecD framework: aspecd.annotation.Artefact and aspecd.annotation.Characteristic. For other types of annotations, simply subclass the aspecd.annotation.Annotation base class.

class aspecd.annotation.Annotation

Bases: aspecd.utils.ToDictMixin

Annotations are user-supplied additional information to datasets.

Whereas many processing steps of data can be fully automated, annotations are mostly the domain of human interaction, looking at the data of a dataset and providing some sort of comments, trying to make sense of the data.

Annotations can have different types, such as simple “comments”, e.g. saying that a dataset is not useful as something during measurement went wrong, they can highlight “characteristics” of the data, they can point to “artefacts”. Each of these types is represented by a class on its own that is derived from the “Annotation” base class. Additionally, the type is reflected in the “type” property that gets set automatically to the class name in lower-case letters.

Each annotation has a scope (such as “point”, “slice”, “area”, “distance”, “dataset”) it belongs to, and a “contents” property (dict) containing the actual content of the annotation.

type

Textual description of the type of annotation: lowercase class name

Set automatically, don’t change

Type

str

content

Actual content of the annotation

Generic place for more information

Type

dict

dataset

Dataset the annotation belongs to

Type

aspecd.dataset.Dataset

Raises
  • aspecd.annotation.NoContentError – Raised when annotation contains no content(s)

  • aspecd.annotation.MissingDatasetError – Raised when no dataset exists to act on

property scope

Get or set the scope the annotation applies to.

The list of allowed scopes is stored in the private property _allowed_scopes, and if no scope is set when the annotation is finally applied to a dataset, a default scope will be used that is stored in the private property _default_scope (and is defined as one element of the list of allowed scopes)

annotate(dataset=None, from_dataset=False)

Annotate a dataset with the given annotation.

If no dataset is provided at method call, but is set as property in the Annotation object, the process method of the dataset will be called and thus the history written.

If no dataset is provided at method call nor as property in the object, the method will raise a respective exception.

If no scope is set in the aspecd.annotation.Annotation object, a default value will be used that can be set in derived classes in the private property _default_scope. A full list of scopes is contained in the private property _allowed_scopes

The Dataset object always calls this method with the respective dataset as argument. Therefore, in this case setting the dataset property within the Annotation object is not necessary.

Parameters
  • dataset (aspecd.dataset.Dataset) – dataset to annotate

  • from_dataset (bool) –

    whether we are called from within a dataset

    Defaults to “False” and shall never be set manually.

Returns

dataset – dataset that has been annotated

Return type

aspecd.dataset.Dataset

create_history_record()

Create history record to be added to the dataset.

Usually, this method gets called from within the aspecd.dataset.annotate() method of the aspecd.dataset.Dataset class and ensures the history of each annotation step to get written properly.

Returns

history_record – history record for annotation step

Return type

aspecd.history.AnnotationHistoryRecord

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

class aspecd.annotation.Comment

Bases: aspecd.annotation.Annotation

The most basic form of annotation: a simple textual comment.

property comment

Get comment of annotation.

Returns

comment – Actual comment string

Return type

str

annotate(dataset=None, from_dataset=False)

Annotate a dataset with the given annotation.

If no dataset is provided at method call, but is set as property in the Annotation object, the process method of the dataset will be called and thus the history written.

If no dataset is provided at method call nor as property in the object, the method will raise a respective exception.

If no scope is set in the aspecd.annotation.Annotation object, a default value will be used that can be set in derived classes in the private property _default_scope. A full list of scopes is contained in the private property _allowed_scopes

The Dataset object always calls this method with the respective dataset as argument. Therefore, in this case setting the dataset property within the Annotation object is not necessary.

Parameters
  • dataset (aspecd.dataset.Dataset) – dataset to annotate

  • from_dataset (bool) –

    whether we are called from within a dataset

    Defaults to “False” and shall never be set manually.

Returns

dataset – dataset that has been annotated

Return type

aspecd.dataset.Dataset

create_history_record()

Create history record to be added to the dataset.

Usually, this method gets called from within the aspecd.dataset.annotate() method of the aspecd.dataset.Dataset class and ensures the history of each annotation step to get written properly.

Returns

history_record – history record for annotation step

Return type

aspecd.history.AnnotationHistoryRecord

property scope

Get or set the scope the annotation applies to.

The list of allowed scopes is stored in the private property _allowed_scopes, and if no scope is set when the annotation is finally applied to a dataset, a default scope will be used that is stored in the private property _default_scope (and is defined as one element of the list of allowed scopes)

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

class aspecd.annotation.Artefact

Bases: aspecd.annotation.Annotation

Mark something as an artefact.

annotate(dataset=None, from_dataset=False)

Annotate a dataset with the given annotation.

If no dataset is provided at method call, but is set as property in the Annotation object, the process method of the dataset will be called and thus the history written.

If no dataset is provided at method call nor as property in the object, the method will raise a respective exception.

If no scope is set in the aspecd.annotation.Annotation object, a default value will be used that can be set in derived classes in the private property _default_scope. A full list of scopes is contained in the private property _allowed_scopes

The Dataset object always calls this method with the respective dataset as argument. Therefore, in this case setting the dataset property within the Annotation object is not necessary.

Parameters
  • dataset (aspecd.dataset.Dataset) – dataset to annotate

  • from_dataset (bool) –

    whether we are called from within a dataset

    Defaults to “False” and shall never be set manually.

Returns

dataset – dataset that has been annotated

Return type

aspecd.dataset.Dataset

create_history_record()

Create history record to be added to the dataset.

Usually, this method gets called from within the aspecd.dataset.annotate() method of the aspecd.dataset.Dataset class and ensures the history of each annotation step to get written properly.

Returns

history_record – history record for annotation step

Return type

aspecd.history.AnnotationHistoryRecord

property scope

Get or set the scope the annotation applies to.

The list of allowed scopes is stored in the private property _allowed_scopes, and if no scope is set when the annotation is finally applied to a dataset, a default scope will be used that is stored in the private property _default_scope (and is defined as one element of the list of allowed scopes)

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

class aspecd.annotation.Characteristic

Bases: aspecd.annotation.Annotation

Base class for characteristics.

annotate(dataset=None, from_dataset=False)

Annotate a dataset with the given annotation.

If no dataset is provided at method call, but is set as property in the Annotation object, the process method of the dataset will be called and thus the history written.

If no dataset is provided at method call nor as property in the object, the method will raise a respective exception.

If no scope is set in the aspecd.annotation.Annotation object, a default value will be used that can be set in derived classes in the private property _default_scope. A full list of scopes is contained in the private property _allowed_scopes

The Dataset object always calls this method with the respective dataset as argument. Therefore, in this case setting the dataset property within the Annotation object is not necessary.

Parameters
  • dataset (aspecd.dataset.Dataset) – dataset to annotate

  • from_dataset (bool) –

    whether we are called from within a dataset

    Defaults to “False” and shall never be set manually.

Returns

dataset – dataset that has been annotated

Return type

aspecd.dataset.Dataset

create_history_record()

Create history record to be added to the dataset.

Usually, this method gets called from within the aspecd.dataset.annotate() method of the aspecd.dataset.Dataset class and ensures the history of each annotation step to get written properly.

Returns

history_record – history record for annotation step

Return type

aspecd.history.AnnotationHistoryRecord

property scope

Get or set the scope the annotation applies to.

The list of allowed scopes is stored in the private property _allowed_scopes, and if no scope is set when the annotation is finally applied to a dataset, a default scope will be used that is stored in the private property _default_scope (and is defined as one element of the list of allowed scopes)

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