flexmeasures.data.models.annotations

Functions

flexmeasures.data.models.annotations.get_or_create_annotation(annotation: Annotation) → Annotation

Add annotation to db session if it doesn’t exist in the session already.

Return the old annotation object if it exists (and expunge the new one). Otherwise, return the new one.

flexmeasures.data.models.annotations.to_annotation_frame(annotations: list[Annotation]) → DataFrame

Transform a list of annotations into a DataFrame.

We don’t use a BeliefsDataFrame here, because they are designed for quantitative data only.

Classes

class flexmeasures.data.models.annotations.AccountAnnotationRelationship(**kwargs)

Links annotations to accounts.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

query: t.ClassVar[Query]

A SQLAlchemy query for a model. Equivalent to db.session.query(Model). Can be customized per-model by overriding query_class.

Warning

The query interface is considered legacy in SQLAlchemy. Prefer using session.execute(select()) instead.

class flexmeasures.data.models.annotations.Annotation(**kwargs)

An annotation is a nominal value that applies to a specific time or time span.

Examples of annotation types:

  • user annotation: annotation.type == “label” and annotation.source.type == “user”

  • unresolved alert: annotation.type == “alert”

  • resolved alert: annotation.type == “label” and annotation.source.type == “alerting script”

  • organisation holiday: annotation.type == “holiday” and annotation.source.type == “user”

  • public holiday: annotation.type == “holiday” and annotation.source.name == “workalendar”

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

classmethod add(df: DataFrame, annotation_type: str, expunge_session: bool = False, allow_overwrite: bool = False, bulk_save_objects: bool = False, commit_transaction: bool = False) → list[Annotation]

Add a data frame describing annotations to the database and return the Annotation objects.

Parameters:

  • df – Data frame describing annotations. Expects the following columns (or multi-index levels): - start - end or duration - content - belief_time - source

  • annotation_type – One of the possible Enum values for annotation.type

  • expunge_session – if True, all non-flushed instances are removed from the session before adding annotations. Expunging can resolve problems you might encounter with states of objects in your session. When using this option, you might want to flush newly-created objects which are not annotations (e.g. a sensor or data source object).

  • allow_overwrite – if True, new objects are merged if False, objects are added to the session or bulk saved

  • bulk_save_objects – if True, objects are bulk saved with session.bulk_save_objects(), which is quite fast but has several caveats, see: https://docs.sqlalchemy.org/orm/persistence_techniques.html#bulk-operations-caveats if False, objects are added to the session with session.add_all()

  • commit_transaction – if True, the session is committed if False, you can still add other data to the session and commit it all within an atomic transaction

query: t.ClassVar[Query]

A SQLAlchemy query for a model. Equivalent to db.session.query(Model). Can be customized per-model by overriding query_class.

Warning

The query interface is considered legacy in SQLAlchemy. Prefer using session.execute(select()) instead.

class flexmeasures.data.models.annotations.GenericAssetAnnotationRelationship(**kwargs)

Links annotations to generic assets.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

query: t.ClassVar[Query]

A SQLAlchemy query for a model. Equivalent to db.session.query(Model). Can be customized per-model by overriding query_class.

Warning

The query interface is considered legacy in SQLAlchemy. Prefer using session.execute(select()) instead.

class flexmeasures.data.models.annotations.SensorAnnotationRelationship(**kwargs)

Links annotations to sensors.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

query: t.ClassVar[Query]

A SQLAlchemy query for a model. Equivalent to db.session.query(Model). Can be customized per-model by overriding query_class.

Warning

The query interface is considered legacy in SQLAlchemy. Prefer using session.execute(select()) instead.