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.ToDictMixinAnnotations 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
-
dataset¶ Dataset the annotation belongs to
- 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.Annotationobject, 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_scopesThe 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 annotatefrom_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
-
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 theaspecd.dataset.Datasetclass and ensures the history of each annotation step to get written properly.- Returns
history_record – history record for annotation step
- Return type
-
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
Changed in version 0.6: New parameter remove_empty
-
-
class
aspecd.annotation.Comment¶ Bases:
aspecd.annotation.AnnotationThe most basic form of annotation: a simple textual comment.
-
property
comment¶ Get comment of annotation.
- Returns
comment – Actual comment string
- Return type
-
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.Annotationobject, 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_scopesThe 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 annotatefrom_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
-
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 theaspecd.dataset.Datasetclass and ensures the history of each annotation step to get written properly.- Returns
history_record – history record for annotation step
- Return type
-
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
Changed in version 0.6: New parameter remove_empty
-
property
-
class
aspecd.annotation.Artefact¶ Bases:
aspecd.annotation.AnnotationMark 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.Annotationobject, 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_scopesThe 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 annotatefrom_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
-
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 theaspecd.dataset.Datasetclass and ensures the history of each annotation step to get written properly.- Returns
history_record – history record for annotation step
- Return type
-
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
Changed in version 0.6: New parameter remove_empty
-
-
class
aspecd.annotation.Characteristic¶ Bases:
aspecd.annotation.AnnotationBase 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.Annotationobject, 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_scopesThe 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 annotatefrom_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
-
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 theaspecd.dataset.Datasetclass and ensures the history of each annotation step to get written properly.- Returns
history_record – history record for annotation step
- Return type
-
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
Changed in version 0.6: New parameter remove_empty
-