Update README.md

README.md

@@ -1,36 +1,67 @@
 ---
 base_model:
-- ibm-esa-geospatial/TerraMind-1.0-base
+  - ibm-esa-geospatial/TerraMind-1.0-base
 pipeline_tag: image-classification
 tags:
-- methane,
-- detection,
-- geospatial,
+  - methane
+  - detection
+  - geospatial
+  - terramind
 ---
+
 # FAST-EO Use Case 2 - Methane Detection
 
-This directory contains all data and code necessary to recreate experiments conducted for fine-tuning Terramind-Base to detect methane in satellite images. It includes five distinct experiments along with their corresponding datasets. The attached Methane_benchmark_patches_summary_v3.xlsx file provides descriptions for every patch extracted from the Methane Benchmark Dataset (MBD) and defines the fold splits to ensure non-overlapping data. This Excel file is used by the runner scripts to partition the data, typically reserving one fold for testing.
+This repository contains data and code to reproduce experiments for fine-tuning **TerraMind-Base** to detect methane-related signatures in multispectral imagery. It includes multiple experiment variants and their corresponding datasets.
+
+The file `Methane_benchmark_patches_summary_v3.xlsx` provides per-patch descriptions and defines the **fold splits** used to ensure non-overlapping partitions. Runner scripts use this Excel file to build train/val/test splits, typically reserving one fold for testing.
+
+All scripts provide usage instructions via `--help` (or `-h`).
+
+## Requirements
+
+- Install the TerraMind/Terratorch stack used by the project before running experiments.
+- Ensure your environment has the required dependencies for data loading and training.
+
+## Experiments
+
+### Experiment 1: Fine-tuning on Methane Benchmark Dataset (MBD)
+
+Fine-tune TerraMind-Base on the Methane Benchmark Dataset. The normalized dataset is provided in:
+
+- `MBD_nan_S2_zscore/`
+
+Training code is located in:
+
+- `classification/` (includes dataset and dataloader classes)
+
+### Experiment 2: Fine-tuning on MBD with text captions
 
-Each script includes usage instructions which can be accessed by applying the --help (or -h) flag.
+This experiment modifies the TerraMind-Base model to concatenate text-caption embeddings with visual embeddings.
 
-## Important: Ensure the Terramind package is installed before running any experiments.
+- Caption embeddings are computed with `all-MiniLM-L6-v2`.
+- Code and resources are in `classification_with_text/`.
+- Original captions: `classification_with_text/MBD_text/`
+- Precomputed embeddings: `combined_caption_embeddings.csv`
 
-## Experiment 1: Fine tuning on Methane Benchmark Dataset
+### Experiment 3: Sentinel-2 with simulated atmospheric conditions
 
-The first experiment is fine tuning the model on Methane Benchmark Dataset. The dataset has been attatched in the directory `MBD_nan_S2_zscore`, and has been already normalized. The code for running the training is located in the `classification` directory, along with neccessary `dataset` and `dataloader` classes. 
+Evaluate generalization on Sentinel-2 data with simulated atmospheric conditions in both:
+- Top-of-Atmosphere (TOA)
+- Bottom-of-Atmosphere (BOA)
 
-## Experiment 2: Fine tuning on MBD with text captions
+The model can be trained on this simulated data or used only for inference to test cross-domain robustness.
 
-This experiment contains a modified verion of the Terramind-Based model, which concatinates the textual embeddings of the text captions for every image, with the visual embeddings of the base model. The text embeddings are calculated using the `all-MiniLM-L6-v2` model. All the code, along with embeddings calculation, and data, is available in the `classification_with_text` directory. The original captions are located in `classification_with_text/MBD_text`, and the embeddings are located inside the `combined_caption_embeddings.csv` file.
+### Experiment 4: Intuition-1 with simulated atmospheric conditions
 
-## Experiment 3: Fine tuning and inference on Sentinel 2 with simulated atmospheric conditions
+Analogous to Experiment 3, but using Intuition-1 imagery with simulated atmospheric conditions (TOA and BOA). This experiment tests robustness under domain shift.
 
-This experiment checks how the Terramind-Base behaves on the Sentinel-2 data with simulated atmospheric conditions. The simulated data is both in the Top-of-Atmosphere and Bottom-of-Atmsphere variants. The model can be both trained on this data, or only run on it, to test how good it is at generalization when trained on different data.
+### Experiment 5: Urban dataset without methane (false-positive stress test)
 
-## Experiment 4: Fine tuning and inference on Intuition 1 with simulated atmosphric conditions
+A control dataset containing only urban imagery without methane is used to check whether models learn methane-specific cues rather than urban signatures. The goal is to quantify false positives.
 
-This experiment checks how the Terramind-Base behaves on the Intuition-1 data with simulated atmospheric conditions. The simulated data is both in the Top-of-Atmosphere and Bottom-of-Atmsphere variants. The model can be both trained on this data, or only run on it, to test how good it is at generalization when trained on different data.
+Scripts for loading and running inference on this dataset are provided in the repository.
 
-## Experiment 5: Testing the detector on urban dataset without methane
+## Notes
 
-The urban dataset has been prepared to check whether the models really learned to detect methane from multispectral data or just look for urban signatures in the images. All of the images in this dataset do not contain methane, the goal is to run the models and see how many false positives are returned. Python script for loading and running the models were attatched.
+- Use `--help` on each runner/training script to see available options.
+- Keep fold definitions consistent with `Methane_benchmark_patches_summary_v3.xlsx` to ensure comparable results across experiments.