documentation on the segment collection mode

Author: max-mauermann

docs/best-practices/segment-review.rst

@@ -35,14 +35,17 @@ Setting Parameters
 
 The GUI and command line tool allow you to set various parameters to customize the segment extraction process:
 
-* **Minimum Confidence** (``min_conf``): Set a minimum confidence value for predictions to be considered. It is recommended to determine the threshold by reviewing precision and recall.
+* **Minimum Confidence** (``min_conf``): Set a minimum confidence value for predictions to be considered.
+* **Maximum Confidence** (``max_conf``): Set a maximum confidence value for predictions to be considered.
 * **Maximum Number of Segments** (``num_seq``): Specify how many segments per species should be extracted.
 * **Audio Speed** (``audio_speed``): Adjust the playback speed. Extracted segments will be saved with the adjusted speed (e.g., to listen to ultrasonic calls).
 * **Segment Length** (``seq_length``): Define how long the extracted audio segments should be. If you set to more than 3 seconds, each segment will be padded with audio from the source recording. For example, for 5-second segment length, 1 second of audio before and after each extracted segment will be included. For 7 seconds, 2 seconds will be included, and so on. The first and last segment of each audio file might be shorter than the specified length.
-
-.. note::
-
-    The desired minimum confidence value can be different for each species.
+* **Segment Collection Mode** (``collection_mode``): Choose how segments are selected. Following options are available:
+    
+    * **random**: Select segments randomly.
+    * **confidence**: Select segments based on confidence values, starting with the highest confidence scores.
+    * **balanced**: Select segments equally distributed across confidence values.
+    * :doc:`More details on segment collection modes <../implementation-details/segment-collection-mode>`
 
 Extracting Segments
 -------------------

docs/implementation-details.rst

@@ -4,4 +4,5 @@ Implementation details
 .. toctree::
    :maxdepth: 1
 
-   implementation-details/crop-modes
+   implementation-details/crop-modes
+   implementation-details/segment-collection-mode

docs/implementation-details/segment-collection-mode.rst

@@ -0,0 +1,29 @@
+Segment Collection Modes
+===============================
+
+This page describes the different segment collection modes available for the segment-extraction feature in the BirdNET-Analyzer.
+In general the segments feature collects all detections from the provided result files according to the specified confidence range.
+Then segments are selected for each species up to the specified maximum number segments.
+If there are more detections than the maximum for a species, the segment collection mode gives you control over which segments are selected.
+The goal of this is to get a more representative set of segments to use in the review feature or to get only high confidence segments to use as training data.
+The following segment collection modes are available:
+
+1. Random
+----------------
+
+This mode will select segments randomly from the detections that are within the specified confidence range.
+Therefore it will mirror the distribution of the confidence values in the detections.
+
+2. Confidence
+----------------
+
+This mode will select segments based on confidence values, starting with the highest confidence scores.
+
+3. Balanced
+----------------
+
+This mode will select segments equally distributed across the specified confidence range.
+In more detail, we divide the confidence range into a specified number of bins (10 by default) and sort the detections into them.
+Then total number of segments is divided by the number of bins to get the maximum number of segments per bin.
+Finally for each bin we randomly select the up to the maximum number of segments from each bin.
+Due to rounding and the distribution of confidence values, the total number of segments might be less than the specified maximum even if there are more segments available.