flexmeasures.data.models.time_series

Classes

class flexmeasures.data.models.time_series.Sensor(name, generic_asset=None, generic_asset_id=None, attributes=None, **kwargs)

A sensor measures events.

__init__(name, generic_asset=None, generic_asset_id=None, attributes=None, **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.

chart(chart_type: str = 'bar_chart', event_starts_after: datetime_type | None = None, event_ends_before: datetime_type | None = None, beliefs_after: datetime_type | None = None, beliefs_before: datetime_type | None = None, source: DataSource | list[DataSource] | int | list[int] | str | list[str] | None = None, most_recent_beliefs_only: bool = True, include_data: bool = False, include_sensor_annotations: bool = False, include_asset_annotations: bool = False, include_account_annotations: bool = False, dataset_name: str | None = None, **kwargs) → dict

Create a vega-lite chart showing sensor data.

Parameters:

chart_type – currently only “bar_chart” # todo: where can we properly list the available chart types?
event_starts_after – only return beliefs about events that start after this datetime (inclusive)
event_ends_before – only return beliefs about events that end before this datetime (inclusive)
beliefs_after – only return beliefs formed after this datetime (inclusive)
beliefs_before – only return beliefs formed before this datetime (inclusive)
source – search only beliefs by this source (pass the DataSource, or its name or id) or list of sources
most_recent_beliefs_only – only return the most recent beliefs for each event from each source (minimum belief horizon)
include_data – if True, include data in the chart, or if False, exclude data
include_sensor_annotations – if True and include_data is True, include sensor annotations in the chart, or if False, exclude these
include_asset_annotations – if True and include_data is True, include asset annotations in the chart, or if False, exclude them
include_account_annotations – if True and include_data is True, include account annotations in the chart, or if False, exclude them
dataset_name – optionally name the dataset used in the chart (the default name is sensor_<id>)

Returns:

JSON string defining vega-lite chart specs

check_required_attributes(attributes: list[str | tuple[str, Type | tuple[Type, ...]]])

Raises if any attribute in the list of attributes is missing, or has the wrong type.

Parameters:: attributes – List of either an attribute name or a tuple of an attribute name and its allowed type (the allowed type may also be a tuple of several allowed types)

event_resolution: timedelta

classmethod find_closest(generic_asset_type_name: str, sensor_name: str, n: int = 1, **kwargs) → 'Sensor' | list['Sensor'] | None

Returns the closest n sensors within a given asset type (as a list if n > 1). Parses latitude and longitude values stated in kwargs.

Can be called with an object that has latitude and longitude properties, for example:

sensor = Sensor.find_closest(“weather station”, “wind speed”, object=generic_asset)

Can also be called with latitude and longitude parameters, for example:

sensor = Sensor.find_closest(“weather station”, “temperature”, latitude=32, longitude=54) sensor = Sensor.find_closest(“weather station”, “temperature”, lat=32, lng=54)

Finally, pass in an account_id parameter if you want to query an account other than your own. This only works for admins. Public assets are always queried.

get_attribute(attribute: str, default: Any | None = None) → Any: Looks for the attribute on the Sensor. If not found, looks for the attribute on the Sensor’s GenericAsset. If not found, returns the default.

id

property is_strictly_non_negative: bool: Return True if this sensor strictly records non-negative values.

property is_strictly_non_positive: bool: Return True if this sensor strictly records non-positive values.

knowledge_horizon_fnc: str

knowledge_horizon_par: dict

Search the most recent event for this sensor, and return the most recent ex-post belief.

Parameters:: source – search only beliefs by this source (pass the DataSource, or its name or id) or list of sources

make_hashable() → tuple: Returns a tuple with the properties subject to change In principle all properties (except ID) of a given sensor could be changed, but not all changes are relevant to warrant reanalysis (e.g. scheduling or forecasting).

property measures_energy: bool: True if this sensor’s unit is measuring energy

property measures_energy_price: bool: True if this sensors’ unit is measuring energy prices

property measures_power: bool: True if this sensor’s unit is measuring power

name: str

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.

Return annotations assigned to this sensor, and optionally, also those assigned to the sensor’s asset and the asset’s account.

Parameters:

annotations_after – only return annotations that end after this datetime (exclusive)
annotations_before – only return annotations that start before this datetime (exclusive)

search_beliefs(event_starts_after: datetime_type | None = None, event_ends_before: datetime_type | None = None, beliefs_after: datetime_type | None = None, beliefs_before: datetime_type | None = None, horizons_at_least: timedelta | None = None, horizons_at_most: timedelta | None = None, source: DataSource | list[DataSource] | int | list[int] | str | list[str] | None = None, most_recent_beliefs_only: bool = True, most_recent_events_only: bool = False, most_recent_only: bool = None, one_deterministic_belief_per_event: bool = False, one_deterministic_belief_per_event_per_source: bool = False, resolution: str | timedelta = None, as_json: bool = False) → tb.BeliefsDataFrame | str

Search all beliefs about events for this sensor.

If you don’t set any filters, you get the most recent beliefs about all events.

Parameters:

event_starts_after – only return beliefs about events that start after this datetime (inclusive)
event_ends_before – only return beliefs about events that end before this datetime (inclusive)
beliefs_after – only return beliefs formed after this datetime (inclusive)
beliefs_before – only return beliefs formed before this datetime (inclusive)
horizons_at_least – only return beliefs with a belief horizon equal or greater than this timedelta (for example, use timedelta(0) to get ante knowledge time beliefs)
horizons_at_most – only return beliefs with a belief horizon equal or less than this timedelta (for example, use timedelta(0) to get post knowledge time beliefs)
source – search only beliefs by this source (pass the DataSource, or its name or id) or list of sources
most_recent_beliefs_only – only return the most recent beliefs for each event from each source (minimum belief horizon)
most_recent_events_only – only return (post knowledge time) beliefs for the most recent event (maximum event start)
one_deterministic_belief_per_event – only return a single value per event (no probabilistic distribution and only 1 source)
one_deterministic_belief_per_event_per_source – only return a single value per event per source (no probabilistic distribution)
as_json – return beliefs in JSON format (e.g. for use in charts) rather than as BeliefsDataFrame

Returns:

BeliefsDataFrame or JSON string (if as_json is True)

property timerange: dict[str, datetime]

Time range for which sensor data exists.

Returns:

dictionary with start and end, for example: {

’start’: datetime.datetime(2020, 12, 3, 14, 0, tzinfo=pytz.utc), ‘end’: datetime.datetime(2020, 12, 3, 14, 30, tzinfo=pytz.utc)

}

timezone: str

unit: str

class flexmeasures.data.models.time_series.TimedBelief(sensor, source, **kwargs)

A timed belief holds a precisely timed record of a belief about an event.

It also records the source of the belief, and the sensor that the event pertains to.

__init__(sensor, source, **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(bdf: BeliefsDataFrame, expunge_session: bool = False, allow_overwrite: bool = False, bulk_save_objects: bool = False, commit_transaction: bool = False)

Add a BeliefsDataFrame as timed beliefs in the database.

Parameters:

bdf – the BeliefsDataFrame to be persisted
expunge_session – if True, all non-flushed instances are removed from the session before adding beliefs. 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 beliefs (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

belief_horizon: timedelta

cumulative_probability: float

event_start: datetime

event_value: float

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.

Search all beliefs about events for the given sensors.

If you don’t set any filters, you get the most recent beliefs about all events.

Parameters:

sensors – search only these sensors, identified by their instance or id (both unique) or name (non-unique)
event_starts_after – only return beliefs about events that start after this datetime (inclusive)
event_ends_before – only return beliefs about events that end before this datetime (inclusive)
beliefs_after – only return beliefs formed after this datetime (inclusive)
beliefs_before – only return beliefs formed before this datetime (inclusive)
horizons_at_least – only return beliefs with a belief horizon equal or greater than this timedelta (for example, use timedelta(0) to get ante knowledge time beliefs)
horizons_at_most – only return beliefs with a belief horizon equal or less than this timedelta (for example, use timedelta(0) to get post knowledge time beliefs)
source – search only beliefs by this source (pass the DataSource, or its name or id) or list of sources
user_source_ids – Optional list of user source ids to query only specific user sources
source_types – Optional list of source type names to query only specific source types *
exclude_source_types – Optional list of source type names to exclude specific source types *
most_recent_beliefs_only – only return the most recent beliefs for each event from each source (minimum belief horizon)
most_recent_events_only – only return (post knowledge time) beliefs for the most recent event (maximum event start)
one_deterministic_belief_per_event – only return a single value per event (no probabilistic distribution and only 1 source)
one_deterministic_belief_per_event_per_source – only return a single value per event per source (no probabilistic distribution)
resolution – Optional timedelta or pandas freqstr used to resample the results **
sum_multiple – if True, sum over multiple sensors; otherwise, return a dictionary with sensors as key, each holding a BeliefsDataFrame as its value

If user_source_ids is specified, the “user” source type is automatically included (and not excluded). Somewhat redundant, though still allowed, is to set both source_types and exclude_source_types.

** Note that:

timely-beliefs converts string resolutions to datetime.timedelta objects (see https://github.com/SeitaBV/timely-beliefs/issues/13).
for sensors recording non-instantaneous data: updates both the event frequency and the event resolution
for sensors recording instantaneous data: updates only the event frequency (and event resolution remains 0)

sensor_id

source_id