From 591d4f4ae8ef8570f6f9eb5f8808ad3e79b6101c Mon Sep 17 00:00:00 2001
From: mbsantiago <santiago.mbal@gmail.com>
Date: Sun, 29 Mar 2026 13:11:49 +0100
Subject: [PATCH] Update docs on roi separation

---
 docs/source/how_to/configure-roi-mapping.md   | 25 +++++++++++--------
 .../reference/targets-config-workflow.md      | 12 ++++++---
 2 files changed, 23 insertions(+), 14 deletions(-)

diff --git a/docs/source/how_to/configure-roi-mapping.md b/docs/source/how_to/configure-roi-mapping.md
index 924fa63..6189923 100644
--- a/docs/source/how_to/configure-roi-mapping.md
+++ b/docs/source/how_to/configure-roi-mapping.md
@@ -9,10 +9,11 @@ The default mapper is `anchor_bbox`.
 
 ```yaml
 roi:
-  name: anchor_bbox
-  anchor: bottom-left
-  time_scale: 1000.0
-  frequency_scale: 0.001163
+  default:
+    name: anchor_bbox
+    anchor: bottom-left
+    time_scale: 1000.0
+    frequency_scale: 0.001163
 ```
 
 ## 2) Choose an anchor strategy
@@ -32,15 +33,17 @@ comparing experiments.
 
 ## 4) (Optional) override ROI mapping for specific classes
 
-You can set class-level `roi` in `classification_targets` when needed.
+Add class-specific mappers under `roi.overrides`.
 
 ```yaml
-classification_targets:
-  - name: species_x
-    tags:
-      - key: class
-        value: Species X
-    roi:
+roi:
+  default:
+    name: anchor_bbox
+    anchor: bottom-left
+    time_scale: 1000.0
+    frequency_scale: 0.001163
+  overrides:
+    species_x:
       name: anchor_bbox
       anchor: center
       time_scale: 1000.0
diff --git a/docs/source/reference/targets-config-workflow.md b/docs/source/reference/targets-config-workflow.md
index b512092..9715a8e 100644
--- a/docs/source/reference/targets-config-workflow.md
+++ b/docs/source/reference/targets-config-workflow.md
@@ -11,7 +11,8 @@ Fields:
 - `detection_target`: one `TargetClassConfig` defining detection eligibility.
 - `classification_targets`: list of `TargetClassConfig` entries for class
   encoding/decoding.
-- `roi`: default ROI mapper config.
+- `roi`: ROI mapping config with `default` mapper and optional per-class
+  `overrides`.
 
 ## `TargetClassConfig`
 
@@ -23,7 +24,6 @@ Fields:
 - `tags`: tag list used for matching (shortcut for `match_if`).
 - `match_if`: explicit condition config (`match_if` is accepted as alias).
 - `assign_tags`: tags used when decoding this class.
-- `roi`: optional class-specific ROI mapper override.
 
 `tags` and `match_if` are mutually exclusive.
 
@@ -42,7 +42,8 @@ Built from `batdetect2.data.conditions`.
 
 ## ROI mapper config
 
-`roi` supports built-in mappers including:
+`roi.default` and each `roi.overrides.<class_name>` entry support built-in
+mappers including:
 
 - `anchor_bbox`
 - `peak_energy_bbox`
@@ -53,6 +54,11 @@ Key `anchor_bbox` fields:
 - `time_scale`
 - `frequency_scale`
 
+Top-level ROI mapping shape:
+
+- `default`: fallback mapper used for all classes.
+- `overrides`: optional mapping from class name to mapper config.
+
 ## Related pages
 
 - Detection target setup: {doc}`../how_to/configure-target-definitions`