flexmeasures.data.queries.utils

Functions

flexmeasures.data.queries.utils.create_beliefs_query(cls: Type[ts.TimedValue], session: Session, old_sensor_class: db.Model, old_sensor_names: tuple[str], start: datetime | None, end: datetime | None) → Select

flexmeasures.data.queries.utils.get_belief_timing_criteria(cls: Type[ts.TimedValue], asset_class: db.Model, belief_horizon_window: tuple[timedelta | None, timedelta | None], belief_time_window: tuple[datetime | None, datetime | None]) → list[BinaryExpression]

Get filter criteria for the desired windows with relevant belief times and belief horizons.

# todo: interpret belief horizons with respect to knowledge time rather than event end. - a positive horizon denotes a before-the-fact belief (ex-ante w.r.t. knowledge time) - a negative horizon denotes an after-the-fact belief (ex-post w.r.t. knowledge time)

Parameters:

belief_horizon_window – short belief horizon and long belief horizon, each an optional timedelta Interpretation: - a positive short horizon denotes “at least <horizon> before the fact” (min ex-ante) - a positive long horizon denotes “at most <horizon> before the fact” (max ex-ante) - a negative short horizon denotes “at most <horizon> after the fact” (max ex-post) - a negative long horizon denotes “at least <horizon> after the fact” (min ex-post)
belief_time_window – earliest belief time and latest belief time, each an optional datetime

Examples (assuming the knowledge time of each event coincides with the end of the event):

# Query beliefs formed between 1 and 7 days before each individual event belief_horizon_window = (timedelta(days=1), timedelta(days=7))

# Query beliefs formed at least 2 hours before each individual event belief_horizon_window = (timedelta(hours=2), None)

# Query beliefs formed at most 2 hours after each individual event belief_horizon_window = (-timedelta(hours=2), None)

# Query beliefs formed at least after each individual event belief_horizon_window = (None, timedelta(hours=0))

# Query beliefs formed from May 2nd to May 13th (left inclusive, right exclusive) belief_time_window = (datetime(2020, 5, 2), datetime(2020, 5, 13))

# Query beliefs formed from May 14th onwards belief_time_window = (datetime(2020, 5, 14), None)

# Query beliefs formed before May 13th belief_time_window = (None, datetime(2020, 5, 13))

flexmeasures.data.queries.utils.get_source_criteria(cls: Type[ts.TimedValue] | Type[ts.TimedBelief], user_source_ids: int | list[int], source_types: list[str], exclude_source_types: list[str]) → list[BinaryExpression]

flexmeasures.data.queries.utils.multiply_dataframe_with_deterministic_beliefs(df1: pd.DataFrame, df2: pd.DataFrame, multiplication_factor: float = 1, result_source: str | None = None) → pd.DataFrame

Create new DataFrame where the event_value columns of df1 and df2 are multiplied.

If df1 and df2 have belief_horizon columns, the belief_horizon column of the new DataFrame is determined as the minimum of the input horizons. The source columns of df1 and df2 are not used. A source column for the new DataFrame can be set by passing a result_source (string).

The index of the resulting DataFrame contains the outer join of the indices of df1 and df2. Event values are np.nan for rows that are not in both DataFrames.

Parameters:

df1 – DataFrame with “event_value” column and optional “belief_horizon” and “source” columns
df2 – DataFrame with “event_value” column and optional “belief_horizon” and “source” columns
multiplication_factor – extra scalar to determine the event_value of the resulting DataFrame
result_source – string label for the source of the resulting DataFrame

Returns:

DataFrame with “event_value” column, an additional “belief_horizon” column if both df1 and df2 contain this column, and an additional “source” column if result_source is set.

flexmeasures.data.queries.utils.potentially_limit_assets_query_to_account(query: Select[tuple[GenericAsset]], account_id: int | None = None) → Select[tuple[GenericAsset]]

Filter out all assets that are not in the current user’s account. For admins and CLI users, no assets are filtered out, unless an account_id is set.

Parameters:: account_id – if set, all assets that are not in the given account will be filtered out (only works for admins and CLI users). For querying public assets in particular, don’t use this function.

flexmeasures.data.queries.utils.simplify_index(bdf: tb.BeliefsDataFrame, index_levels_to_columns: list[str] | None = None) → pd.DataFrame

Drops indices other than event_start. Optionally, salvage index levels as new columns.

Because information stored in the index levels is potentially lost*, we cannot guarantee a complete description of beliefs in the BeliefsDataFrame. Therefore, we type the result as a regular pandas DataFrame.

The index levels are dropped (by overwriting the multi-level index with just the “event_start” index level). Only for the columns named in index_levels_to_columns, the relevant information is kept around.

flexmeasures.data.queries.utils.source_type_criterion(source_types: list[str]) → BinaryExpression: Criterion to collect only data from sources that are of the given type.

flexmeasures.data.queries.utils.source_type_exclusion_criterion(source_types: list[str]) → BinaryExpression: Criterion to exclude sources that are of the given type.

flexmeasures.data.queries.utils.user_source_criterion(cls: Type[ts.TimedValue] | Type[ts.TimedBelief], user_source_ids: int | list[int]) → BinaryExpression

Criterion to search only through user data from the specified user sources.

We distinguish user sources (sources with source.type == “user”) from other sources (source.type != “user”). Data with a user source originates from a registered user. Data with e.g. a script source originates from a script.

This criterion doesn’t affect the query over non-user type sources. It does so by ignoring user sources that are not in the given list of source_ids.