Final set of editing based on Anthony's requests.

Issue #451 A few further changes to make a parameter available to the user with changes accordingly to the documentation.

docs/guides/generic_recognizers.md

@@ -413,7 +413,7 @@ The final post-processing step is to remove all but the longest duration event i
 
 Post processing is optional - you may decide to combine or filter the "raw" events using code you have written yourself.
 To add a post-processing section to your config file, insert the `PostProcessing` keyword and indent its parameters.
-There are five post-processing possibilities, each of which is optional.
+There are six post-processing possibilities, each of which is optional.
 However the order in which these steps are performed _cannot_ be changed by the user. The post-processing sequence is:
 
 > 1. Combine events having temporal _and_ spectral overlap.
@@ -424,10 +424,12 @@ However the order in which these steps are performed _cannot_ be changed by the
 
 > 4. Remove (filter) events whose bandwidth is outside an acceptable range.
 
-> 5. Remove (filter) events having excessive acoustic activity in their sidebands.  
+> 5. Remove (filter) events having excessive acoustic activity in their sidebands.
 
-    > [!NOTE]:
-    If you do not wish to include a post-processing step, delete or comment out the key word and all its component parameters using a `#` at the start of each relevant line in the config file.
+> 6. Remove (filter) events that are enclosed by another event.
+
+  > [!NOTE]:
+    If you do not wish to include a post-processing step, delete or comment out the key-word and all its component parameters using a `#` at the start of each relevant line in the config file.
     The only exception to this is to set boolean parameters to `false` where this option exists.
     Removing a post-processing filter means that all events are accepted for that step.
 
@@ -501,7 +503,7 @@ Use the keyword `SidebandAcousticActivity` to enable sideband filtering. There a
 
 2. `UpperSidebandWidth` sets the width of the desired sideband "zone" above the target event.
 
-There are two tests for determining if the acoustic activity in a sideband is excessive, each having a single parameter:
+> There are two tests for determining if the acoustic activity in a sideband is excessive, each having a single parameter:
 
 3. `MaxBackgroundDecibels` sets a threshold value for the maximum permitted background or average decibel value in each sideband. The average is taken over all spectrogram cells included in a sideband, excluding those adjacent to the event.
 
