# evandroct/mdpi-nrt-forest-monitoring architecture

> Architecture diagram of the GitHub repository evandroct/mdpi-nrt-forest-monitoring, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/evandroct/mdpi-nrt-forest-monitoring
- Repository: https://github.com/evandroct/mdpi-nrt-forest-monitoring

## Overview

This repository reproduces selective-logging monitoring from source-data preparation through model training, inference, temporal filtering, and evaluation. The documented main route starts with the Zenodo corpora, pretrains an ST-MAE, fits leave-one-monitoring-unit-out soft-label regressors, then evaluates detection filters and their outputs. Separate scripts rebuild the upstream corpora from DETER-derived ROIs and HLS imagery. The graph retains README-documented evaluation branches; unsampled scripts are represented by their exact paths, with relationships included only where the README or shown source supports them.

Main entry points: [`07_detector/build_dense_pred_variant.py`](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/07_detector/build_dense_pred_variant.py) (Dense predictions), [`04_pretraining/model.py`](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/04_pretraining/model.py) (ST-MAE model), [`06_regressor/train_classifier.py`](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/06_regressor/train_classifier.py) (Regressor training), [`04_pretraining/train.py`](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/04_pretraining/train.py) (Pretraining)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_corpora["Corpus rebuilding"]
  node_roi["ROI candidates"]
  node_eligibility["Eligibility scan"]
  node_acquisition["HLS acquisition"]
  node_cubes["GeoZarr assembly"]
  node_sharedqc["Shared eligibility<br/>[eligibility.py]"]
  node_recordfetch["Record download<br/>[download_record.py]"]
end

subgraph group_foundation["Foundation model"]
  node_dataset["Pretraining dataset<br/>[dataset.py]"]
  node_mae["ST-MAE model<br/>[model.py]"]
  node_pretrain["Pretraining<br/>[train.py]"]
  node_curriculum["Training curriculum<br/>[train_extend.py]"]
end

subgraph group_regression["Downstream regression"]
  node_cache["Crop caches<br/>[build_caches.py]"]
  node_classdata["Soft-label dataset"]
  node_head["Classifier head<br/>[classifier_head.py]"]
  node_regtrain["Regressor training"]
  node_loocv["LOO-CV orchestration<br/>[loocv_chain.py]"]
  node_oof["OOF aggregation<br/>[agg_oof.py]"]
end

subgraph group_inference["Prediction products"]
  node_predict["Raster inference"]
  node_indices["Index VRTs"]
end

subgraph group_detection["Detection evaluation"]
  node_dense["Dense predictions"]
  node_sweep["Kernel sweep<br/>[sweep_kernels.py]"]
  node_nested["Nested evaluation<br/>[nested_sweep.py]"]
  node_nestedtables["Nested results"]
  node_negative["Negative test"]
  node_selecttargets["Target selection<br/>[select_targets.py]"]
  node_scoretargets["Target scoring<br/>[score_targets.py]"]
  node_deteralerts["DETER survey<br/>[deter_survey.py]"]
  node_alerttables["Alert tables"]
  node_munumbers["MU numbering"]
  node_paper["Kernel summaries"]
end

node_analyst(("Pipeline operator"))
node_zenodo[("Zenodo record")]
node_deter[("DETER alerts")]
node_hls[("HLS imagery")]

