DOCSEARCHbyAlgolia
Submit Docs

AutoTS Documentation

repository·master·Indexed 23 days ago

https://github.com/winedarksea/autots

A high-performance Python package for automated time series forecasting (version 1.0.3). AutoTS uses genetic algorithms to automatically determine the best combination of models, transformations, and ensembles for univariate and multivariate datasets. It includes an MCP Server for LLM integration, a browser-based PWA using Pyodide/WASM, and support for both wide and long data formats.

Tokens
23.3K
Snippets
34
Records
91
Agent score
80%

What's inside AutoTS

  1. Overview of the autots.tools package submodules

    master

    The autots.tools package provides a collection of utility modules used for time series analysis, forecasting, and data preprocessing. These submodules cover a wide range of specialized tasks including anomaly detection, statistical modeling, signal processing, and data transformation.

    Key functional areas include:

    • Statistical & Regression Models: bayesian_regression, kalman, fast_kalman, fast_kalman_params, regressor, and cointegration.
    • Signal Processing: fft (Fast Fourier Transform), fir_filter, wavelet, and window_functions.
    • Data Preprocessing & Transformation: impute (for missing values), shaping, transform, thresholding, and percentile.
    • Time Series Features: seasonal, calendar, holiday, changepoints, and lunar.
    • Specialized Analysis: anomaly_utils, autoencoder, probabilistic, and hierarchial (hierarchical) analysis.
    • Utilities: cpu_count, mlflow (for experiment tracking), plotting, profile, and mocks (for testing).

  2. Explore the autots.models submodules

    master

    The autots.models package provides a wide variety of forecasting model implementations. Depending on your requirements (e.g., deep learning, statistical models, or ensembles), you can utilize specific submodules.

    Key model categories available include:

    • Deep Learning & Neural Networks: dnn, gluonts, neural_forecast, pytorch, and deepssm.
    • Statistical & Classical Models: statsmodels, prophet, and basics.
    • Ensemble & Composite Methods: ensemble, composite, mlensemble, and matrix_var.
    • Specialized Frameworks: sklearn (scikit-learn based), tide, and tva_model.
    • Data Integration: cassandra for specific data source handling.

    Use these submodules to select the appropriate model architecture for your time-series forecasting tasks.

  3. Understand the AutoTS PWA design and architecture

    master

    The AutoTS Progressive Web App (PWA) is designed as an elegant, browser-based tool for beginners to perform time series forecasting. It follows a modern design language based on Material Design 3.

    Architecture & Data Flow

    • Frontend: Rust-based (potentially using Leptos).
    • Backend: Python running via Pyodide.
    • Data Flow: Data moves between Rust (using polars) and Python (using pandas) via the Apache Arrow format.

    Key Features

    • Data Upload: Supports copy-pasting (TSV/CSV), file uploads (CSV/Excel), URL links (e.g., published Google Sheets), and loading sample or live daily data.
    • Interactive Visualization: Users can view uploaded data as interactive line graphs with feature detector labels. Forecast plots distinguish between actual values and forecasted values.
    • Forecast Adjustments: Users can manually adjust forecast data points via a drag-and-drop interface.
    • Data Export: Both loaded data and adjusted forecasts can be downloaded as wide-format CSV files.
    • Asynchronous Processing: Forecasting is designed to be asynchronous to prevent blocking the UI.

  4. Use the autots.datasets package for time series data

    master

    The autots.datasets package provides access to various time series datasets for testing and evaluating AutoTS models. It includes submodules for fetching real-world economic data from FRED (Federal Reserve Economic Data) and generating synthetic datasets for controlled experimentation.

    Available submodules:

    • autots.datasets.fred: Accesses economic datasets from the Federal Reserve.
    • autots.datasets.synthetic: Generates synthetic time series data.
    • autots.datasets: The main entry point for dataset operations.

  5. Handling categorical and custom frequency data

    master

    Categorical Data

    AutoTS handles categorical data, but optimization metrics do not currently include categorical accuracy. For categorical data with a meaningful order (e.g., 'low', 'medium', 'high'), it is recommended to manually encode the data (e.g., low=1, medium=2, high=3) before passing it to AutoTS to preserve the relative sequence.

    Custom Frequencies

    Data must be coercible to a regular frequency. It is recommended to specify the frequency as a pandas datetime offset (e.g., pd.offsets.Day()). Note that some models may only support a limited range of frequencies.

  6. Design Principles for AutoTS PWA

    master

    The AutoTS PWA follows a 'Classical meets Modern' aesthetic. To maintain this without falling into 'kitschy' skeuomorphism, follow these guidelines:

    • Typography: Pair an inscriptional display face (e.g., Cinzel) for wordmarks and hero elements with a clean, modern sans-serif (e.g., Inter or Outfit) for all functional UI, body text, and chart labels.
    • Avoid Skeuomorphism: Do not use literal marble textures, glossy gradients on buttons, or faux-chiseled bevels. Instead, express 'classical' through restrained type and color.
    • Elevation: Use Material 3's tonal elevation (surfaces tinted by overlays) rather than heavy drop shadows to create a 'carved from one block' feel.
    • Motion: Use 'Expressive' motion (larger corner radii, springier navigation) for high-level UI, but keep chart and data transitions quick and purposeful (~200–300ms) to maintain a sense of precision.

  7. How to use metric_weighting to guide model selection

    master

    The metric_weighting argument allows you to guide AutoTS toward models that meet specific business needs rather than just optimizing for a single mathematical error. This is useful when a standard metric like Mean Absolute Error (MAE) produces forecasts that don't fit your production constraints (e.g., producing a flat line when you need to capture movement).

    Key Principles

    • Relative Weighting: Weights are relative, not absolute. If all weights are set to 1, all metrics are weighted equally.
    • Order of Magnitude: For best results, use an order of magnitude difference between important and unimportant features (e.g., spl_weighting: 10 for high priority, smape_weighting: 1 for medium, and runtime_weighting: 0.1 for a tie-breaker).
    • Direction of Optimization:
      • For minimizing metrics (most metrics), a larger weighting favors smaller values.
      • For maximizing metrics, a larger weighting favors larger values.
    • Normalization: Behind the scenes, all metrics are normalized relative to each other and combined into a single Score used for model selection.

  8. Understand Regression-based forecasting models

    master

    AutoTS includes several regression models that reshape time series data into $X$ (features) and $Y$ (targets) for traditional Machine Learning or Deep Learning. All these models draw from a pool of sklearn and tensorflow models.

    • DatepartRegression: Uses date features as $X$ to predict values $Y$.
    • WindowRegression: Uses the $n$ preceding data points as $X$ to predict future values.
    • RollingRegression: Uses the entire time series and summarized rolling values as $X$. This scales poorly with a large number of series.
    • MultivariateRegression: Uses rolling features but considers them one at a time (features for series $i$ predict series $i$). This is often referred to as a "global forecasting ML model". It supports a GradientBoostingRegressor with quantile loss for probabilistic estimates.

  9. Configure Forecasting Color Semantics

    master

    When visualizing time-series data in the PWA, follow these color and style conventions to ensure accessibility and clarity:

    • Actuals vs. Forecast: Use Turquoise for actual values and Bronze/Gold for forecasted values. These hues are chosen to remain distinguishable for common colorblindness types.
    • Confidence Intervals: Use a translucent version of the primary color (e.g., turquoise at low alpha) to fill prediction bands. This indicates the band belongs to the same series but with less certainty.
    • Diverging Data (Over/Under Forecast): Use a Teal-to-Terracotta scale instead of the standard Red/Green to support colorblind users.
    • Redundancy: Never encode meaning by hue alone. Always pair color with a visual indicator, such as a dashed line pattern for forecasts vs. a solid line for actuals, or specific markers.

  11. How the AutoTS MCP ID-Based Workflow works

    master

    AutoTS MCP tools follow a cache-and-ID pattern. Most operations store their results in a server-side cache and return a unique ID. To perform downstream tasks, you must pass the ID returned by the previous tool into the next tool.

    Typical Workflow Example:

    1. load_sample_data $\rightarrow$ returns data_id
    2. forecast_fast(data_id) $\rightarrow$ returns prediction_id
    3. get_forecast(prediction_id) $\rightarrow$ retrieves results
    4. plot_forecast(prediction_id) $\rightarrow$ generates visualization
    5. apply_constraints(prediction_id) $\rightarrow$ returns a new_prediction_id

    Note: Use list_cache to rediscover IDs if you lose track of them during a conversation. The cache persists for the lifetime of the server process.

    load_sample_data → data_id
    ↓
forecast_fast(data_id) → prediction_id
    ↓
get_forecast(prediction_id)
plot_forecast(prediction_id)
apply_constraints(prediction_id) → new prediction_id

  12. Data formats for AutoTS: Wide vs Long

    master

    AutoTS accepts two primary input shapes for time series data:

    1. Wide Format: A pandas.DataFrame with a pandas.DatetimeIndex. Each column represents a distinct time series. No extra parameters are needed in .fit() for this format.
    2. Long Format: A pandas.DataFrame with three specific columns:
      • Date: Ideally in pandas-recognized datetime format.
      • Series ID: A unique identifier for each series (can be None for a single series).
      • Value: The observation value.

    When using Long Format, you must pass the column names to the .fit() method using date_col, id_col, and value_col.