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.annotations.Artefact and aspecd.annotations.Characteristic. For other types of annotations, simply subclass the aspecd.annotations.Annotation base class.

exception aspecd.annotation.Error

Bases: Exception

Base class for exceptions in this module.

exception aspecd.annotation.MissingDatasetError(message='')

Bases: aspecd.annotation.Error

Exception raised when no dataset exists to act on

message

explanation of the error

Type

str

exception aspecd.annotation.NoContentError(message='')

Bases: aspecd.annotation.Error

Exception raised when no content was provided

message

explanation of the error

Type

str

exception aspecd.annotation.UnknownScopeError(message='')

Bases: aspecd.annotation.Error

Exception raised when unknown scope was tried to set

message

explanation of the error

Type

str

exception aspecd.annotation.MissingAnnotationError(message='')

Bases: aspecd.annotation.Error

Exception raised when no annotation exists to act on

message

explanation of the error

Type

str

class aspecd.annotation.Annotation

Bases: object

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
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.annotation.AnnotationHistoryRecord

class aspecd.annotation.Comment

Bases: aspecd.annotation.Annotation

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

comment

Get comment of annotation.

Returns

comment – Actual comment string

Return type

str

class aspecd.annotation.Artefact

Bases: aspecd.annotation.Annotation

Mark something as an artefact.

class aspecd.annotation.Characteristic

Bases: aspecd.annotation.Annotation

Base class for characteristics.

class aspecd.annotation.AnnotationRecord(annotation=None)

Bases: object

Base class for annotation records stored in the dataset annotations.

The annotation of a aspecd.dataset.Dataset should not contain references to aspecd.annotation.Annotation objects, but rather records that contain all necessary information to create the respective objects inherited from aspecd.annotation.Annotation. One reason for this is simply that we want to import datasets containing annotations in their analyses for which no corresponding annotation class exists in the current installation of the application. Another is to not have an infinite recursion of datasets, as the dataset is stored in an aspecd.analysis.SingleAnalysisStep object.

Note

Each annotation entry in a dataset stores the annotation as a aspecd.annotation.AnnotationRecord, even in applications inheriting from the ASpecD framework. Hence, subclassing of this class should normally not be necessary.

content

Actual content of the annotation

Generic place for more information

Type

dict

class_name

Fully qualified name of the class of the corresponding annotation

Type

str

Parameters

annotation (aspecd.annotation.Annotation) – Annotation the record should be created for.

Raises

aspecd.annotation.MissingAnnotationError – Raised when no annotation exists to act on

create_annotation()

Create an analysis step object from the parameters stored.

Returns

analysis_step – actual analysis step object that can be used for analysis

Return type

aspecd.analysis.SingleAnalysisStep

class aspecd.annotation.AnnotationHistoryRecord(annotation=None, package='')

Bases: aspecd.dataset.HistoryRecord

History record for annotations of datasets.

annotation

Annotation the history is saved for

Type

aspecd.analysis.Annotation

package

Name of package the history record gets recorded for

Prerequisite for reproducibility, gets stored in the aspecd.dataset.HistoryRecord.sysinfo attribute. Will usually be provided automatically by the dataset.

Type

str

Parameters