estebanr25/decafia

 license: cc-by-4.0
 library_name: ultralytics
 tags:
   - object-detection
   - yolov8
   - agriculture
   - plant-disease
   - coffee
 datasets:
   - https://doi.org/10.5281/zenodo.19931903
 language:
   - en
 ---

 # DECAFIA — YOLOv8m Coffee Leaf Disease Detector

 YOLOv8m object-detection model for three coffee crop threats, trained on
 field images from *Coffea arabica* plantations in El Socorro, Santander,
 Colombia, supplemented with the Silva et al. rust-and-leaf-miner dataset.

 **Dataset:** [CoffeeLeaf-CO v2 on Zenodo](https://doi.org/10.5281/zenodo.19931903)
 (concept DOI 10.5281/zenodo.19931903, CC BY 4.0)

 **Training code & full results:** [estebanr25/decafia-research](https://github.com/estebanr25/decafia-research)

 ---

 ## Files in this repository

 | File | Description |
 |------|-------------|
 | `decafia_clean_best.pt` | **Current model.** YOLOv8m, 3-class output head (roya, coco, minador), trained on CoffeeLeaf-CO
 v2.0.0. All metrics in this card refer to this file. |
 | `decafia_best.onnx` | **Legacy model — retained for production reproducibility only.** Trained on the v1 dataset with a
 4-class output head whose fourth class (`sano`) carried zero annotated instances. Superseded; not recommended for new work. |

 > **The two files have different output shapes and are not interchangeable.**
 > `decafia_clean_best.pt` produces 3-class scores; `decafia_best.onnx`
 > produces 4-class scores. Code written for one will produce incorrect results
 > if pointed at the other without modification.

 ---

 ## Detection classes

 The model predicts **three classes only**:

 | ID | Label | Pathogen / agent |
 |---:|-------|-----------------|
 | 0 | `roya` | *Hemileia vastatrix* — coffee leaf rust |
 | 1 | `coco` | Curculionidae weevils (*Compsus* sp. / *Epicaerus* sp.) — weevil defoliation |
 | 2 | `minador` | *Leucoptera coffeella* — coffee leaf miner |

 **Healthy leaves are not a detection class.** There is no `sano` class.
 Healthy-leaf images are background examples with **empty label files**.
 A healthy verdict is derived from the **absence of any detection above the
 confidence threshold (0.50)**; no bounding box is predicted for healthy tissue.

 > **Taxonomy note — `coco`:** The weevil defoliation class was previously
 > mislabelled as *Pseudococcus jamaicensis* (a scale insect) in earlier
 > releases. The correct identification is leaf-chewing weevils of family
 > Curculionidae, genera *Compsus* and *Epicaerus*, per:
 > Constantino et al. (2013). *Manual del Cafetero Colombiano*, Vol. 2,
 > pp. 261–306. Cenicafé.
 > DOI: [10.38141/cenbook-0026_25](https://doi.org/10.38141/cenbook-0026_25)

 ---

 ## Intended use

 Automated detection of rust, weevil defoliation, and leaf-miner damage on
 individual coffee leaf images for research and field-monitoring applications.
 The model is intended to be used as a component within a larger system (e.g.,
 WhatsApp bot, mobile app) where images are captured in Colombian Andean
 field conditions similar to the training site.

 ### Limitations

 - **Single collection site.** Own-field images come exclusively from
   one farm in El Socorro, Santander (~1,500 m a.s.l.). Performance on
   farms with different varieties, altitudes, or lighting conditions has
   not been validated.
 - **Minador — cross-country generalisation only.** All 2,385 minador
   annotations come from Silva et al. (Brazil); no Colombian field images
   of leaf-miner damage were available at training time. Minador mAP
   measures generalisation across a training/deployment domain shift,
   not in-distribution Colombian performance.
 - **Roya — mixed source.** 60% of roya annotations by instance count
   (52.6% by image count) are own-field; 40% / 47.4% are from Silva et al.
 - **Coco — fully Colombian.** All 5,389 coco annotations are own-field
   (El Socorro). Coco mAP is the most reliable indicator of Colombian
   field performance.
 - **Not validated for other regions or cultivars.** Adaptation to other
   countries, *Coffea robusta*, or significantly different phenological
   stages may require fine-tuning.
 - **Confidence threshold.** The operational threshold is 0.50. Lowering
   it substantially increases false positives on background images.

 ---

 ## Test-set results

 Evaluated on the held-out test split. Metrics are computed at the
 F1-optimal confidence threshold per class.

 **Test split:** 349 images, 1,948 annotated instances
 (167 background / empty-label images included)

 ### Per-class metrics

 | Class | Precision | Recall | F1 | mAP50 | mAP50-95 |
 |-------|----------:|-------:|---:|------:|---------:|
 | roya | 0.8364 | 0.7931 | 0.8142 | 0.8619 | 0.5700 |
 | coco | 0.9177 | 0.9087 | 0.9132 | 0.9638 | 0.7921 |
 | minador | 0.8687 | 0.8987 | 0.8834 | 0.9449 | 0.8258 |
 | **all** | | | | **0.9235** | **0.7293** |

 ### Background-image suppression (conf ≥ 0.50)

 Of the 167 background test images (healthy-leaf images with empty label files):

 | Outcome | Count | Fraction |
 |---------|------:|---------:|
 | Zero detections (correct) | 164 | 98.2% |
 | ≥ 1 detection (false positive) | 3 | 1.8% |
 | Total FP detections | 4 | — |

 At the operational threshold the model correctly suppresses spurious detections
 on healthy tissue in 98.2% of background images.

 ---

 ## Dataset

 | Split | Images | Roya ann. | Coco ann. | Minador ann. | Total ann. | Background imgs |
 |-------|-------:|----------:|----------:|-------------:|-----------:|----------------:|
 | train | 1,618 | 3,433 | 3,883 | 1,634 | 8,950 | 779 |
 | val | 348 | 723 | 807 | 366 | 1,896 | 167 |
 | test | 349 | 864 | 699 | 385 | 1,948 | 167 |
 | **Total** | **2,315** | **5,020** | **5,389** | **2,385** | **12,794** | **1,113** |

 Split ratio: 70 / 15 / 15, stratified by class-presence signature, seed = 42.

 **Sources:**

 | Source | Images | Roya instances | Coco instances | Minador instances |
 |--------|-------:|---------------:|---------------:|------------------:|
 | Own-field (El Socorro, Santander) | 1,705 | 3,013 (60%) | 5,389 (100%) | 0 (0%) |
 | Silva et al. (DOI [10.17632/vfxf4trtcg.5](https://doi.org/10.17632/vfxf4trtcg.5)) | 610 | 2,007 (40%) | 0 (0%) | 2,385
 (100%) |

 RoCoLe (Parraga-Alava et al., DOI 10.17632/c5yvn32dzg.2) was excluded to
 preserve it as an independent external validation set. Exclusion also removed
 5 SHA256 duplicate pairs including 3 train/test cross-split leaks present in
 the prior dataset version.

 ---

 ## Training details

 | Parameter | Value |
 |-----------|-------|
 | Architecture | YOLOv8m (~26 M parameters) |
 | Base weights | `yolov8m.pt` (COCO-pretrained) |
 | Epochs | 100 (early-stop patience 20) |
 | Image size | 640 × 640 |
 | Batch size | 16 |
 | Optimizer | AdamW |
 | LR schedule | Linear decay, lr₀ = 0.01, lr_f = 1 × 10⁻⁵ (cos_lr = false) |
 | Seed | 42 (random, numpy, torch, CUDA) |
 | `workers` | 0 (mandatory on Windows) |
 | Augmentation | mosaic = 1.0, mixup = 0.15, HSV jitter, horizontal/vertical flip, degrees = 15°, scale = 0.5 |
 | Hardware | NVIDIA RTX 5070 Laptop GPU (Blackwell sm_120, 8 GB VRAM), CUDA 12.8 |
 | Wall-clock time | 1 h 21 m 7 s (4,867.66 s; from `results.csv` cumulative time at epoch 100) |
 | Python | 3.14 |
 | ultralytics | 8.4.148 |
 | PyTorch | 2.11.0+cu128 |

 Full training config:
 [`configs/clean_v1.yaml`](https://github.com/estebanr25/decafia-research/blob/main/configs/clean_v1.yaml)

 ---

 ## How to use

 ```python
 from ultralytics import YOLO

 model = YOLO("estebanr25/decafia")   # loads weights from this Hub entry

 # Inference on a single image
 results = model.predict("leaf.jpg", conf=0.50)
 results[0].show()

 # Evaluate on your own test split
 metrics = model.val(data="path/to/data.yaml", split="test")
 print(metrics.box.map50)   # mAP50
 ```

 Output class indices: `0` = roya, `1` = coco, `2` = minador.
 An image with no detections at `conf >= 0.50` is treated as healthy.

 ---

 ## Superseded results

 The earlier model (`decafia_best.onnx`, v1 dataset) was reported elsewhere
 with **mAP50 = 92.4% / mAP50-95 = 76.6%**. Those figures are superseded
 and should not be cited. They came from a dataset with two known problems:

 1. **Cross-split SHA256 duplicate leakage** — 3 image pairs appeared in
    both train and test splits.
 2. **Declared class with zero annotated instances** — `sano` was listed in
    `data.yaml` but carried no bounding-box annotations. Because Ultralytics
    excludes zero-instance classes from the mAP mean, the reported mAP was
    effectively an average over three classes, not four.

 The figures in the Test-set results section above are from the corrected
 dataset (`decafia_clean`, CoffeeLeaf-CO v2).

 ---

 ## Citation

 ```bibtex
 @dataset{rosas2026decafia,
   author    = {Rosas Ruiz, Luis Esteban and
                Salom Medina, Andrey Fernando and
                Barrero Pérez, Jaime Guillermo},
   title     = {{CoffeeLeaf-CO}: {DECAFIA} coffee leaf disease dataset v2},
   year      = {2026},
   publisher = {Zenodo},
   doi       = {10.5281/zenodo.19931903},
   url       = {https://doi.org/10.5281/zenodo.19931903}
 }
 ```

 ---

 ## License

 Model weights and dataset: **CC BY 4.0**
 <https://creativecommons.org/licenses/by/4.0/>

 The Silva et al. subset is used under its original CC BY 4.0 licence
 (DOI [10.17632/vfxf4trtcg.5](https://doi.org/10.17632/vfxf4trtcg.5)).