wildfire-analyser 0.3.0

Python library for post-fire assessment and wildfire analysis using Google Earth Engine.

Project Architecture (Overview)

The wildfire-analyser project is organized into three conceptual layers:

• Core library (fire_assessment)
  Implements scientific computation, dependency resolution, and Earth Engine logic.

• Execution layer (DAG)
  Automatically resolves and executes dependencies required for each deliverable.

• Command-line interfaces (CLI)
  User-facing tools for running analyses and monitoring Earth Engine tasks.

Outputs

All generated outputs (GeoTIFFs, thumbnails, statistics) are considered runtime artifacts and are not committed to version control.

Scientific Background

This project is based on the peer-reviewed study:

Spatial and statistical analysis of burned areas with Landsat-8/9 and Sentinel-2 satellites: 2023 Çanakkale forest fires Authors: Deniz Bitek, Fusun Balik Sanli, Ramazan Cuneyt Erenoglu Study area: Çanakkale Province, Turkey

The methodology implemented in wildfire-analyser follows the same analytical framework and burn severity thresholds described in the paper, particularly for the Sentinel-2–based analysis, including:

• dNBR, dNDVI and RBR indices
• Burn severity classification tables
• Area statistics in hectares and percentage

Minor numerical differences may occur due to cloud masking, spatial sampling, and Google Earth Engine implementation details.

---

Installation and Usage

Follow the steps below to install and test wildfire-analyser inside an isolated environment:

mkdir test
cd test

python3 -m venv venv
source venv/bin/activate

pip install wildfire-analyser

---

Required Files Before Running the Client

Before running the client, you must prepare the following items:

---

1. Add a GeoJSON polygon (ROI)

Create a folder named polygons in the project root and place your ROI polygon file inside it:

/tmp/test/
├── polygons/
│   └── your_polygon.geojson
└── venv/

Example GeoJSON files are available in the repository (e.g. canakkale_aoi_1.geojson).

---

2. Create the .env file with GEE credentials

In the project root, add a .env file containing your Google Earth Engine authentication variables.

A .env.template file is available in the repository.

/tmp/test/
├── .env
├── polygons/
└── venv/

---

Running the Client (Standard Mode)

After adding the .env file and your GeoJSON polygon. Please update your GEE service account key and the bucket name in the .env file.

python3 -m wildfire_analyser.cli \
  --roi polygons/canakkale_aoi_1.geojson \
  --start-date 2023-07-01 \
  --end-date 2023-07-21 \
  --deliverables \
    DNBR_VISUAL \
    DNDVI_VISUAL \
    RBR_VISUAL \
    DNBR_AREA_STATISTICS \
    DNDVI_AREA_STATISTICS \
    RBR_AREA_STATISTICS \
  --days-before-after 0

or:

python3 -m wildfire_analyser.cli \
  --roi polygons/eejatai.geojson \
  --start-date 2024-09-26 \
  --end-date 2024-10-05 \
  --deliverables \
    RGB_PRE_FIRE_VISUAL \
    RGB_POST_FIRE_VISUAL \
    DNBR_VISUAL \
    DNBR_AREA_STATISTICS

This will:

• Run the post-fire assessment pipeline
• Generate visual thumbnail URLs
• Generate scientific GeoTIFF outputs (when applicable)
• Compute burned area statistics
• Print all results to the terminal

---

Deliverables

You may explicitly select deliverables using --deliverables.

Scientific products

• RGB_PRE_FIRE
• RGB_POST_FIRE
• NDVI_PRE_FIRE
• NDVI_POST_FIRE
• NBR_PRE_FIRE
• NBR_POST_FIRE
• DNDVI
• DNBR
• RBR

Visual products

• RGB_PRE_FIRE_VISUAL
• RGB_POST_FIRE_VISUAL
• DNDVI_VISUAL
• DNBR_VISUAL
• RBR_VISUAL

Severity maps and statistics

• DNBR_AREA_STATISTICS
• DNDVI_AREA_STATISTICS
• RBR_AREA_STATISTICS

Example:

python3 -m wildfire_analyser.cli \
   --roi polygons/canakkale_aoi_1.geojson \
   --start-date 2023-07-01 \
   --end-date 2023-07-21 \
   --deliverables DNBR_VISUAL DNBR_AREA_STATISTICS

If --deliverables is not provided, all available deliverables are generated.

---

Paper Preset Mode (Reproducibility)

The client also supports paper presets, which are predefined experimental configurations designed to reproduce published results.

Example preset: PAPER_DENIZ_FUSUN_RAMAZAN

Run:

python3 -m wildfire_analyser.cli \
  --deliverables PAPER_DENIZ_FUSUN_RAMAZAN

This preset:

• Executes the analysis for two distinct burned areas
• Uses paper-aligned temporal windows
• Generates only visual outputs and statistics
• Does not export scientific GeoTIFFs
• Prints results grouped by area

Internally, it runs:

Area	ROI	Pre-fire	Post-fire
Area 1	canakkale_aoi_1.geojson	2023-07-01	2023-07-21
Area 2	canakkale_aoi_2.geojson	2023-07-31	2023-08-30

---

Help

For help and full usage information:

python3 -m wildfire_analyser.cli --help

Additional Documentation

The following documents provide more detailed and advanced guidance for development, environment setup, and asynchronous processing workflows. They are not required if the environment is already configured, but are recommended for first-time setup, developers, and production deployments.

• Development Guide Internal architecture, project conventions, and contribution guidelines. docs/development.md

• Environment & Credentials Setup Step-by-step instructions for configuring Google Earth Engine, service accounts, environment variables, and Cloud Storage. docs/environment-setup.md

• 🔧 Asynchronous GEE Task Monitoring Detailed explanation of asynchronous scientific exports, gee_task_id handling, and task monitoring using the standalone CLI tool. docs/gee_task_monitoring.md

---

When to read these documents

• Read environment-setup.md before running the pipeline in a new system.
• Read gee_task_monitoring.md when integrating with frontend/backend architectures or background workers.
• Read development.md if you plan to modify or extend the codebase.

---