{"id":43439304,"url":"https://github.com/fortracc/pyfortracc","last_synced_at":"2026-02-02T21:53:26.202Z","repository":{"id":260625444,"uuid":"879739879","full_name":"fortracc/pyfortracc","owner":"fortracc","description":"pyFortraCC is a Python library for tracking and forecasting clusters.","archived":false,"fork":false,"pushed_at":"2025-10-25T21:22:23.000Z","size":48811,"stargazers_count":37,"open_issues_count":7,"forks_count":9,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-10-25T22:10:29.322Z","etag":null,"topics":["forecasting","nowcasting","nowcasting-precipitation","tracking","tracking-algorithm","weather-forecast"],"latest_commit_sha":null,"homepage":"https://pyfortracc.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fortracc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-10-28T13:19:28.000Z","updated_at":"2025-10-25T21:22:27.000Z","dependencies_parsed_at":null,"dependency_job_id":"28711a33-6765-46de-a870-d7677bf11ab0","html_url":"https://github.com/fortracc/pyfortracc","commit_stats":null,"previous_names":["fortracc/pyfortracc"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/fortracc/pyfortracc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fortracc%2Fpyfortracc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fortracc%2Fpyfortracc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fortracc%2Fpyfortracc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fortracc%2Fpyfortracc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fortracc","download_url":"https://codeload.github.com/fortracc/pyfortracc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fortracc%2Fpyfortracc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29021031,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-02T18:51:31.335Z","status":"ssl_error","status_checked_at":"2026-02-02T18:49:20.777Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["forecasting","nowcasting","nowcasting-precipitation","tracking","tracking-algorithm","weather-forecast"],"created_at":"2026-02-02T21:53:25.610Z","updated_at":"2026-02-02T21:53:26.195Z","avatar_url":"https://github.com/fortracc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pyForTraCC - Python library for Forecasting and Tracking the Evolution of Configurable Clusters\n\n\u003c!-- badges: start --\u003e\n[![stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://pyfortracc.readthedocs.io)\n[![pypi](https://badge.fury.io/py/pyfortracc.svg)](https://pypi.python.org/pypi/pyfortracc)\n[![Documentation](https://readthedocs.org/projects/pyfortracc/badge/?version=latest)](https://pyfortracc.readthedocs.io/)\n[![Downloads](https://img.shields.io/pypi/dm/pyfortracc.svg)](https://pypi.python.org/pypi/pyfortracc)\n[![Contributors](https://img.shields.io/github/contributors/fortracc/pyfortracc.svg)](https://github.com/fortracc/pyfortracc/graphs/contributors)\n[![License](https://img.shields.io/pypi/l/pyfortracc.svg)](https://github.com/fortracc/pyfortracc/blob/main/LICENSE)\n\u003c!-- badges: end --\u003e\n\n## Overview\n\n`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.\n\n### Algorithm Workflow\n\nThe algorithm is divided into two main modules: **Track** and **Forecast**.\n\n1. **Track**: This module identifies and tracks clusters in a time-sequenced field. It follows four steps:\n   - **Feature Extraction**: Identifies relevant features using multi-thresholding on a time-varying field, clusters contiguous pixels above thresholds, and vectorizes clusters as geospatial objects.\n   - **Spatial Operations**: Establishes spatial relationships between features and computes vector displacements between feature centroids.\n   - **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.\n   - **Concatenation**: Combines all identified features and trajectories into a single Parquet file, forming a consolidated tracking table with complete tracking data.\n\n2. **Forecast**: This module will predict future cluster positions through:\n   - **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.\n   - **Track Routine**: Applies the tracking routine to the virtual image, projecting cluster identification to the anticipated time step.\n\n## Documentation\n\nFor detailed instructions and usage, refer to the [pyForTraCC Documentation](https://pyfortracc.readthedocs.io/).\n\n## Installation\nThe pyForTraCC package can be installed in two ways: Directly by via the `pip` package manager or cloning the official GitHub repository.\n\n#### Installing with Pip (Directly)\nTo install or update pyForTraCC directly from the Python Package Index (PyPI), use:\n\n```bash\npip install -U pyfortracc\n```\n\n#### Installing from GitHub  \nDownload the package directly from the official GitHub repository by cloning it:\n\n```bash\ngit clone https://github.com/fortracc/pyfortracc/\n```\nAfter 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.\n\n- **Installing with Conda** If you are using Conda, you can install the package dependencies as follows:\n   \n   ```bash\n   cd pyfortracc\n   conda env create -f environment.yml\n   conda activate pyfortracc\n   ```\n\n- **Installing with pip** Alternatively, you can install the package with `pip`:\n   \n   ```bash\n   cd pyfortracc\n   python3 -m venv venv\n   source venv/bin/activate  # On Linux/macOS\n   .venv\\bin\\activate  # On Windows\n   pip install .\n   ```\n\nRunning pyFortracc\n=====================================================================\nTo 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.\n\nHere is an example script:\n\n```python\nimport pyfortracc\nimport xarray as xr\n\n# Custom data reading function\ndef read_function(path):\n    \"\"\"\n    This function reads data from the given path and returns a two-dimensional matrix.\n    \"\"\"\n    data = xr.open_dataarray(path).data\n    return data\n\n# Parameter dictionary for tracking configuration\nname_list = {\n    'input_path': 'input/',  # Path to input data\n    'output_path': 'output/',  # Path to output data\n    'thresholds': [20, 30, 45],  # Intensity thresholds\n    'min_cluster_size': [10, 5, 3],  # Minimum cluster size (in number of points)\n    'operator': '\u003e=',  # Comparison operator (\u003e=, \u003c=, or ==)\n    'timestamp_pattern': '%Y%m%d_%H%M%S.nc',  # Timestamp file naming pattern\n    'delta_time': 12  # Time interval between frames, in minutes\n}\n\n# Execute tracking with parameters and custom reading function\npyfortracc.track(name_list, read_function)\n```\n\n### WORCAP Minicourse (Portuguese)\n\nEducational tutorial series developed for the [WORCAP 2025](https://www.gov.br/inpe/pt-br/eventos/worcap-2025) (Workshop on Applied Computing at INPE 2025), providing step-by-step introduction to pyForTraCC concepts and applications in Portuguese:\n\n|                                                                                    | Minicurso                              |\n|-------------------------------------------------------------------------------------------|----------------------------------------|\n| [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/fortracc/pyfortracc/blob/main/examples/WORCAP-Minicourse/1_Basic_Tracking/1_Basic_Tracking.ipynb) | 1 - Exemplo Introdutório (Basic Tracking) |\n| [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/fortracc/pyfortracc/blob/main/examples/WORCAP-Minicourse/2_RealTime_Tracking/2_RealTime_Tracking.ipynb) | 2 - Rastreamento em Tempo Real (Real-Time Tracking) |\n| [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/fortracc/pyfortracc/blob/main/examples/WORCAP-Minicourse/3_Antropogenic_Tracking/3_Antropogenic_Tracking.ipynb) | 3 - Rastreamento de Mudanças Antropogênicas (Anthropogenic Change Tracking) |\n\n\n### Example Gallery\n=====================================================================\n\nLibrary have a gallery of examples that demonstrate the application of the algorithm in different situations.\u003cbr\u003e\nYou can run the examples in Google Colab:\n\n|                                                                                    | Example                              |\n|-------------------------------------------------------------------------------------------|----------------------------------------|\n| [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/fortracc/pyfortracc/blob/main/examples/01_Introducing_Example/01_Introducing-pyFortraCC.ipynb) | 01 - Introducing Example              |\n| [![Open in Cola](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/fortracc/pyfortracc/blob/main/examples/02_Track-Radar-Data/02_Track-Radar-Dataset.ipynb) | 02 - Radar Data Example               |\n| [![Open in Cola](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/fortracc/pyfortracc/blob/main/examples/03_Track-Infrared-Dataset/03_Track-Infrared-Dataset.ipynb) | 03 - Infrared Satellite Example (Realtime Track) |\n| [![Open in Cola](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/fortracc/pyfortracc/blob/main/examples/04_Track-Global-Precipitation-EDA/04_Track-Global-Precipitation.ipynb) | 04 - Global Precipitation Example     |\n\n\n\n### Citation\n=====================================================================\n\nIf you use pyForTraCC in your research, please cite the following reference:\n\n**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.**\n\n#### BibTeX\n```bibtex\n@article{leal2022impact,\n  title={Impact of Multi-Thresholds and Vector Correction for Tracking Precipitating Systems over the Amazon Basin},\n  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},\n  journal={Remote Sensing},\n  volume={14},\n  number={21},\n  pages={5408},\n  year={2022},\n  publisher={MDPI}\n}\n```\n\n#### Related Works\n=====================================================================\n\nThe following publications demonstrate various applications and developments of pyForTraCC:\n\n- **LEAL NETO, H. B., e Milton, A. J. P. C., \u0026 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á.  \n  [📄 View Paper](http://marte2.sid.inpe.br/attachment.cgi/sid.inpe.br/marte2/2025/08.16.16.54.21/doc/@individualPDF.pdf)\n\n- **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á.  \n  [📄 View Paper](https://proceedings.science/sbsr-2025/trabalhos/avaliacao-das-estimativas-de-chuva-da-missao-gpm-sobre-mato-grosso-do-sul?lang=pt-br)\n\n- **LEAL NETO, H. B., \u0026 James, P. C. A. (2022)**. Application of the DBSCAN algorithm for identifying morphological features of atmospheric systems over the amazon basin. Authorea Preprints.  \n  [📄 View Paper](https://essopenarchive.org/doi/full/10.1002/essoar.10512488.1)\n\n- **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.  \n  [📄 View Thesis](http://urlib.net/ibi/8JMKD3MGP3W34R/44HGF8E)\n\n- **LEAL NETO, H. B., Almeida, A. P., \u0026 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).  \n  [📄 View Paper](http://mtc-m16c.sid.inpe.br/col/sid.inpe.br/mtc-m16c/2020/12.15.12.54/doc/s14.pdf)\n\n\nSupport and Contact\n=====================================================================\n- fortracc.project@inpe.br\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffortracc%2Fpyfortracc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffortracc%2Fpyfortracc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffortracc%2Fpyfortracc/lists"}