Command-Line Interface (CLI)¶

Under Active Development

The Command-Line Interface is currently undergoing a significant reorganization to make it more powerful and intuitive. As a result, some of the commands documented on this page may be renamed, have their options changed, or be moved to different command groups in a future release.

We appreciate your patience as we work to improve these tools!

fusionlab-learn includes an extensible Command-Line Interface (CLI) for executing common workflows directly from your terminal. This allows you to run forecasting pipelines, data processing tasks, and launch applications without writing any Python code.

The main entry point for all tools is the fusionlab-learn command.

Getting Help¶

You can get a list of all available commands and their descriptions by running:

fusionlab-learn --help

To get help for a specific command group (e.g., forecast) or a sub-command, you can use:

# Help for a command group
fusionlab-learn forecast --help

# Help for a specific sub-command
fusionlab-learn forecast xtft-proba --help

Command Groups¶

The CLI is organized into several logical groups to make finding the right tool intuitive and easy.

Forecasting Tools (forecast)¶

This command group contains high-level tools for running end-to-end forecasting workflows. Each command encapsulates a full pipeline, from data loading and preprocessing to model training, prediction, and visualization.

This command trains and runs an XTFT model to generate probabilistic (quantile) forecasts. It provides a comprehensive set of options to control the entire workflow.

Usage:

fusionlab-learn forecast xtft-proba --data-path <PATH> --target <NAME> [OPTIONS]

Key Options:

--data-path (Required): The path to the directory containing your input CSV files.
--target (Required): The name of the target variable you wish to predict.
--cat-features, --num-features: Comma-separated lists of your categorical and numerical feature column names.
--epochs, --batch-size, --time-steps, --horizon: Standard parameters to control the training process and sequence generation.
--quantiles: A comma-separated list of quantiles for the probabilistic forecast (e.g., “0.1,0.5,0.9”).

This command is similar to xtft-proba but is specifically for generating deterministic (point) forecasts. It trains an XTFT model using a standard regression loss like Mean Squared Error.

Usage:

fusionlab-learn forecast xtft-point --data-path <PATH> [OPTIONS]

Key Options:

--data-path (Required): The path to the data directory.
--epochs, --batch-size, --time-steps, --horizon: Parameters to control the training and forecasting dimensions.

Data Processing Tools (process)¶

This group provides powerful utilities for inspecting and transforming your forecast data files. These tools are designed to help you automate common post-processing tasks, such as reshaping data for analysis or scripting workflows based on the data format.

Converts a long-format forecast DataFrame, where each row is a single time step for a specific entity, into a wide-format DataFrame, where each entity has a single row and the time steps are spread across the columns. This is essential for creating summary tables or preparing data for specific analysis tools that require a wide data structure.

Usage:

fusionlab-learn process pivot-forecast -i <INPUT> -o <OUTPUT> --id-vars <COLS> --time-col <COL> --prefixes <PREFIXES>

Key Options:

-i, --input-file (Required): The path to the input CSV file that is in a long format.
-o, --output-file (Required): The path where the new, wide-format CSV file will be saved.
--id-vars (Required): A comma-separated list of columns that uniquely identify each time series (e.g., “sample_idx,longitude”). These columns will be preserved as the index of the new wide table.
--time-col (Required): The name of the column that contains the temporal information (e.g., “year” or “forecast_step”).
--prefixes (Required): A comma-separated list of the base names of the value columns to be pivoted (e.g., “subsidence,GWL”).
--static-cols: An optional comma-separated list of columns that contain static “ground truth” values. These columns will be merged back into the final wide DataFrame without being pivoted.

This is a smart wrapper around the pivot-forecast command. It automatically detects if the input file is already in a wide format. If it is, the command does nothing. If it detects a long format, it will automatically run the pivot operation. This is useful for ensuring a dataset conforms to the wide format without causing errors if it’s already been processed.

Usage:

fusionlab-learn process format-forecast -i <INPUT_CSV> -o <OUTPUT_CSV> ...