node_analyst -->|"fetch record"| node_recordfetch
node_zenodo -->|"provides archives"| node_recordfetch
node_analyst -->|"rebuild corpora"| node_roi
node_deter -->|"derives ROIs"| node_roi
node_roi -->|"screens candidates"| node_eligibility
node_eligibility -->|"uses rules"| node_sharedqc
node_analyst -->|"acquire imagery"| node_acquisition
node_hls -->|"supplies scenes"| node_acquisition
node_acquisition -->|"assembles imagery"| node_cubes
node_analyst -->|"train foundation"| node_pretrain
node_dataset -->|"uses rules"| node_sharedqc
node_pretrain -->|"loads samples"| node_dataset
node_pretrain -->|"trains model"| node_mae
node_curriculum -->|"launches stages"| node_pretrain
node_analyst -->|"run cross-validation"| node_loocv
node_loocv -->|"runs folds"| node_regtrain
node_analyst -->|"build caches"| node_cache
node_cache -->|"prepares variants"| node_classdata
node_regtrain -->|"loads labels"| node_classdata
node_regtrain -->|"loads trunk"| node_mae
node_regtrain -->|"fits head"| node_head
node_analyst -->|"aggregate metrics"| node_oof
node_analyst -->|"run inference"| node_predict
node_predict -->|"loads checkpoint model"| node_mae
node_analyst -->|"create views"| node_indices
node_indices -->|"reads prediction rasters"| node_predict
node_analyst -->|"build dense output"| node_dense
node_dense -->|"uses trunk"| node_mae
node_dense -->|"uses classifier"| node_head
node_dense -->|"uses dataset logic"| node_classdata
node_analyst -->|"search filters"| node_sweep
node_sweep -->|"reads predictions"| node_dense
node_analyst -->|"evaluate nested folds"| node_nested
node_nested -->|"uses kernels"| node_sweep
node_analyst -->|"summarize nested results"| node_nestedtables
node_nestedtables -->|"imports numbering"| node_munumbers
node_analyst -->|"select test targets"| node_selecttargets
node_analyst -->|"evaluate negatives"| node_negative
node_negative -->|"uses filter kernels"| node_sweep
node_scoretargets -->|"runs trunk"| node_mae
node_scoretargets -->|"scores with head"| node_head
node_analyst -->|"survey alert periods"| node_deteralerts
node_analyst -->|"build alert tables"| node_alerttables
node_alerttables -->|"imports numbering"| node_munumbers
node_analyst -->|"report kernel metrics"| node_paper

