pyForTraCC - Python library for Forecasting and Tracking the Evolution of Configurable Clusters

Overview

pyForTraCC is a Python library developed for identifying, tracking, and forecasting clusters in diverse datasets. Its modular structure enables flexible integration, supporting user-defined configurations and compatibility with multiple input formats.

Algorithm Workflow

The algorithm is divided into two main modules: Track and Forecast.

1. Track: This module identifies and tracks clusters in a time-sequenced field. It follows four steps:

   • Feature Extraction: Identifies relevant features using multi-thresholding on a time-varying field, clusters contiguous pixels above thresholds, and vectorizes clusters as geospatial objects.
   • Spatial Operations: Establishes spatial relationships between features and computes vector displacements between feature centroids.
   • Cluster Linkage: Links features across time steps by indexing current features with those from the previous time step, generating unique cluster identifiers, tracking trajectories, and recording the cluster lifetime.
   • Concatenation: Combines all identified features and trajectories into a single Parquet file, forming a consolidated tracking table with complete tracking data.

2. Forecast: This module will predict future cluster positions through:

   • Virtual Image: A persistence-based forecast of cluster positions by shifting clusters in the current time step to a specified future position based on average vector displacement.
   • Track Routine: Applies the tracking routine to the virtual image, projecting cluster identification to the anticipated time step.

Documentation

For detailed instructions and usage, refer to the pyForTraCC Documentation.

Installation

The pyForTraCC package can be installed in two ways: Directly by via the pip package manager or cloning the official GitHub repository.

Installing with Pip (Directly)

To install or update pyForTraCC directly from the Python Package Index (PyPI), use:

pip install -U pyfortracc

Installing from GitHub

Download the package directly from the official GitHub repository by cloning it:

git clone https://github.com/fortracc/pyfortracc/

After downloading, you can install the package directly. It is recommended to use Python 3.12 and a virtual environment (such as Anaconda3, Miniconda, or Mamba) to avoid dependency conflicts.

• Installing with Conda If you are using Conda, you can install the package dependencies as follows:

  cd pyfortracc
  conda env create -f environment.yml
  conda activate pyfortracc

• Installing with pip Alternatively, you can install the package with pip:

  cd pyfortracc
  python3 -m venv venv
  source venv/bin/activate  # On Linux/macOS
  .venv\bin\activate  # On Windows
  pip install .

Running pyFortracc

To use pyForTraCC, install and import the library, then create a custom data-reading function, read_function, tailored to your data’s format. This function should return a two-dimensional matrix as required by the library. Define a dictionary, name_list, with necessary configuration parameters for tracking, including data paths, thresholds, and time intervals. Finally, run the tracking function.

Here is an example script:

import pyfortracc
import xarray as xr

# Custom data reading function
def read_function(path):
    """
    This function reads data from the given path and returns a two-dimensional matrix.
    """
    data = xr.open_dataarray(path).data
    return data

# Parameter dictionary for tracking configuration
name_list = {
    'input_path': 'input/',  # Path to input data
    'output_path': 'output/',  # Path to output data
    'thresholds': [20, 30, 45],  # Intensity thresholds
    'min_cluster_size': [10, 5, 3],  # Minimum cluster size (in number of points)
    'operator': '>=',  # Comparison operator (>=, <=, or ==)
    'timestamp_pattern': '%Y%m%d_%H%M%S.nc',  # Timestamp file naming pattern
    'delta_time': 12  # Time interval between frames, in minutes
}

# Execute tracking with parameters and custom reading function
pyfortracc.track(name_list, read_function)

WORCAP Minicourse (Portuguese)

Educational tutorial series developed for the WORCAP 2025 (Workshop on Applied Computing at INPE 2025), providing step-by-step introduction to pyForTraCC concepts and applications in Portuguese:

	Minicurso
	1 - Exemplo Introdutório (Basic Tracking)
	2 - Rastreamento em Tempo Real (Real-Time Tracking)
	3 - Rastreamento de Mudanças Antropogênicas (Anthropogenic Change Tracking)

Example Gallery

=====================================================================

Library have a gallery of examples that demonstrate the application of the algorithm in different situations.
You can run the examples in Google Colab:

	Example
	01 - Introducing Example
	02 - Radar Data Example
	03 - Infrared Satellite Example (Realtime Track)
	04 - Global Precipitation Example

Citation

=====================================================================

If you use pyForTraCC in your research, please cite the following reference:

LEAL, Helvecio B. et al. Impact of Multi-Thresholds and Vector Correction for Tracking Precipitating Systems over the Amazon Basin. Remote Sensing, v. 14, n. 21, p. 5408, 2022.

BibTeX

@article{leal2022impact,
  title={Impact of Multi-Thresholds and Vector Correction for Tracking Precipitating Systems over the Amazon Basin},
  author={Leal, Helvecio B and Calheiros, Alan JP and Barbosa, Henrique MJ and Almeida, Adriano P and Sanchez, Arturo and Vila, Daniel A and Garcia, S{\^a}mia R and Macau, Elbert EN},
  journal={Remote Sensing},
  volume={14},
  number={21},
  pages={5408},
  year={2022},
  publisher={MDPI}
}

Related Works

=====================================================================

The following publications demonstrate various applications and developments of pyForTraCC:

• Calheiros, A., Neto, H. L., Kubota, T., Vila, D., Garcia, S., Ushio, T., & Hirose, H. (2025). Tracking a Decade of GSMaP-Derived Precipitating Systems with pyForTraCC (No. EMS2025-292). Copernicus Meetings.
  📄 View Paper

  • Neto, H. B. L., e Milton, A. J. P. C., & da Silva, B. (2025) TRACKING PRECIPITATION SYSTEMS OVER BRAZIL: ANALYSIS OF DENSITY, INTENSITY, DURATION AND SIZE OVER TWO DECADES. In: ANAIS DO XXI SIMPÓSIO BRASILEIRO DE SENSORIAMENTO REMOTO, Salvador. Anais eletrônicos..., Galoá.
    📄 View Paper

• SILVA, Milton Borges da et al. (2025). AVALIAÇÃO DAS ESTIMATIVAS DE CHUVA DA MISSÃO GPM SOBRE MATO GROSSO DO SUL. In: ANAIS DO XXI SIMPÓSIO BRASILEIRO DE SENSORIAMENTO REMOTO, Salvador. Anais eletrônicos..., Galoá.
  📄 View Paper

• Helvecio, B. L. N., & James, P. C. A. (2022). Application of the DBSCAN algorithm for identifying morphological features of atmospheric systems over the amazon basin. Authorea Preprints.
  📄 View Paper

  • LEAL NETO, H. B. (2021). Rastreio e previsão de sistemas precipitantes e convectivos na Bacia Amazônica utilizando aprendizado de máquina não-supervisionado. Dissertação (Mestrado em Computação Aplicada) - Instituto Nacional de Pesquisas Espaciais (INPE), São José dos Campos. 142 p.
    📄 View Thesis

• Neto, H. B. L., Almeida, A. P., & Calheiros, A. J. (2020). As dificuldades no rastreio de tempestades com uso de refletividade radar a partir de técnicas de geoprocessamento: Um estudo de caso sobre a região Amazônica. In GEOINFO (pp. 240-245).
  📄 View Paper

Support and Contact

• [email protected]