aspecd.history module

History: Classes collecting information on what has been done to a dataset.

Reproducibility is an essential aspect of good scientific practice. In the context of data processing and analysis, this means that each processing step performed on data (of a dataset) should be stored in an reproducible way and preferably in a consistent format.

To be of actual use, an entry of the history needs to contain all information necessary to reproduce the processing step in its original form. This includes as a minimum the name of the processing routine used, the complete list of necessary parameters for that routine, and a unique version information of the routine. Additional useful aspects contain information about the operating system used, the name of the operator, and the date the processing step has been performed.

class aspecd.history.HistoryRecord(package='')

Bases: aspecd.utils.ToDictMixin

Generic base class for all kinds of history records.

For all classes operating on datasets, such as aspecd.processing.ProcessingStep, aspecd.analysis.SingleAnalysisStep and others, there exist at least two “representations”: (i) the generic one not (necessarily) tied to any concrete dataset, thus portable, and (ii) a concrete one having operated on a dataset and thus being accompanied with information about who has done what when how to what dataset.

For this second type, a history class derived from aspecd.dataset.HistoryRecord gets used, and it is this second type that is stored inside the Dataset object.

date

datetime object with date current at HistoryRecord instantiation

Type

datetime.datetime

sysinfo

key–value store with crucial system parameters, including user login name

Type

aspecd.system.SystemInfo

Parameters

package (str) –

Name of package the history record gets recorded for

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

from_dict(dict_=None)

Set properties from dictionary.

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

Datetime objects are set correctly from the string.

If the corresponding attribute is an object having a from_dict method itself, this method will be called accordingly, making cascading calls possible.

Parameters

dict (dict) – Dictionary containing properties to set

to_dict()

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict

class aspecd.history.ProcessingStepRecord(processing_step=None)

Bases: aspecd.utils.ToDictMixin

Base class for processing step records stored in the dataset history.

The history of a aspecd.dataset.Dataset should not contain references to aspecd.processing.ProcessingStep objects, but rather records that contain all necessary information to create the respective objects inherited from aspecd.processing.ProcessingStep. One reason for this is simply that we want to import datasets containing processing steps in their history for which no corresponding processing class exists in the current installation of the application.

Note

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

undoable

Can this processing step be reverted?

Type

bool

description

Short description, to be set in class definition

Type

str

parameters

Parameters required for performing the processing step

All parameters, implicit and explicit.

Type

dict

comment

User-supplied comment describing intent, purpose, reason, …

Type

str

class_name

Fully qualified name of the class of the corresponding processing step

Type

str

Parameters

processing_step (aspecd.processing.ProcessingStep) – Processing step the record should be created for.

Raises

aspecd.processing.MissingProcessingStepError – Raised when no processing step exists to act on

from_processing_step(processing_step)

Obtain information from processing step.

Parameters

processing_step (aspecd.processing.ProcessingStep) – Object to obtain information from

create_processing_step()

Create a processing step object from the parameters stored.

Returns

processing_step – actual processing step object that can be used for processing, e.g., in context of undo/redo

Return type

aspecd.processing.ProcessingStep

from_dict(dict_=None)

Set properties from dictionary.

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

Parameters

dict (dict) – Dictionary containing properties to set

to_dict()

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict

class aspecd.history.ProcessingHistoryRecord(processing_step=None, package='')

Bases: aspecd.history.HistoryRecord

History record for processing steps on datasets.

processing

record of the processing step

Type

aspecd.history.ProcessingStepRecord

Parameters
  • processing_step (aspecd.processing.ProcessingStep) – processing step the history is saved for

  • package (str) –

    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.

property undoable

Can this processing step be reverted?

replay(dataset)

Replay the processing step saved in the history record.

Parameters

dataset (aspecd.dataset.Dataset) – dataset the processing step should be replayed to

from_dict(dict_=None)

Set properties from dictionary.

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

Datetime objects are set correctly from the string.

If the corresponding attribute is an object having a from_dict method itself, this method will be called accordingly, making cascading calls possible.

Parameters

dict (dict) – Dictionary containing properties to set

to_dict()

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict

class aspecd.history.AnalysisStepRecord(analysis_step=None)

Bases: aspecd.utils.ToDictMixin

Base class for analysis step records.

The analysis of a aspecd.dataset.Dataset should not contain references to aspecd.analysis.AnalysisStep objects, but rather records that contain all necessary information to create the respective objects inherited from aspecd.analysis.AnalysisStep. One reason for this is simply that we want to import datasets containing analysis steps in their analyses for which no corresponding analysis 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.AnalysisStep object.

description

Short description, to be set in class definition

Type

str

parameters

Parameters required for performing the analysis step

All parameters, implicit and explicit.

Type

dict

result

Results of the analysis step

Can be either a aspecd.dataset.Dataset or some other class, e.g., aspecd.metadata.PhysicalQuantity.

In case of a dataset, it is a calculated dataset (aspecd.dataset.CalculatedDataset)

comment

User-supplied comment describing intent, purpose, reason, …

Type

str

class_name

Fully qualified name of the class of the corresponding analysis step

Type

str

Parameters

analysis_step (aspecd.analysis.SingleAnalysisStep) – Analysis step the record should be created for.

Raises

aspecd.analysis.MissingAnalysisStepError – Raised when no analysis step exists to act on

from_analysis_step(analysis_step)

Obtain information from analysis step.

Parameters

analysis_step (aspecd.analysis.AnalysisStep) – Object to obtain information from

create_analysis_step()

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

from_dict(dict_=None)

Set properties from dictionary.

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

Parameters

dict (dict) – Dictionary containing properties to set

to_dict()

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict

class aspecd.history.SingleAnalysisStepRecord(analysis_step=None)

Bases: aspecd.history.AnalysisStepRecord

Base class for analysis step records stored in the dataset analyses.

The analysis of a aspecd.dataset.Dataset should not contain references to aspecd.analysis.AnalysisStep objects, but rather records that contain all necessary information to create the respective objects inherited from aspecd.analysis.AnalysisStep. One reason for this is simply that we want to import datasets containing analysis steps in their analyses for which no corresponding analysis 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.AnalysisStep object.

Note

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

preprocessing

List of processing steps

The actual processing steps are objects of the class aspecd.processing.ProcessingStepRecord.

Type

list

Parameters

analysis_step (aspecd.analysis.SingleAnalysisStep) – Analysis step the record should be created for.

from_analysis_step(analysis_step)

Obtain information from analysis step.

Parameters

analysis_step (aspecd.analysis.AnalysisStep) – Object to obtain information from

create_analysis_step()

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

from_dict(dict_=None)

Set properties from dictionary.

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

Parameters

dict (dict) – Dictionary containing properties to set

to_dict()

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict

class aspecd.history.AnalysisHistoryRecord(analysis_step=None, package='')

Bases: aspecd.history.HistoryRecord

History record for analysis steps on datasets.

analysis

Analysis step the history is saved for

Type

aspecd.analysis.SingleAnalysisStep

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
replay(dataset)

Replay the analysis step saved in the history record.

Parameters

dataset (aspecd.dataset.Dataset) – dataset the analysis step should be replayed to

from_dict(dict_=None)

Set properties from dictionary.

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

Datetime objects are set correctly from the string.

If the corresponding attribute is an object having a from_dict method itself, this method will be called accordingly, making cascading calls possible.

Parameters

dict (dict) – Dictionary containing properties to set

to_dict()

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict

class aspecd.history.AnnotationRecord(annotation=None)

Bases: aspecd.utils.ToDictMixin

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

from_annotation(annotation)

Obtain information from annotation.

Parameters

annotation (aspecd.annotation.Annotation) – Object to obtain information from

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

from_dict(dict_=None)

Set properties from dictionary.

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

Parameters

dict (dict) – Dictionary containing properties to set

to_dict()

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict

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

Bases: aspecd.history.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
  • annotation (aspecd.annotation.AnnotationRecord) – Annotation the history is saved for

  • package (str) – Name of package the history record gets recorded for

from_dict(dict_=None)

Set properties from dictionary.

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

Datetime objects are set correctly from the string.

