Sensitivity test (#765)

* small sanity check for the sensitivity setting, needs some cleanup

* cleaned up the test and added docu + demo for sensitivity

* ruff fix

Author: max-mauermann

docs/_static/birdnet_sigmoid_sensitivity_old_vs_new.html

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

docs/implementation-details.rst

@@ -0,0 +1,12 @@
+Sensitivity
+===============================
+
+Starting with version 2.0.0, the BirdNET-Analyzer uses a new sensitivity implementation.
+Our goal with this change is to make the sensitivity more intuitive by changing it so that higher sensitivity values always lead to higher confidence scores.
+
+Comparison to the previous implementation
+--------------------------------------------------------
+
+Where the old implementation changed the slope of the sigmoid function, the new implementation performs a shift of the function.
+
+We have a little demo where you can explore the behavior of the old and the new sensitivity implementations `here <../_static/birdnet_sigmoid_sensitivity_old_vs_new.html>`_.

docs/implementation-details/sensitivity.rst

@@ -426,3 +426,50 @@ def test_analyze_with_additional_columns(mock_ensure_model, setup_test_environme
             assert float(row["sensitivity"]) == cfg.SIGMOID_SENSITIVITY, "Sensitivity value does not match expected value"
             assert row["species_list"] == "", "Species list value does not match expected value"
             assert float(row["min_conf"]) == 0, "Min confidence value does not match expected value"
+
+def test_sensitivity(setup_test_environment):
+    """Test sensitivity setting."""
+    env = setup_test_environment
+
+    soundscape_path = "birdnet_analyzer/example/soundscape.wav"
+
+    assert os.path.exists(soundscape_path), "Soundscape file does not exist"
+
+    normal_sensitivity_result = {}
+    low_sensitivity_result = {}
+    high_sensitivity_result = {}
+
+    # Call function under test
+    analyze(soundscape_path, env["output_dir"], top_n=1)
+    output_file = os.path.join(env["output_dir"], "soundscape.BirdNET.selection.table.txt")
+    assert os.path.exists(output_file)
+
+    def extract_confidence_from_output(output_file, result_dict):
+        with open(output_file) as f:
+            lines = f.readlines()[1:]
+            for line in lines:
+                parts = line.strip().split("\t")
+                start = float(parts[3])
+                end = float(parts[4])
+                confidence = float(parts[9])
+                result_dict[(start, end)] = confidence
+
+    extract_confidence_from_output(output_file, normal_sensitivity_result)
+
+    analyze(soundscape_path, env["output_dir"], top_n=1, sensitivity=0.75)
+    output_file = os.path.join(env["output_dir"], "soundscape.BirdNET.selection.table.txt")
+    assert os.path.exists(output_file)
+
+    extract_confidence_from_output(output_file, low_sensitivity_result)
+
+    analyze(soundscape_path, env["output_dir"], top_n=1, sensitivity=1.25)
+    output_file = os.path.join(env["output_dir"], "soundscape.BirdNET.selection.table.txt")
+    assert os.path.exists(output_file)
+
+    extract_confidence_from_output(output_file, high_sensitivity_result)
+
+    for key in normal_sensitivity_result:
+        assert key in low_sensitivity_result, "Low sensitivity result missing key from normal sensitivity result"
+        assert key in high_sensitivity_result, "High sensitivity result missing key from normal sensitivity result"
+        assert low_sensitivity_result[key] <= normal_sensitivity_result[key], "Low sensitivity confidence should be less than or equal to normal sensitivity"
+        assert high_sensitivity_result[key] >= normal_sensitivity_result[key], "High sensitivity confidence should be greater than or equal to normal sensitivity"