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.

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.