Merge pull request #579 from kahst:extend-docs

Change how sensitivity works

birdnet_analyzer/analyze/utils.py

@@ -167,22 +167,23 @@ def generate_kaleidoscope(timestamps: list[str], result: dict[str, list], afile_
         start, end = timestamp.split("-", 1)
 
         for c in result[timestamp]:
-            label = cfg.TRANSLATED_LABELS[cfg.LABELS.index(c[0])]
-            rstring += "{},{},{},{},{},{},{},{:.4f},{:.4f},{:.4f},{},{},{}\n".format(
-                parent_folder.rstrip("/"),
-                folder_name,
-                filename,
-                start,
-                float(end) - float(start),
-                label.split("_", 1)[0],
-                label.split("_", 1)[-1],
-                c[1],
-                cfg.LATITUDE,
-                cfg.LONGITUDE,
-                cfg.WEEK,
-                cfg.SIG_OVERLAP,
-                (1.0 - cfg.SIGMOID_SENSITIVITY) + 1.0,
-            )
+            if c[1] > cfg.MIN_CONFIDENCE and (not cfg.SPECIES_LIST or c[0] in cfg.SPECIES_LIST):
+                label = cfg.TRANSLATED_LABELS[cfg.LABELS.index(c[0])]
+                rstring += "{},{},{},{},{},{},{},{:.4f},{:.4f},{:.4f},{},{},{}\n".format(
+                    parent_folder.rstrip("/"),
+                    folder_name,
+                    filename,
+                    start,
+                    float(end) - float(start),
+                    label.split("_", 1)[0],
+                    label.split("_", 1)[-1],
+                    c[1],
+                    cfg.LATITUDE,
+                    cfg.LONGITUDE,
+                    cfg.WEEK,
+                    cfg.SIG_OVERLAP,
+                    cfg.SIGMOID_SENSITIVITY,
+                )
 
         # Write result string to file
         out_string += rstring
@@ -459,7 +460,7 @@ def predict(samples):
 
     # Logits or sigmoid activations?
     if cfg.APPLY_SIGMOID:
-        prediction = model.flat_sigmoid(np.array(prediction), sensitivity=-cfg.SIGMOID_SENSITIVITY)
+        prediction = model.flat_sigmoid(np.array(prediction), sensitivity=-1, bias=cfg.SIGMOID_SENSITIVITY)
 
     return prediction
 

birdnet_analyzer/cli.py

@@ -121,7 +121,7 @@ def sigmoid_args():
     """
     Creates an argument parser for sigmoid sensitivity.
     This function sets up an argument parser with a single argument `--sensitivity`.
-    The sensitivity value is constrained to be within the range [0.5, 1.5], where higher
+    The sensitivity value is constrained to be within the range [0.75, 1.25], where higher
     values result in higher detection sensitivity. The default value is taken from
     `cfg.SIGMOID_SENSITIVITY`.
     Returns:
@@ -130,9 +130,9 @@ def sigmoid_args():
     p = argparse.ArgumentParser(add_help=False)
     p.add_argument(
         "--sensitivity",
-        type=lambda a: max(0.5, min(1.0 - (float(a) - 1.0), 1.5)),
+        type=lambda a: min(1.25, max(0.75, float(a))),
         default=cfg.SIGMOID_SENSITIVITY,
-        help="Detection sensitivity; Higher values result in higher sensitivity. Values in [0.5, 1.5].",
+        help="Detection sensitivity; Higher values result in higher sensitivity. Values in [0.75, 1.25].",
     )
 
     return p

birdnet_analyzer/gui/analysis.py

@@ -180,7 +180,7 @@ def run_analysis(
     cfg.MIN_CONFIDENCE = confidence
 
     # Set sensitivity
-    cfg.SIGMOID_SENSITIVITY = max(0.5, min(1.0 - (float(sensitivity) - 1.0), 1.5))
+    cfg.SIGMOID_SENSITIVITY = min(1.25, max(0.75, float(sensitivity)))
 
     # Set overlap
     cfg.SIG_OVERLAP = max(0.0, min(2.9, float(overlap)))

birdnet_analyzer/gui/utils.py

@@ -291,8 +291,8 @@ def sample_sliders(opened=True):
         with gr.Group():
             with gr.Row():
                 sensitivity_slider = gr.Slider(
-                    minimum=0.5,
-                    maximum=1.5,
+                    minimum=0.75,
+                    maximum=1.25,
                     value=1,
                     step=0.01,
                     label=loc.localize("inference-settings-sensitivity-slider-label"),

birdnet_analyzer/model.py

@@ -781,22 +781,32 @@ def custom_loss(y_true, y_pred, epsilon=1e-7):
     return total_loss
 
 
-def flat_sigmoid(x, sensitivity=-1):
+def flat_sigmoid(x, sensitivity=-1, bias=1.0):
     """
-    Applies a flat sigmoid function to the input array.
+    Applies a flat sigmoid function to the input array with a bias shift.
 
     The flat sigmoid function is defined as:
-        f(x) = 1 / (1 + exp(sensitivity * clip(x, -15, 15)))
+        f(x) = 1 / (1 + exp(sensitivity * clip(x + bias, -20, 20)))
+        
+    We transform the bias parameter to a range of [-100, 100] with the formula:
+        transformed_bias = (bias - 1.0) * 10.0
+        
+    Thus, higher bias values will shift the sigmoid function to the right on the x-axis, making it more "sensitive".
+        
+    Note: Not sure why we are clipping, must be for numerical stability somewhere else in the code.
 
     Args:
         x (array-like): Input data.
         sensitivity (float, optional): Sensitivity parameter for the sigmoid function. Default is -1.
+        bias (float, optional): Bias parameter to shift the sigmoid function on the x-axis. Must be in the range [0.01, 1.99]. Default is 1.0.
 
     Returns:
         numpy.ndarray: Transformed data after applying the flat sigmoid function.
     """
-    return 1 / (1.0 + np.exp(sensitivity * np.clip(x, -15, 15)))
+
+    transformed_bias = (bias - 1.0) * 10.0
 
+    return 1 / (1.0 + np.exp(sensitivity * np.clip(x + transformed_bias, -20, 20)))
 
 def predict(sample):
     """Uses the main net to predict a sample.