forecastingapi.forecastingapi

  1import os
  2from dotenv import load_dotenv
  3import getpass
  4import requests
  5from .config import BASE_URL
  6
  7
  8def get_token(token=None):
  9    """
 10    Retrieve the API token, either from the environment or user input.
 11
 12    Parameters:
 13    -----------
 14    token : str
 15        Token provided as a parameter (default is None).
 16
 17    Returns:
 18    --------
 19    str
 20        A valid API token.
 21    """
 22    if token:
 23        return token
 24
 25    # Load environment variables from .env if available
 26    load_dotenv()
 27    token = os.getenv("TECHTONIQUE_TOKEN")
 28
 29    if not token:
 30        # Prompt user for token if not found in environment
 31        token = getpass.getpass(
 32            "Enter your token (from https://www.techtonique.net/token): ")
 33
 34    if not token:
 35        raise ValueError("API token is required but was not provided.")
 36
 37    return token
 38
 39
 40def get_forecast(
 41    path_to_file,
 42    base_model="RidgeCV",
 43    n_hidden_features=5,
 44    lags=25,
 45    type_pi="gaussian",
 46    replications=None,
 47    h=10,
 48    token=None,
 49):
 50    """
 51    Get a forecast from the Techtonique API.
 52
 53    Parameters:
 54    -----------
 55
 56    path_to_file : str
 57        Path to the input file or URL containing the time series data.
 58
 59    base_model : str
 60        Forecasting method to use (default is "RidgeCV"); for now scikit-learn model names. 
 61
 62    n_hidden_features : int
 63        Number of hidden features for the model (default is 5).
 64
 65    lags : int
 66        Number of lags to use in the model (default is 25).
 67
 68    type_pi : str
 69        Type of prediction interval to use (default is 'gaussian').
 70
 71    replications : int
 72        Number of replications for certain methods (default is None).
 73
 74    h : int
 75        Forecast horizon (default is 10).
 76
 77    token : str
 78        API token for authentication (default is None). If not provided, and if not in the environment, the user will be prompted to enter it.
 79
 80    Returns:
 81    --------
 82    dict
 83        A dictionary containing the forecast results (mean, lower bound, upper bound, and simulations).
 84
 85    Example:
 86    --------   
 87    >>> from forecastingapi import get_forecast
 88    >>> # path to your local timeseries data (examples in https://github.com/Techtonique/datasets/tree/main/time_series)
 89    >>> file_path = "path/to/your/timeseries/data.csv"
 90    >>> forecast = get_forecast(file_path, h=15)
 91    >>> print(forecast)
 92    """
 93
 94    token = get_token(token)
 95
 96    headers = {
 97        'Authorization': 'Bearer ' + token,
 98    }
 99
100    params = {
101        'base_model': str(base_model),
102        'n_hidden_features': str(n_hidden_features),
103        'lags': str(lags),
104        'type_pi': str(type_pi),
105        'replications': str(replications),
106        'h': str(h),
107    }
108
109    files = {
110        'file': (path_to_file, read_file_or_url(path_to_file), 'text/csv'),
111    }
112
113    response = requests.post(BASE_URL + '/forecasting',
114                             params=params, headers=headers, files=files)
115
116    return response.json()
117
118
119def read_file_or_url(path):
120    if path.startswith("http://") or path.startswith("https://"):
121        response = requests.get(path)
122        return response.content
123    else:
124        return open(path, "rb")