Fix problem ACI value in top freq bin

Issue #186 - Fix problem with the ACI value in the top most freq bin. Explanation is given where the code has been changed. This change may cause unit tests to fail that depend on the ACI value in top freq bin.

src/AudioAnalysisTools/AcousticComplexityIndex.cs

@@ -1,33 +1,32 @@
-// <copyright file="AcousticComplexityIndex.cs" company="QutEcoacoustics">
-// All code in this file and all associated files are the copyright and property of the QUT Ecoacoustics Research Group (formerly MQUTeR, and formerly QUT Bioacoustics Research Group).
+// <copyright file="AcousticComplexityIndex.cs" company="QutEcoacoustics">
+// All code in this file and all associated files are the copyright and property of the QUT Ecoacoustics Research Group (formerly MQUTeR, and formerly QUT Bio-acoustics Research Group).
 // </copyright>
 
 namespace AudioAnalysisTools
 {
     using System;
-    using System.Collections.Generic;
-    using System.Linq;
-    using System.Text;
 
     public static class AcousticComplexityIndex
     {
         /// <summary>
         /// Returns an array of ACOUSTIC COMPLEXITY INDICES
-        /// This implements the index of N. Pieretti, A. Farina, D. Morri
+        /// This implements the index of N. Pieretti, A. Farina, D. Morri.
         /// in "A new methodology to infer the singing activity of an avian community: The Acoustic Complexity Index (ACI)"
-        /// in Ecological Indicators 11 (2011) pp868–873
+        /// in Ecological Indicators 11 (2011) pp868–873.
         /// </summary>
-        /// <param name="spectrogram">this is an amplitude spectrum.</param>
-        /// <returns></returns>
-        public static double[] CalculateACI(double[,] spectrogram)
+        /// <param name="spectrogram">this is an AMPLITUDE spectrum. All its values are positive.</param>
+        /// <returns>array of ACI values.</returns>
+        public static double[] CalculateAci(double[,] spectrogram)
         {
             int frameCount = spectrogram.GetLength(0);
             int freqBinCount = spectrogram.GetLength(1);
             double[] aciArray = new double[freqBinCount];      // array of acoustic complexity indices, one for each freq bin
-            for (int j = 0; j < freqBinCount; j++) // for all frequency bins
+
+            // for all frequency bins
+            for (int j = 0; j < freqBinCount; j++)
             {
-                var deltaI = 0.0;          //  to accumlate sum of differences
-                var sumI = 0.0;
+                var deltaI = 0.0; //  to accumulate sum of differences
+                var sumI = 0.0;   //  to accumulate sum
                 for (int r = 0; r < frameCount - 1; r++)
                 {
                     sumI += spectrogram[r, j];
@@ -36,14 +35,19 @@ public static double[] CalculateACI(double[,] spectrogram)
 
                 if (sumI > 0.0)
                 {
-                    aciArray[j] = deltaI / sumI;      //store normalised ACI value
+                    aciArray[j] = deltaI / sumI; //store normalised ACI value
                 }
             }
 
-            //DataTools.writeBarGraph(aciArray);
+            // LDFC spectrograms that include the ACI index show a red line in top most freq bin.
+            // For some reason, the ACI values in the topmost freq bin sit around 0.8 which is double the value one would expect.
+            // Divide this value by 2 in order to bring it down to expected level.
+            // This is a hack! The issue needs further investigation - one day! Possibly due to problem in the passed amplitude spectrogram.
+            aciArray[freqBinCount - 1] /= 2;
 
+            //DataTools.writeBarGraph(aciArray);
             return aciArray;
-        } // AcousticComplexityIndex()
+        }
 
         /// <summary>
         /// Returns an array of DIFFERENCE values used in top line of calculation of ACOUSTIC COMPLEXITY INDICES
@@ -53,20 +57,22 @@ public static double[] CalculateACI(double[,] spectrogram)
         ///       but the sum of DIFFERENCES will be over one less value.
         ///       WHen ACI is calculated over a long interval i.e. one minute this is not a problem. When calculated over 0.2s, need to compensate.
         ///       To get an almost correct approx to the ACI value calculated over a long interval, we add the average DIF to the total DIFF.
-        ///       So the number of difference values equals the number of freq bin values, when it cons to calculate ACI = DIFF / SUM
-        ///       This problem arises because of the very short sement duration e.g. 0.2 s segment = 8-9 frames.
+        ///       So the number of difference values equals the number of freq bin values, when it comes to calculate ACI = DIFF / SUM
+        ///       This problem arises because of the very short segment duration e.g. 0.2 s segment = 8-9 frames.
         /// </summary>
         /// <param name="spectrogram">this is an amplitude spectrum.</param>
-        /// <returns></returns>
+        /// <returns>an array of DIFFERENCE values.</returns>
         public static double[] SumOfAmplitudeDifferences(double[,] spectrogram)
         {
             int frameCount = spectrogram.GetLength(0);
             int deltaCount = frameCount - 1;
             int freqBinCount = spectrogram.GetLength(1);
             double[] differenceArray = new double[freqBinCount];  // array of difference values, one for each freq bin
-            for (int j = 0; j < freqBinCount; j++) // for all frequency bins
+
+            // for all frequency bins
+            for (int j = 0; j < freqBinCount; j++)
             {
-                double deltaI = 0.0; // to accumlate sum of differences
+                double deltaI = 0.0; // to accumulate sum of differences
                 for (int r = 0; r < frameCount - 1; r++)
                 {
                     deltaI += Math.Abs(spectrogram[r, j] - spectrogram[r + 1, j]);
@@ -76,6 +82,6 @@ public static double[] SumOfAmplitudeDifferences(double[,] spectrogram)
             }
 
             return differenceArray;
-        } // SumDifferences()
+        }
     }
 }

src/AudioAnalysisTools/Indices/IndexCalculate.cs

@@ -337,7 +337,7 @@ public static IndexCalculateResult Analysis(
             // ii: CALCULATE THE ACOUSTIC COMPLEXITY INDEX
             spectralIndices.DIF = AcousticComplexityIndex.SumOfAmplitudeDifferences(amplitudeSpectrogram);
 
-            double[] aciSpectrum = AcousticComplexityIndex.CalculateACI(amplitudeSpectrogram);
+            double[] aciSpectrum = AcousticComplexityIndex.CalculateAci(amplitudeSpectrogram);
             spectralIndices.ACI = aciSpectrum;
 
             // remove low freq band of ACI spectrum and store average ACI value

src/AudioAnalysisTools/Indices/RainIndices.cs

@@ -183,7 +183,7 @@ public static RainStruct Get10SecondIndices(double[] signal, double[,] spectrogr
             }
 
             // iv: CALCULATE Acoustic Complexity Index on the AMPLITUDE SPECTRUM
-            var aciArray = AcousticComplexityIndex.CalculateACI(midbandSpectrogram);
+            var aciArray = AcousticComplexityIndex.CalculateAci(midbandSpectrogram);
             rainIndices.ACI = aciArray.Average();
 
             //v: remove background noise from the spectrogram