api_24sea.datasignals#

The module for the DataSignals pandas accessor containing the main class and the methods to authenticate, get metrics, and get data from the 24SEA API.

Submodules#

Classes#

DataSignals

Accessor for working with data signals coming from the 24SEA API.

Package Contents#

class DataSignals(pandasdata: pandas.DataFrame)#

Accessor for working with data signals coming from the 24SEA API.

property authenticated: bool#

Return the authentication status.

property metrics_overview: pandas.DataFrame | None#

Get the metrics overview DataFrame.

authenticate(username: str, password: str, __metrics_overview: pandas.DataFrame | None = None) → pandas.DataFrame#

Authenticate the user with the 24SEA API. Additionally, define the metrics_overview dataframe as __api.metrics_overview.

Parameters#

usernamestr

The username to authenticate.

passwordstr

The password to authenticate.

Returns#

pd.DataFrame

The authenticated DataFrame.

property selected_metrics: pandas.DataFrame#

Return the selected metrics for the query.

put_data(site: str | None = None, location: str | None = None, on_conflict: str = 'replace', include_cyclecount: bool = True, profile: bool = False, headers: Dict[str, str] | None = None, timeout: int = 3600, max_retries: int = 0) → Dict[str, Any]#

Write this DataFrame by inserting or fully replacing rows.

timestamp, site, and location may be columns in the DataFrame. Scalar site and location values can be supplied when those columns are absent.

patch_data(site: str | None = None, location: str | None = None, on_conflict: str = 'replace', include_cyclecount: bool = True, profile: bool = False, headers: Dict[str, str] | None = None, timeout: int = 3600, max_retries: int = 0) → Dict[str, Any]#

Write this DataFrame by merging supplied metric keys.

as_dict(metrics_map: pandas.DataFrame | None = None) → Dict[str, Dict[str, pandas.DataFrame]]#

Return the DataFrames as a dictionary where the keys are the sites and the values are a dictionary where the keys are locations and the values are dataframes for each location.

Parameters#

metrics_mapOptional[pd.DataFrame], optional

The DataFrame containing the metrics map. If None, the selected_metrics attribute will be used. Default is None.

Returns#

Dict[str, Dict[str, pd.DataFrame]]

The dictionary containing the dataframes for each site.

Example#

>>> import pandas as pd
>>> import api_24sea as sea
>>> df = pd.DataFrame({
...     "timestamp": ["2021-01-01", "2021-01-02"],
...     "mean_WF_A01_windspeed": [10.0, 11.0],
...     "mean_WF_A02_windspeed": [12.0, 13.0]
... })
>>> metrics_map = pd.DataFrame({
...     "site": ["wf", "wf"],
...     "location": ["a01", "a02"],
...     "metric": ["mean_WF_A01_windspeed", "mean_WF_A02_windspeed"]
... })
>>> df.datasignals.as_dict(metrics_map)
# output
{
    "wf": {
        "a01": pd.DataFrame({
            "timestamp": ["2021-01-01", "2021-01-02"],
            "mean_WF_A01_windspeed": [10.0, 11.0]
        }),
        "a02": pd.DataFrame({
            "timestamp": ["2021-01-01", "2021-01-02"],
            "mean_WF_A02_windspeed": [12.0, 13.0]
        })
    }
}
get_data(sites: List | str | None, locations: List | str | None, metrics: List | str, start_timestamp: str | datetime.datetime, end_timestamp: str | datetime.datetime, location: List | str | None = None, force_cache_miss: bool = False, method: str = 'GET') → pandas.DataFrame | Dict[str, Dict[str, pandas.DataFrame] | Dict[str, Any]] | List[Any | str] | None#

Get the data signals from the 24SEA API.

Parameters#

sitesOptional[Union[List, str]]

The site name or List of site names. If None, the site will be inferred from the metrics.

locationsOptional[Union[List, str]]

The location name or List of location names. If None, the location will be inferred from the metrics.

metricsUnion[List, str]

The metric name or List of metric names. It must be provided. They do not have to be the entire metric name, but can be a part of it. For example, if the metric name is "mean_WF_A01_windspeed", the user can equivalently provide sites="wf", locations="a01", metric="mean windspeed".

start_timestampUnion[str, datetime.datetime]

The start timestamp for the query. It must be in ISO 8601 format, e.g., "2021-01-01T00:00:00Z" or a datetime object.

end_timestampUnion[str, datetime.datetime]

The end timestamp for the query. It must be in ISO 8601 format, e.g., "2021-01-01T00:00:00Z" or a datetime object.

Returns#

Union[pd.DataFrame, Dict[str, Dict[str, pd.DataFrame]]]

The DataFrame containing the data signals, or the dictionary containing the dataframes for each site and location.