click node_roi "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/01_rois/build_roi_candidates.py"
click node_eligibility "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/02_download/scan_eligibility.py"
click node_acquisition "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/02_download/hls_stac_download.py"
click node_cubes "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/03_cubes/build_geozarr_datacubes.py"
click node_sharedqc "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/common/eligibility.py"
click node_recordfetch "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/00_data/download_record.py"
click node_dataset "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/04_pretraining/dataset.py"
click node_mae "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/04_pretraining/model.py"
click node_pretrain "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/04_pretraining/train.py"
click node_curriculum "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/04_pretraining/recipes/train_extend.py"
click node_cache "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/06_regressor/build_caches.py"
click node_classdata "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/common/dataset_classifier.py"
click node_head "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/common/classifier_head.py"
click node_regtrain "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/06_regressor/train_classifier.py"
click node_loocv "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/06_regressor/loocv_chain.py"
click node_oof "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/06_regressor/agg_oof.py"
click node_predict "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/05_inference/predict_geotiffs.py"
click node_indices "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/05_inference/make_indices_vrts.py"
click node_dense "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/07_detector/build_dense_pred_variant.py"
click node_sweep "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/07_detector/sweep_kernels.py"
click node_nested "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/07_detector/nested_sweep.py"
click node_nestedtables "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/07_detector/make_nested_tables.py"
click node_negative "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/07_detector/negative_test/evaluate_targets.py"
click node_selecttargets "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/07_detector/negative_test/select_targets.py"
click node_scoretargets "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/07_detector/negative_test/score_targets.py"
click node_deteralerts "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/07_detector/deter_alerts/deter_survey.py"
click node_alerttables "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/07_detector/deter_alerts/make_deter_tables.py"
click node_munumbers "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/07_detector/paper_mu_numbers.py"
click node_paper "https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/07_detector/paper_mu_numbers.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_roi,node_eligibility,node_acquisition,node_cubes,node_sharedqc,node_recordfetch toneBlue
class node_dataset,node_mae,node_pretrain,node_curriculum,node_zenodo,node_deter,node_hls toneAmber
class node_cache,node_classdata,node_head,node_regtrain,node_loocv,node_oof toneMint
class node_predict,node_indices toneRose
class node_dense,node_sweep,node_nested,node_nestedtables,node_negative,node_selecttargets,node_scoretargets,node_deteralerts,node_alerttables,node_munumbers,node_paper,node_analyst toneIndigo
```

## Components

### Corpus rebuilding

- [ROI candidates](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/01_rois/build_roi_candidates.py): `01_rois/build_roi_candidates.py`
- [Eligibility scan](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/02_download/scan_eligibility.py): `02_download/scan_eligibility.py`
- [HLS acquisition](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/02_download/hls_stac_download.py): `02_download/hls_stac_download.py`
- [GeoZarr assembly](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/03_cubes/build_geozarr_datacubes.py): `03_cubes/build_geozarr_datacubes.py`
- [Shared eligibility](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/common/eligibility.py): `common/eligibility.py`
- [Record download](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/00_data/download_record.py): `00_data/download_record.py`

### Foundation model

- [Pretraining dataset](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/04_pretraining/dataset.py): `04_pretraining/dataset.py`
- [ST-MAE model](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/04_pretraining/model.py): `04_pretraining/model.py`
- [Pretraining](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/04_pretraining/train.py): `04_pretraining/train.py`
- [Training curriculum](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/04_pretraining/recipes/train_extend.py): `04_pretraining/recipes/train_extend.py`

### Downstream regression

- [Crop caches](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/06_regressor/build_caches.py): `06_regressor/build_caches.py`
- [Soft-label dataset](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/common/dataset_classifier.py): `common/dataset_classifier.py`
- [Classifier head](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/common/classifier_head.py): `common/classifier_head.py`
- [Regressor training](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/06_regressor/train_classifier.py): `06_regressor/train_classifier.py`
- [LOO-CV orchestration](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/06_regressor/loocv_chain.py): `06_regressor/loocv_chain.py`
- [OOF aggregation](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/06_regressor/agg_oof.py): `06_regressor/agg_oof.py`

### Prediction products

- [Raster inference](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/05_inference/predict_geotiffs.py): `05_inference/predict_geotiffs.py`
- [Index VRTs](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/05_inference/make_indices_vrts.py): `05_inference/make_indices_vrts.py`

### Detection evaluation

- [Dense predictions](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/07_detector/build_dense_pred_variant.py): `07_detector/build_dense_pred_variant.py`
- [Kernel sweep](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/07_detector/sweep_kernels.py): `07_detector/sweep_kernels.py`
- [Nested evaluation](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/07_detector/nested_sweep.py): `07_detector/nested_sweep.py`
- [Nested results](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/07_detector/make_nested_tables.py): `07_detector/make_nested_tables.py`
- [Negative test](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/07_detector/negative_test/evaluate_targets.py): `07_detector/negative_test/evaluate_targets.py`
- [Target selection](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/07_detector/negative_test/select_targets.py): `07_detector/negative_test/select_targets.py`
- [Target scoring](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/07_detector/negative_test/score_targets.py): `07_detector/negative_test/score_targets.py`
- [DETER survey](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/07_detector/deter_alerts/deter_survey.py): `07_detector/deter_alerts/deter_survey.py`
- [Alert tables](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/07_detector/deter_alerts/make_deter_tables.py): `07_detector/deter_alerts/make_deter_tables.py`
- [MU numbering](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/07_detector/paper_mu_numbers.py): `07_detector/paper_mu_numbers.py`
- [Kernel summaries](https://github.com/evandroct/mdpi-nrt-forest-monitoring/blob/main/07_detector/paper_mu_numbers.py): `07_detector/paper_mu_numbers.py`

### Other components

- **Pipeline operator**
- **Zenodo record**
- **DETER alerts**
- **HLS imagery**

## Connections

- Pipeline operator → Record download: fetch record (evidence: `README.md`)
- Zenodo record → Record download: provides archives (evidence: `README.md`)
- Pipeline operator → ROI candidates: rebuild corpora (evidence: `README.md`)
- DETER alerts → ROI candidates: derives ROIs (evidence: `README.md`)
- ROI candidates → Eligibility scan: screens candidates (evidence: `README.md`)
- Eligibility scan → Shared eligibility: uses rules (evidence: `02_download/scan_eligibility.py`)
- Pipeline operator → HLS acquisition: acquire imagery (evidence: `README.md`)
- HLS imagery → HLS acquisition: supplies scenes (evidence: `README.md`)
- HLS acquisition → GeoZarr assembly: assembles imagery (evidence: `README.md`)
- Pipeline operator → Pretraining: train foundation (evidence: `README.md`)
- Pretraining dataset → Shared eligibility: uses rules (evidence: `04_pretraining/dataset.py`)
- Pretraining → Pretraining dataset: loads samples (evidence: `04_pretraining/train.py`)
- Pretraining → ST-MAE model: trains model (evidence: `04_pretraining/train.py`)
- Training curriculum → Pretraining: launches stages (evidence: `README.md`)
- Pipeline operator → LOO-CV orchestration: run cross-validation (evidence: `README.md`)
- LOO-CV orchestration → Regressor training: runs folds (evidence: `README.md`)
- Pipeline operator → Crop caches: build caches (evidence: `README.md`)
- Crop caches → Soft-label dataset: prepares variants (evidence: `06_regressor/build_caches.py`)
- Regressor training → Soft-label dataset: loads labels (evidence: `06_regressor/train_classifier.py`)
- Regressor training → ST-MAE model: loads trunk (evidence: `06_regressor/train_classifier.py`)
- Regressor training → Classifier head: fits head (evidence: `06_regressor/train_classifier.py`)
- Pipeline operator → OOF aggregation: aggregate metrics (evidence: `README.md`)
- Pipeline operator → Raster inference: run inference (evidence: `README.md`)
- Raster inference → ST-MAE model: loads checkpoint model (evidence: `05_inference/predict_geotiffs.py`)
- Pipeline operator → Index VRTs: create views (evidence: `05_inference/make_indices_vrts.py`)
- Index VRTs → Raster inference: reads prediction rasters (evidence: `05_inference/make_indices_vrts.py`)
- Pipeline operator → Dense predictions: build dense output (evidence: `README.md`)
- Dense predictions → ST-MAE model: uses trunk (evidence: `07_detector/build_dense_pred_variant.py`)
- Dense predictions → Classifier head: uses classifier (evidence: `07_detector/build_dense_pred_variant.py`)
- Dense predictions → Soft-label dataset: uses dataset logic (evidence: `07_detector/build_dense_pred_variant.py`)
- Pipeline operator → Kernel sweep: search filters (evidence: `README.md`)
- Kernel sweep → Dense predictions: reads predictions (evidence: `07_detector/sweep_kernels.py`)
- Pipeline operator → Nested evaluation: evaluate nested folds (evidence: `README.md`)
- Nested evaluation → Kernel sweep: uses kernels (evidence: `07_detector/nested_sweep.py`)
- Pipeline operator → Nested results: summarize nested results (evidence: `README.md`)
- Nested results → MU numbering: imports numbering (evidence: `07_detector/make_nested_tables.py`)
- Pipeline operator → Target selection: select test targets (evidence: `README.md`)
- Pipeline operator → Negative test: evaluate negatives (evidence: `README.md`)
- Negative test → Kernel sweep: uses filter kernels (evidence: `07_detector/negative_test/evaluate_targets.py`)
- Target scoring → ST-MAE model: runs trunk (evidence: `07_detector/negative_test/score_targets.py`)
- Target scoring → Classifier head: scores with head (evidence: `07_detector/negative_test/score_targets.py`)
- Pipeline operator → DETER survey: survey alert periods (evidence: `README.md`)
- Pipeline operator → Alert tables: build alert tables (evidence: `README.md`)
- Alert tables → MU numbering: imports numbering (evidence: `07_detector/deter_alerts/make_deter_tables.py`)
- Pipeline operator → Kernel summaries: report kernel metrics (evidence: `README.md`)