@@ -518,6 +520,16 @@ Only one sideband bin or frame is allowed to contain acoustic activity exceeding
     ```
     > In this example, only one test (for background noise) will be performed on only one sideband (the lower). If no sideband tests are performed, all events will be accepted regardless of the acoustic activity in their sidebands.
 
+
+### Remove events that are enclosed by other events.
+
+Running profiles with multiple decibel thresholds can produce sets of nested or enclosed
+events  (Russian doll events!)  that are actually the result of detecting the same acoustic syllable.
+This final (optional) post-processing step is to remove all but the outermost event of any nested set by setting the parameter `RemoveTemporallyEnclosedEvents` to `true`. 
+You would typically do this only after reviewing the output spectrograms to confirm that you have sets of nested events.
+
+This brings us to the final group of parameters that determine what results are written to file.
+
 ### Parameters for saving results
 
 The parameters in this final part of the config file determine what results are saved to file.

src/AnalysisConfigFiles/RecognizerConfigFiles/Towsey.NinoxBoobook.yml

@@ -66,6 +66,9 @@ PostProcessing:
     #    UpperSidebandWidth: 400
     #    MaxBackgroundDecibels: 12
     #    MaxActivityDecibels: 12
+
+    # 6: In the case of sets of nested/enclosed events, filter/remove all but the outermost event. 
+    RemoveTemporallyEnclosedEvents: true
 
 # Options to save results files
 # 1: Available options for saving spectrograms (case-sensitive): [False/Never | True/Always | WhenEventsDetected]

src/AnalysisConfigFiles/RecognizerConfigFiles/Towsey.NinoxStrenua.yml

@@ -77,6 +77,10 @@ PostProcessing:
         MaxBackgroundDecibels: null
         MaxActivityDecibels: null
 
+    # 6: In the case of sets of nested/enclosed events, filter/remove all but the outermost event. 
+    RemoveTemporallyEnclosedEvents: true
+
+
 # Various options to save results files
 # 1: Available options for saving spectrograms (case-sensitive): [False/Never | True/Always | WhenEventsDetected]
 # "True" is useful when debugging but "WhenEventsDetected" is required for operational use.

src/AnalysisPrograms/Recognizers/GenericRecognizer.cs

@@ -138,15 +138,12 @@ public override RecognizerResults Recognize(
 
             var postprocessingConfig = configuration.PostProcessing;
             var postEvents = new List<EventCommon>();
-
             var groups = results.NewEvents.GroupBy(x => x.DecibelDetectionThreshold);
 
             foreach (var group in groups)
             {
                 var key = group.Key;
                 List<EventCommon> events = group.ToList<EventCommon>();
-                //Log.Debug($"Profiles detected {events.Count} events at threshold {key} dB.");
-
                 var ppEvents = EventPostProcessing.PostProcessingOfSpectralEvents(
                     events,
                     postprocessingConfig,
@@ -157,12 +154,19 @@ public override RecognizerResults Recognize(
                 postEvents.AddRange(ppEvents);
             }
 
-            // Running profiles with multiple dB thresholds produces nested (Russian doll) events.
+            // Running profiles with multiple dB thresholds can produce enclosed or temporally nested (Russian doll) events.
             // Remove all but the outermost event.
-            Log.Debug($"\nREMOVE EVENTS ENCLOSED BY LONGER EVENTS.");
-            Log.Debug($"Event count BEFORE removing enclosed events = {postEvents.Count}.");
-            results.NewEvents = CompositeEvent.RemoveEnclosedEvents(postEvents);
-            Log.Debug($"Event count AFTER  removing enclosed events = {postEvents.Count}.");
+            if (configuration.PostProcessing.RemoveTemporallyEnclosedEvents)
+            {
+                Log.Debug($"\nREMOVE EVENTS ENCLOSED BY LONGER EVENTS.");
+                Log.Debug($"Event count BEFORE removing enclosed events = {postEvents.Count}.");
+                results.NewEvents = CompositeEvent.RemoveEnclosedEvents(postEvents);
+                Log.Debug($"Event count AFTER  removing enclosed events = {postEvents.Count}.");
+            }
+            else
+            {
+                Log.Debug($"\nEVENTS ENCLOSED BY LONGER EVENTS WERE NOT REMOVED.");
+            }
 
             // Write out the events to log.
             if (postEvents.Count > 0)

src/AudioAnalysisTools/Events/Types/EventPostProcessing.cs

@@ -160,11 +160,6 @@ public class PostProcessingConfig
             /// </summary>
             public SyllableSequenceConfig SyllableSequence { get; set; }
 
-            /// <summary>
-            /// Gets or sets the parameters required to filter events on the acoustic activity in their sidebands.
-            /// </summary>
-            public SidebandConfig SidebandAcousticActivity { get; set; }
-
             /// <summary>
             /// Gets or sets the parameters required to filter events on their duration.
             /// </summary>
@@ -174,6 +169,19 @@ public class PostProcessingConfig
             /// Gets or sets the parameters required to filter events on their bandwidth.
             /// </summary>
             public BandwidthConfig Bandwidth { get; set; }
+
+            /// <summary>
+            /// Gets or sets the parameters required to filter events on the acoustic activity in their sidebands.
+            /// </summary>
+            public SidebandConfig SidebandAcousticActivity { get; set; }
+
+            /// <summary>
+            /// Gets or sets a value indicating Whether or not to remove temporally enclosed/nested events.
+            /// Running profiles with multiple dB thresholds can produce sets of enclosed or temporally nested events.
+            /// Russian doll events!
+            /// Setting this boolean true removes all but the outermost of any set of encloseed events.
+            /// </summary>
+            public bool RemoveTemporallyEnclosedEvents { get; set; }
         }
 
         /// <summary>