If the corresponding attribute is an object having a from_dict method itself, this method will be called accordingly, making cascading calls possible.

Parameters

dict (dict) – Dictionary containing properties to set

to_dict()

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict

class aspecd.history.PlotRecord(plotter=None)

Bases: aspecd.utils.ToDictMixin

Base class for records storing information about a plot.

For reproducibility of plots performed on either a single dataset or multiple datasets, information for each plot needs to be collected that suffices to reproduce the plot. This is what a PlotRecord is good for.

All information will usually be obtained from a plotter object, either by instantiating a PlotRecord object providing a plotter object, or by calling from_plotter() on a PlotRecord object.

Subclasses for aspecd.plotting.SinglePlotter and aspecd.plotting.MultiPlotter objects are available, namely aspecd.plotting.SinglePlotRecord and aspecd.plotting.MultiPlotRecord.

class_name

Name of the plotter.

Defaults to the plotter class name and shall never be set manually.

Type

str

description

Short description of the plot

Type

str

parameters

All parameters necessary for the plot, implicit and explicit

Type

dict

properties

Properties of the plot, defining its appearance

Type

aspecd.plotting.PlotProperties

caption

User-supplied information for the figure.

Type

aspecd.plotting.Caption

filename

Name of the file the plot has been/should be saved to

Type

str

Parameters

plotter (aspecd.plotting.Plotter) – Plotter object to obtain information from

Raises

aspecd.plotting.MissingPlotterError – Raised if no plotter is provided.

from_plotter(plotter=None)

Obtain information from plotter.

Parameters

plotter (aspecd.plotting.Plotter) – Plotter object to obtain information from

Raises

aspecd.plotting.MissingPlotterError – Raised if no plotter is provided.

from_dict(dict_=None)

Set properties from dictionary.

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

Parameters

dict (dict) – Dictionary containing properties to set

to_dict()

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict

class aspecd.history.SinglePlotRecord(plotter=None)

Bases: aspecd.history.PlotRecord

Record for SinglePlotter objects.

When plotting data of a single dataset, classes derived from aspecd.plotting.SinglePlotter will be used. The information obtained from these plotters will be stored in a SinglePlotRecord object.

preprocessing

List of processing steps

The actual processing steps are objects of the class aspecd.processing.ProcessingStepRecord.

Type

list

Parameters

plotter (aspecd.plotting.Plotter) – Plotter object to obtain information from

from_dict(dict_=None)

Set properties from dictionary.

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

Parameters

dict (dict) – Dictionary containing properties to set

from_plotter(plotter=None)

Obtain information from plotter.

Parameters

plotter (aspecd.plotting.Plotter) – Plotter object to obtain information from

Raises

aspecd.plotting.MissingPlotterError – Raised if no plotter is provided.

to_dict()

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict

class aspecd.history.MultiPlotRecord(plotter=None)

Bases: aspecd.history.PlotRecord

Record for MultiPlotter objects.

When plotting data of multiple datasets, classes derived from aspecd.plotting.MultiPlotter will be used. The information obtained from these plotters will be stored in a MultiPlotRecord object.

datasets

List of datasets whose data appear in the plot.

Type

list

Parameters

plotter (aspecd.plotting.Plotter) – Plotter object to obtain information from

from_dict(dict_=None)

Set properties from dictionary.

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

Parameters

dict (dict) – Dictionary containing properties to set

from_plotter(plotter=None)

Obtain information from plotter.

Parameters

plotter (aspecd.plotting.Plotter) – Plotter object to obtain information from

Raises

aspecd.plotting.MissingPlotterError – Raised if no plotter is provided.

to_dict()

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict

class aspecd.history.PlotHistoryRecord(package='')

Bases: aspecd.history.HistoryRecord

History record for plots of datasets.

plot

Plot the history is saved for

Type

aspecd.plotting.SinglePlotRecord

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

from_dict(dict_=None)

Set properties from dictionary.

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

Datetime objects are set correctly from the string.

If the corresponding attribute is an object having a from_dict method itself, this method will be called accordingly, making cascading calls possible.

Parameters

dict (dict) – Dictionary containing properties to set

to_dict()

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict