.. _quick-start-01:
.. raw:: html
User manual
=================
**api-24sea-ai** is an extension package for `API-24SEA `_
that provides tools to interact with the AI models hosted on the 24SEA platform.
.. note::
The following example shows the classical usage of the datasignals module.
The first step is package installation, and after that the example code cells show how to:
* Import the package and other useful libraries.
* Load the environment variables from a `.env` file.
This step is optional, since if any of the following names for
user and password in the system, the package will authenticate
automatically.
* ``API_24SEA_USERNAME``, ``24SEA_API_USERNAME``, ``TWOFOURSEA_API_USERNAME``, ``API_TWOFOURSEA_USERNAME`` for the username.
* ``API_24SEA_PASSWORD``, ``24SEA_API_PASSWORD``, ``TWOFOURSEA_API_PASSWORD``, ``API_TWOFOURSEA_PASSWORD`` for the password.
* After that, API can be instantiated and authenticated.
* Finally, the user can get predictions from the API. The AsyncAPI class will
authenticate lazily if the environment variables are loaded, or the user
can authenticate manually before performing the data retrieval.
Installation
------------
The package supports Python ``[3.8:3.14)``. To install it, run the following command in your terminal:
.. code-block:: bash
pip install api-24sea-ai
or, being an extension package of ``api-24sea``, you can install it as:
.. tab-set-code::
.. code-block:: powershell
pip install api-24sea[ai]
.. code-block:: bash
pip install 'api-24sea[ai]'
Importing the package
---------------------
.. code-block:: python
# %%
# **Package Imports**
# - From the Python Standard Library
import logging
import os
import sys
# - From third party libraries
import pandas as pd
import dotenv # <-- Not necessary to api-24sea-ai per se, but useful for
# loading environment variables. Install it with
# `pip install python-dotenv`
# - Local imports
from api_24sea.ai.version import __version__, parse_version
.. code-block:: python
# %%
# **Package Versions**
print("Working Folder: ", os.getcwd())
print(f"Python Version: {sys.version}")
print(f"Pandas Version: {pd.__version__}")
print(f"Package {parse_version(__version__)}")
# **Notebook Configuration**
logging.basicConfig(level=logging.INFO)
Setting up the environment variables (optional)
------------------------------------------------
This step assumes that you have a file structure similar to the following one:
.. code-block:: shell
.
├── env
│ └── .env
├── notebooks
│ └── example.ipynb
└── requirements.txt
The `.env` file should look like this:
.. code-block:: shell
API_24SEA_USERNAME=your_username
API_24SEA_PASSWORD=your_password
With this in mind, the following code snippet shows how to load the environment
variables from the `.env` file:
.. code-block:: python
# %%
# **Load Environment Variables from .env File**
_ = dotenv.load_dotenv("../env/.env")
if _:
print("Environment Variables Loaded Successfully")
print(os.getenv("API_24SEA_USERNAME"))
# print(os.getenv("API_24SEA_PASSWORD"))
else:
raise Exception("Environment Variables Not Loaded")
Performing AI model predictions
-------------------------------
After loading the environment variables and authenticating with the API,
the user can perform AI predictions from
`24SEA API AI endpoints `_.
The predictions are returned as a DataFrame. All the metrics predicted from
the requested models are stored in separate columns, and the timestamps are
set as the index of the DataFrame.
The prediction is done by specifying the sites or the locations or both, the
metrics, and timestamps.
* Sites: Case insensitive, it can either match `site` or `site_id`. It is an
optional parameter.
* Locations: Case insensitive, it can either match `location` or `location_id`.
It is an optional parameter.
* Models: Case insensitive, it can be a partial match of the model name. It is a
required parameter.
* Timestamps: Timezone-aware datetime, strings in ISO 8601 format, or shorthand
strings compatible with the `shorthand_datetime package `_.
.. code-block:: python
# %%
# **Authenticating AI Client and Viewing Models Overview**
from api_24sea.ai.core import AsyncAPI
api = AsyncAPI()
api.models_overview # <-- View the models overview (performs lazy authentication)
.. code-block:: python
# %%
# **Making Predictions**
api.get_predictions(
sites="WF",
locations="A01",
model="mean_WF_A01_some_ai_model",
start_timestamp="2020-03-01",
end_timestamp="2020-06-01",
).head()