A useful utility for scripting that inspects the columns of a CSV file and reports whether it contains a 'quantile' or a 'deterministic' forecast. This allows automated pipelines to make decisions based on the type of data they are processing.

Usage:

fusionlab-learn process detect-forecast-type -i <INPUT_CSV>

Geospatial Utilities (geotools)¶

This group contains tools specifically designed for preparing and augmenting geospatial time series data before it is used for training.

Creates a synthetic dataset with a structure suitable for the library’s PINN models. This is invaluable for quick tests, creating reproducible examples, or prototyping a workflow without needing a real dataset.

Usage:

fusionlab-learn geotools generate-dummy -o dummy_data.csv --n-samples 5000

Performs stratified spatial sampling on a large dataset. This is more intelligent than a simple random sample because it ensures that the smaller, output dataset is a representative microcosm of the original, preserving the spatial and categorical distribution of the data.

Usage:

fusionlab-learn geotools sample -i <INPUT> -o <OUTPUT> --sample-size 0.1 --stratify-by "year,category"

Applies advanced data augmentation techniques to a spatiotemporal dataset to increase the size and diversity of the training data, which can lead to more robust models. It can operate in two modes: interpolate (fills in missing time steps) and augment_features (adds random noise to feature columns), or both.

Usage:

fusionlab-learn geotools augment -i data.csv -o aug.csv --mode both --group-by "lon,lat" --time-col "date"

Key Options:

--interp-kwargs & --augment-kwargs: These options allow you to pass a JSON string to control the behavior of the underlying functions. For example: –interp-kwargs ‘{“freq”: “D”, “method”: “linear”}’

Hyperparameter Tuning (tune)¶

This command group contains tools for running automated hyperparameter tuning sessions for the various models in the library.

Launches the hyperparameter tuning workflow for the original, legacy PIHALNet model. This script is designed as a self-contained workflow with its own internal data loading and processing logic, making it a quick way to run a predefined tuning experiment.

Usage:

fusionlab-learn tune legacy-pihalnet

PINN Workflow Tools¶

This set of tools provides a complete pipeline for training a Physics-Informed Neural Network from scratch and then using the trained model to run inference on new data.

This command orchestrates the full end-to-end training workflow. It takes a single raw data file, runs the entire data processing, sequence generation, model training, and forecasting pipeline, and saves all resulting artifacts (the trained model, scalers, plots, and a forecast CSV) to a unique output directory.

Usage:

fusionlab-learn forecast train-pinn --data-file <PATH_TO_CSV> [OPTIONS]

Key Options:

--data-file (Required): The path to your input CSV data.
--model-name: Choose between TransFlowSubsNet and PIHALNet.
--output-dir: The root directory where a new, timestamped run folder will be created.
--epochs, --lr, --batch-size, --patience: Standard training hyperparameters.
--train-end-year, --horizon, --time-steps: Parameters to control the temporal split and sequence length.
--pde-mode, --lambda-cons, --lambda-gw: Fine-grained control over the physics-informed components of the model.

This command runs inference only. It is designed to be used after a model has been trained. It takes a pre-trained model and its associated artifacts (like scalers and encoders) and applies them to a new, unseen data file to generate a new forecast.

Usage:

fusionlab.tools forecast infer-pinn --data-file <NEW_DATA.csv> --model-path <MODEL.keras> --artifacts-dir <PATH>

Key Options:

--data-file (Required): Path to the new CSV file you want to run predictions on.
--model-path (Required): Direct path to the trained .keras model file saved from the train-pinn command.
--artifacts-dir (Required): Path to the directory containing the other saved training artifacts (e.g., ohe_encoder.joblib, main_scaler.joblib).
--output-dir: A new directory where the inference results (forecast CSV and plots) will be saved.

Mini-GUI Applications (app)¶

This group contains commands for launching graphical user interfaces, providing a user-friendly way to interact with the library’s workflows without writing code.

Launches the Subsidence PINN Mini GUI. This desktop application provides a complete, interactive interface for loading data, configuring all model and training parameters, running an end-to-end forecasting pipeline, and visualizing the results.

Usage:

fusionlab-learn app launch-mini-forecaster