api_24sea.datasignals.schemas

Data signals types.

Classes

BaseDataSignalSchema	Shared base schema for data signals requests.
GetOldestTimestampSchema	Schema for oldest timestamp requests.
GetData	A pydantic schema for the data signals (data retrieval).
GetStats	A pydantic schema for the data signals (stats retrieval).
GetAvailability	A pydantic schema for the data signals (availability retrieval).

Functions

build_query_str(→ str)	Build a query string based on the provided BaseDataSignalSchema instance.
get_selected_metrics(→ pandas.DataFrame)	Calculate the selected metrics DataFrame based on the metrics_overview,
get_selected_locations(→ pandas.DataFrame)	Calculate the selected locations DataFrame based on the metrics_overview,

Module Contents

class BaseDataSignalSchema(**data)

Shared base schema for data signals requests. Includes common fields and validation logic for timestamp, sites, locations, metrics, and headers. Inherit from this class to create specific schemas for data retrieval and stats retrieval.

validate_timestamp(v: datetime.datetime | str) → str

Validate and format timestamp input.

validate_sites_locations(v)

Validate and format sites and locations input.

validate_metrics(v)

Validate and format metrics input.

validate_headers(v)

Validate and format headers input.

validate_method(v: str) → str

Validate and normalize request method input.

property query_str: str

Build a query string based on self.

get_selected_metrics(df: pandas.DataFrame | None, log: bool = True) → pandas.DataFrame

Calculate the selected metrics DataFrame based on a df (metrics overview) and the query object.

group_metrics(df: pandas.DataFrame | None) → pandas.core.groupby.DataFrameGroupBy

Group metrics by site and location.

group_metrics_by_site(df: pandas.DataFrame | None) → pandas.core.groupby.DataFrameGroupBy

Group metrics by site while keeping per-site locations.

class GetOldestTimestampSchema(/, **data: Any)

Schema for oldest timestamp requests.

validate_locations(v) → str | None

Normalize locations to a comma-separated lower-case string.

validate_site(v)

Normalize site to a lower-case string.

validate_method(v: str) → str

Validate and normalize request method input.

get_selected_locations(df: pandas.DataFrame | None) → pandas.DataFrame

Get the selected locations DataFrame based on the query object.

class GetData(**data)

A pydantic schema for the data signals (data retrieval). Includes all common fields plus ‘outer_join_on_timestamp’ for join behavior.

class GetStats(**data)

A pydantic schema for the data signals (stats retrieval). Inherits all common fields from the base schema.

class GetAvailability(**data)

A pydantic schema for the data signals (availability retrieval). Inherits all common fields from the base schema.

build_query_str(query: BaseDataSignalSchema) → str

Build a query string based on the provided BaseDataSignalSchema instance.

Parameters

queryBaseDataSignalSchema

The query object containing the filtering criteria.

Returns

str

The constructed query string.

get_selected_metrics(query: BaseDataSignalSchema, metrics_overview: pandas.DataFrame, log: bool = True) → pandas.DataFrame

Calculate the selected metrics DataFrame based on the metrics_overview, and the query object.

Parameters

metrics_overviewpd.DataFrame

The metrics overview DataFrame.

query_strstr

The query string to filter metrics.

logbool, optional

Whether to log the selected metrics, by default True.

Returns

pd.DataFrame

The filtered and sorted metrics DataFrame.

get_selected_locations(query: GetOldestTimestampSchema, metrics_overview: pandas.DataFrame, log: bool = True) → pandas.DataFrame

Calculate the selected locations DataFrame based on the metrics_overview, and the query object.

Parameters

query: GetOldestTimestampSchema

Timestamp schema query class instance.

metrics_overviewpd.DataFrame

The metrics overview DataFrame.

logbool, optional

Whether to log the selected locations, by default True.

Returns

pd.DataFrame

The filtered and sorted locations DataFrame.