api_24sea.datasignals
=====================

.. py:module:: api_24sea.datasignals

.. autoapi-nested-parse::

   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
----------

.. toctree::
   :maxdepth: 1

   /autoapi/api_24sea/datasignals/core/index
   /autoapi/api_24sea/datasignals/fatigue/index
   /autoapi/api_24sea/datasignals/schemas/index


Classes
-------

.. autoapisummary::

   api_24sea.datasignals.DataSignals


Package Contents
----------------

.. py:class:: DataSignals(pandasdata: pandas.DataFrame)

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


   .. py:property:: authenticated
      :type: bool


      Return the authentication status.



   .. py:property:: metrics_overview
      :type: Optional[pandas.DataFrame]


      Get the metrics overview DataFrame.



   .. py:method:: authenticate(username: str, password: str, __metrics_overview: Optional[pandas.DataFrame] = None) -> pandas.DataFrame

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

      Parameters
      ----------
      username : str
          The username to authenticate.
      password : str
          The password to authenticate.

      Returns
      -------
      pd.DataFrame
          The authenticated DataFrame.



   .. py:property:: selected_metrics
      :type: pandas.DataFrame


      Return the selected metrics for the query.



   .. py:method:: as_dict(metrics_map: Optional[pandas.DataFrame] = 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_map : Optional[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]
              })
          }
      }



   .. py:method:: get_data(sites: Optional[Union[List, str]], locations: Optional[Union[List, str]], metrics: Union[List, str], start_timestamp: Union[str, datetime.datetime], end_timestamp: Union[str, datetime.datetime], location: Optional[Union[List, str]] = None, force_cache_miss: bool = False, method: str = 'GET') -> Optional[Union[pandas.DataFrame, Dict[str, Union[Dict[str, pandas.DataFrame], Dict[str, Any]]], List[Union[Any, str]]]]

      Get the data signals from the 24SEA API.

      Parameters
      ----------
      sites : Optional[Union[List, str]]
          The site name or List of site names. If None, the site will be
          inferred from the metrics.
      locations : Optional[Union[List, str]]
          The location name or List of location names. If None, the location
          will be inferred from the metrics.
      metrics : Union[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_timestamp : Union[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_timestamp : Union[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.