More work on calculation and normalisation of event scores.

Issue #297

src/AudioAnalysisTools/CommonParameters.cs

@@ -77,5 +77,12 @@ public abstract class CommonParameters
         /// Gets or sets the threshold of "loudness" of a component. Units are decibels.
         /// </summary>
         public double? DecibelThreshold { get; set; } = 6;
+
+        /// <summary>
+        /// Gets or sets the maximum score for an event.
+        /// Setting this value sets a normalised score value for the event.
+        /// The normalised score is a linear conversion from 0 - maxScore to [0, 1].
+        /// </summary>
+        public double? MaxScore { get; set; }
     }
 }

src/AudioAnalysisTools/Events/Types/ChirpEvent.cs

@@ -15,12 +15,20 @@ namespace AudioAnalysisTools
 
     public class ChirpEvent : SpectralEvent, ITracks<Track>
     {
-        public ChirpEvent(Track chirp)
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ChirpEvent"/> class.
+        /// MaxScore establishes a scale for the chirp score. Typically the amplitude of track points is decibels.
+        /// A satisfactory maxScore is 12.0 decibels, since this is a high SNR in enviornmental recordings.
+        /// The normalised score is a linear conversion from 0 - maxScore to [0, 1].
+        /// </summary>
+        /// <param name="chirp">A chirp track consisting of a sequence of spectral points.</param>
+        /// <param name="maxScore">A maximum score used to normalise the track score.</param>
+        public ChirpEvent(Track chirp, double maxScore)
         {
             this.Tracks.Add(chirp);
 
-            // set score = to aaverage normalised amplitude score.
-            //this.Score = 
+            // set score = to average normalised amplitude score.
+            this.SetTrackScore(maxScore);
         }
 
         public List<Track> Tracks { get; private set; } = new List<Track>(1);
@@ -37,12 +45,18 @@ public ChirpEvent(Track chirp)
         public override double HighFrequencyHertz =>
             this.Tracks.Max(x => x.HighFreqHertz);
 
-        public override void Draw(IImageProcessingContext graphics, EventRenderingOptions options)
+        /// <summary>
+        /// Sets a normalised value for the chirp's track score.
+        /// NOTE: It is assumed that the minimum value of the score range = zero.
+        /// </summary>
+        /// <param name="maxScore">The max score value which sets the scale.</param>
+        public void SetTrackScore(double maxScore)
         {
-            // foreach (var track in tracks) {
-            // track.Draw(...)
-            // }
+            this.Score = this.Tracks[0].GetAverageTrackAmplitude() / maxScore;
+        }
 
+        public override void Draw(IImageProcessingContext graphics, EventRenderingOptions options)
+        {
             this.Tracks.First().Draw(graphics, options);
 
             //  base drawing (border)

src/AudioAnalysisTools/StandardSpectrograms/SpectrogramTools.cs

@@ -82,7 +82,9 @@ public static Image<Rgb24> GetSonogramPlusCharts(
                 foreach (SpectralEvent ev in events)
                 {
                     var options = new EventRenderingOptions(new UnitConverters(segmentStartTime.TotalSeconds, segmentDuration.TotalSeconds, nyquist, width, height));
-                    spectrogram.Mutate(x => ev.Draw(x, options));
+
+                    //spectrogram.Mutate(x => ev.Draw(x, options));
+                    spectrogram.Mutate(x => ev.DrawWithAnnotation(x, options));
                 }
             }
 

src/AudioAnalysisTools/Tracks/ForwardTrackParameters.cs

@@ -27,8 +27,19 @@ public class ForwardTrackParameters : CommonParameters
         /// </summary>
         public bool CombinePossibleHarmonics { get; set; }
 
-        public TimeSpan StartDifference { get; set; }
+        public TimeSpan HarmonicsStartDifference { get; set; }
 
-        public int HertzGap { get; set; }
-}
+        public int HarmonicsHertzGap { get; set; }
+
+        /// <summary>
+        /// Gets or sets a value indicating whether a short sequence of chirp tracks are to be considered a combined event.
+        /// To qualify for combining, the event start times should not be greater than the specified seconds interval....
+        /// AND the difference in minimum frequency values (the Hertz gap) between consecutive tracks should not exceed the specified Hertz interval.
+        /// </summary>
+        public bool CombinePossibleChirpSequence { get; set; }
+
+        public TimeSpan ChirpStartDifference { get; set; }
+
+        public int ChirpHertzGap { get; set; }
+    }
 }

src/AudioAnalysisTools/Tracks/Track.cs

@@ -192,7 +192,6 @@ public double[] GetTrackFrequencyProfile()
 
         /// <summary>
         /// Returns the maximum amplitude in each time frame.
-        /// TODO ############################################
         /// </summary>
         public double[] GetAmplitudeOverTimeFrames()
         {
@@ -210,6 +209,21 @@ public double[] GetAmplitudeOverTimeFrames()
             return sorted;
         }
 
+        /// <summary>
+        /// Returns the maximum amplitude in each time frame.
+        /// </summary>
+        public double GetAverageTrackAmplitude()
+        {
+            var sum = 0.0;
+            foreach (var point in this.Points)
+            {
+                sum += point.Value;
+            }
+
+            var av = sum / this.Points.Count;
+            return av;
+        }
+
         /// <summary>
         /// Draws the track on an image given by its processing context.
         /// </summary>

src/AudioAnalysisTools/Tracks/TrackExtractor.cs

@@ -412,7 +412,7 @@ public static Track GetOneFrameTrack(double[,] peaks, int startRow, int startBin
         }
 
         /// <summary>
-        /// This method returns foward (spectral peak) tracks enclosed in acoustic events.
+        /// This method returns foward (spectral peak) tracks enclosed in spectral events.
         /// It averages dB log values incorrectly but it is faster than doing many log conversions.
         /// </summary>
         /// <param name="sonogram">The spectrogram to be searched.</param>
@@ -429,6 +429,7 @@ public static (List<EventCommon> Events, double[] CombinedIntensity) GetForwardT
             double binWidth = nyquist / (double)binCount;
             int minBin = (int)Math.Round(parameters.MinHertz.Value / binWidth);
             int maxBin = (int)Math.Round(parameters.MaxHertz.Value / binWidth);
+            double maxScore = parameters.MaxScore.Value;
 
             var converter = new UnitConverters(
                 segmentStartOffset: segmentStartOffset.TotalSeconds,
@@ -464,7 +465,7 @@ public static (List<EventCommon> Events, double[] CombinedIntensity) GetForwardT
             var combinedIntensityArray = new double[frameCount];
             foreach (var track in tracks)
             {
-                var ae = new ChirpEvent(track)
+                var ae = new ChirpEvent(track, maxScore)
                 {
                     SegmentDurationSeconds = frameCount * converter.StepSize,
                 };

tests/Acoustics.Test/AnalysisPrograms/Recognizers/GenericRecognizer/GenericRecognizerTests.cs

@@ -402,6 +402,7 @@ public void TestForwardTrackAlgorithm()
                 MinDuration = 0.2,
                 MaxDuration = 1.1,
                 DecibelThreshold = 2.0,
+                MaxScore = 12.0,
                 CombinePossibleHarmonics = false,
             };