Fixing percentile nomenclature issue

- what we compute as statistics here from a time vector is not the percentile value, but rather the value exceeded during x-percent of the time. This nomenclature was fixed. - In the future, it would be very handy to have one universal function to compute the statistics of all metrics. This should be easy to do without compromising the backwards compatibility of the software - the name of the function <get_percentile> is kept to not compromise backwards compatibility of the toolbox. Nevertheless, it is not a correct nomenclature !!!!!!
ggrecow · Jan 10, 2025 · 1368160 · 1368160
1 parent 073c829
commit 1368160
Show file tree

Hide file tree

Showing 18 changed files with 35 additions and 33 deletions.
diff --git a/psychoacoustic_metrics/FluctuationStrength_Osses2016/FluctuationStrength_Osses2016.m b/psychoacoustic_metrics/FluctuationStrength_Osses2016/FluctuationStrength_Osses2016.m
@@ -66,8 +66,7 @@
 %              (vacil)
 %         ** FSmax : maximum of InstantaneousFluctuationStrength (vacil)
 %         ** FSmin : minimum of InstantaneousFluctuationStrength (vacil)
-%         ** FSx : percentile fluctuation strength exceeded during x percent
-%              of the signal (vacil)
+%         ** FSx : fluctuation strength value exceeded during x percent of the time (vacil)
 %
 % Original file name: FluctuationStrength_TUe.m from 
 %   https://github.com/aosses-tue/mb/tree/master/FluctuationStrength_TUe (accessed 04/03/2020)

diff --git a/...oustic_metrics/FluctuationStrength_Osses2016/FluctuationStrength_Osses2016_from_wavfile.m b/...oustic_metrics/FluctuationStrength_Osses2016/FluctuationStrength_Osses2016_from_wavfile.m
@@ -57,8 +57,7 @@
 %              (vacil)
 %         ** FSmax : maximum of InstantaneousFluctuationStrength (vacil)
 %         ** FSmin : minimum of InstantaneousFluctuationStrength (vacil)
-%         ** FSx : percentile fluctuation strength exceeded during x percent
-%              of the signal (vacil)
+%         ** FSx : fluctuation strength exceeded during x percent of the time (vacil)
 %
 % Stand-alone example:
 %   fname = [basepath_SQAT 'sound_files' filesep 'reference_signals' filesep 'RefSignal_FluctuationStrength_Osses2016.wav'];

diff --git a/psychoacoustic_metrics/Loudness_ISO532_1/Loudness_ISO532_1.m b/psychoacoustic_metrics/Loudness_ISO532_1/Loudness_ISO532_1.m
@@ -57,8 +57,9 @@
 %         ** Nstd : standard deviation of InstantaneousLoudness (sone)
 %         ** Nmax : maximum of InstantaneousLoudness (sone)
 %         ** Nmin : minimum of InstantaneousLoudness (sone)
-%         ** Nx : percentile loudness exceeded during x percent of the signal (sone)
+%         ** Nx : loudness value exceeded during x percent of the time (sone)
 %         ** N_ratio : ratio between N5/N95 ( 1.1 (stationary)> N_ratio > 1.1 (time varying) )
+%
 %           *** HINT: loudness calculation takes some time to have a steady-response
 %                     therefore, it is a good practice to consider a time_skip to compute the statistics
 %                     due to transient effects in the beginning of the loudness calculations

diff --git a/psychoacoustic_metrics/Loudness_ISO532_1/Loudness_ISO532_1_from_wavfile.m b/psychoacoustic_metrics/Loudness_ISO532_1/Loudness_ISO532_1_from_wavfile.m
@@ -63,9 +63,10 @@
 %         ** Nstd : standard deviation of InstantaneousLoudness (sone)
 %         ** Nmax : maximum of InstantaneousLoudness (sone)
 %         ** Nmin : minimum of InstantaneousLoudness (sone)
-%         ** Nx : percentile loudness exceeded during x percent of the signal (sone)
+%         ** Nx : loudness value exceeded during x percent of the time (sone)
 %         ** N_ratio : ratio between N5/N95 ( 1.1 (stationary)> N_ratio > 1.1 (time varying) )
-%           *** HINT: loudness calculation takes some time to have a steady-response
+%
+%           *** HINT: loudness calculation takes some time to have a steady-response%
 %                     therefore, it is a good practice to consider a time_skip to compute the statistics 
 %                     due to transient effects in the beginning of the loudness calculations
 %

diff --git a/psychoacoustic_metrics/PsychoacousticAnnoyance_Di2016/PsychoacousticAnnoyance_Di2016.m b/psychoacoustic_metrics/PsychoacousticAnnoyance_Di2016/PsychoacousticAnnoyance_Di2016.m
@@ -72,7 +72,7 @@
 %               *** PAstd : standard deviation of instantaneous psychoacoustic annoyance (unit)
 %               *** PAmax : maximum of instantaneous psychoacoustic annoyance (unit)
 %               *** PAmin : minimum of instantaneous psychoacoustic annoyance (unit)
-%               *** PAx : x percentile of the PA metric exceeded during x percent of the time
+%               *** PAx : value exceeded x percent of the time
 %
 %      * include structs with the results from the other metrics computed
 %        **  L : struct with Loudness results, type <help Loudness_ISO532_1>

diff --git a/...stic_metrics/PsychoacousticAnnoyance_Di2016/PsychoacousticAnnoyance_Di2016_from_wavfile.m b/...stic_metrics/PsychoacousticAnnoyance_Di2016/PsychoacousticAnnoyance_Di2016_from_wavfile.m
@@ -81,7 +81,7 @@
 %               *** PAstd : standard deviation of instantaneous psychoacoustic annoyance (unit)
 %               *** PAmax : maximum of instantaneous psychoacoustic annoyance (unit)
 %               *** PAmin : minimum of instantaneous psychoacoustic annoyance (unit)
-%               *** PAx : x percentile of the PA metric exceeded during x percent of the time
+%               *** PAx : value exceeded x percent of the time
 %
 %      * include structs with the results from the other metrics computed
 %        **  L : struct with Loudness results, type <help Loudness_ISO532_1>

diff --git a/psychoacoustic_metrics/PsychoacousticAnnoyance_More2010/PsychoacousticAnnoyance_More2010.m b/psychoacoustic_metrics/PsychoacousticAnnoyance_More2010/PsychoacousticAnnoyance_More2010.m
@@ -67,7 +67,7 @@
 %               *** PAstd : standard deviation of instantaneous psychoacoustic annoyance (unit)
 %               *** PAmax : maximum of instantaneous psychoacoustic annoyance (unit)
 %               *** PAmin : minimum of instantaneous psychoacoustic annoyance (unit)
-%               *** PAx : x percentile of the PA metric exceeded during x percent of the time
+%               *** PAx : value exceeded x percent of the time
 %
 %      * include structs with the results from the other metrics computed
 %        **  L : struct with Loudness results, type <help Loudness_ISO532_1> for more info

diff --git a/..._metrics/PsychoacousticAnnoyance_More2010/PsychoacousticAnnoyance_More2010_from_wavfile.m b/..._metrics/PsychoacousticAnnoyance_More2010/PsychoacousticAnnoyance_More2010_from_wavfile.m
@@ -75,7 +75,7 @@
 %               *** PAstd : standard deviation of instantaneous psychoacoustic annoyance (unit)
 %               *** PAmax : maximum of instantaneous psychoacoustic annoyance (unit)
 %               *** PAmin : minimum of instantaneous psychoacoustic annoyance (unit)
-%               *** PAx : x percentile of the PA metric exceeded during x percent of the time
+%               *** PAx : value exceeded x percent of the time
 %
 %      * include structs with the results from the other metrics computed
 %        **  L : struct with Loudness results, type <help Loudness_ISO532_1> for more info

diff --git a/...coustic_metrics/PsychoacousticAnnoyance_Zwicker1999/PsychoacousticAnnoyance_Zwicker1999.m b/...coustic_metrics/PsychoacousticAnnoyance_Zwicker1999/PsychoacousticAnnoyance_Zwicker1999.m
@@ -61,7 +61,7 @@
 %               *** PAstd : standard deviation of instantaneous psychoacoustic annoyance (unit)
 %               *** PAmax : maximum of instantaneous psychoacoustic annoyance (unit)
 %               *** PAmin : minimum of instantaneous psychoacoustic annoyance (unit)
-%               *** PAx : x percentile of the PA metric exceeded during x percent of the time
+%               *** PAx : value exceeded x percent of the time
 %
 %      * include structs with the results from the other metrics computed
 %        **  L : struct with Loudness results, type <help Loudness_ISO532_1> for more info

diff --git a/...cs/PsychoacousticAnnoyance_Zwicker1999/PsychoacousticAnnoyance_Zwicker1999_from_wavfile.m b/...cs/PsychoacousticAnnoyance_Zwicker1999/PsychoacousticAnnoyance_Zwicker1999_from_wavfile.m
@@ -71,7 +71,7 @@
 %               *** PAstd : standard deviation of instantaneous psychoacoustic annoyance (unit)
 %               *** PAmax : maximum of instantaneous psychoacoustic annoyance (unit)
 %               *** PAmin : minimum of instantaneous psychoacoustic annoyance (unit)
-%               *** PAx : x percentile of the PA metric exceeded during x percent of the time
+%               *** PAx : value exceeded x percent of the time
 %
 %      * include structs with the results from the other metrics computed
 %        **  L : struct with Loudness results, type <help Loudness_ISO532_1> for more info

diff --git a/psychoacoustic_metrics/Roughness_Daniel1997/Roughness_Daniel1997.m b/psychoacoustic_metrics/Roughness_Daniel1997/Roughness_Daniel1997.m
@@ -41,7 +41,7 @@
 %         ** Rstd : standard deviation of instantaneous roughness (asper)
 %         ** Rmax : maximum of instantaneous roughness (asper)
 %         ** Rmin : minimum of instantaneous roughness (asper)
-%         ** Rx : percentile roughness exceeded during x percent of the signal (asper)
+%         ** Rx : roughness value exceeded during x percent of the time (asper)
 %
 % Original file name: roughnessDW.m obtained from 
 %   https://github.com/densilcabrera/aarae/ (accessed 11/02/2020)

diff --git a/psychoacoustic_metrics/Roughness_Daniel1997/Roughness_Daniel1997_from_wavfile.m b/psychoacoustic_metrics/Roughness_Daniel1997/Roughness_Daniel1997_from_wavfile.m
@@ -49,7 +49,7 @@
 %         ** Rstd : standard deviation of instantaneous roughness (asper)
 %         ** Rmax : maximum of instantaneous roughness (asper)
 %         ** Rmin : minimum of instantaneous roughness (asper)
-%         ** Rx : percentile roughness exceeded during x percent of the signal (asper)
+%         ** Rx : roughness value exceeded during x percent of the time (asper)
 %
 % Stand-alone example:
 %   fname = [basepath_SQAT 'sound_files' filesep 'reference_signals' filesep 'RefSignal_Roughness_Daniel1997.wav'];

diff --git a/psychoacoustic_metrics/Sharpness_DIN45692/Sharpness_DIN45692.m b/psychoacoustic_metrics/Sharpness_DIN45692/Sharpness_DIN45692.m
@@ -60,7 +60,8 @@
 %         ** Sstd : standard deviation of InstantaneousSharpness (acum)
 %         ** Smax : maximum of InstantaneousSharpness (acum)
 %         ** Smin : minimum of InstantaneousSharpness (acum)
-%         ** Sx : percentile sharpness exceeded during x percent of the signal (acum)
+%         ** Sx : sharpness value exceeded during x percent of the time (acum)
+%
 %           *** HINT: time-varying loudness calculation takes some time to
 %                     have a steady-response (thus sharpness too!).
 %                     Therefore, it is a good practice to consider a 

diff --git a/psychoacoustic_metrics/Sharpness_DIN45692/Sharpness_DIN45692_from_loudness.m b/psychoacoustic_metrics/Sharpness_DIN45692/Sharpness_DIN45692_from_loudness.m
@@ -44,7 +44,8 @@
 %         ** Sstd : standard deviation of InstantaneousSharpness (acum)
 %         ** Smax : maximum of InstantaneousSharpness (acum)
 %         ** Smin : minimum of InstantaneousSharpness (acum)
-%         ** Sx : percentile sharpness exceeded during x percent of the signal (acum)
+%         ** Sx : sharpness value exceeded during x percent of the time (acum)
+%
 %           *** HINT: time-varying loudness calculation takes some time to
 %                     have a steady-response (thus sharpness too!). 
 %                     Therefore, it is a good practice to consider a 
@@ -118,7 +119,7 @@
     % statistics from Time-varying sharpness (acum)
 
     [~,idx] = min( abs(OUT.time-time_skip) ); % find idx of time_skip on time vector
-    
+
     OUT.Smax = max(s(idx:end));
     OUT.Smin = min(s(idx:end));
     OUT.Smean = mean(s(idx:end));

diff --git a/psychoacoustic_metrics/Sharpness_DIN45692/Sharpness_DIN45692_from_wavfile.m b/psychoacoustic_metrics/Sharpness_DIN45692/Sharpness_DIN45692_from_wavfile.m
@@ -66,7 +66,8 @@
 %         ** Sstd : standard deviation of InstantaneousSharpness (acum)
 %         ** Smax : maximum of InstantaneousSharpness (acum)
 %         ** Smin : minimum of InstantaneousSharpness (acum)
-%         ** Sx : percentile sharpness exceeded during x percent of the signal (acum)
+%         ** Sx : sharpness value exceeded during x percent of the time (acum)
+%
 %           *** HINT: time-varying loudness calculation takes some time to
 %                     have a steady-response (thus sharpness too!). 
 %                     Therefore, it is a good practice to consider a 

diff --git a/psychoacoustic_metrics/Tonality_Aures1985/Tonality_Aures1985.m b/psychoacoustic_metrics/Tonality_Aures1985/Tonality_Aures1985.m
@@ -48,7 +48,7 @@
 %         ** Kstd : standard deviation of InstantaneousTonality (t.u.)
 %         ** Kmax : maximum of InstantaneousTonality (t.u.)
 %         ** Kmin : minimum of InstantaneousTonality (t.u.)
-%         ** Kx : percentile InstantaneousTonality exceeded during x percent of the signal (t.u.)
+%         ** Kx : Tonality value exceeded during x percent of the time (t.u.)
 %
 % Author: Gil Felix Greco, Braunschweig 13/07/2020 (updated 14.04.2023)
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

diff --git a/psychoacoustic_metrics/Tonality_Aures1985/Tonality_Aures1985_from_wavfile.m b/psychoacoustic_metrics/Tonality_Aures1985/Tonality_Aures1985_from_wavfile.m
@@ -56,7 +56,7 @@
 %         ** Kstd : standard deviation of InstantaneousTonality (t.u.)
 %         ** Kmax : maximum of InstantaneousTonality (t.u.)
 %         ** Kmin : minimum of InstantaneousTonality (t.u.)
-%         ** Kx : percentile InstantaneousTonality exceeded during x percent of the signal (t.u.)
+%         ** Kx : Tonality value exceeded during x percent of the time (t.u.)
 %
 % Stand-alone example:
 %   fname = [basepath_SQAT 'sound_files' filesep 'reference_signals' filesep 'RefSignal_Tonality_Aures1985.wav'];

diff --git a/utilities/get_percentile.m b/utilities/get_percentile.m
@@ -1,29 +1,28 @@
-function OUT = get_percentile(input,PercentileValue)
+function OUT = get_percentile(input, PercentValue)
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %
-% Calculate the value exceeded in a desired percentile % from the entire
-% input signal
+% Calculate the value exceeded  during <PercentValue> of the time 
 %
 % INPUT:
-%   PercentileValue: desired percentile value exceeded during nSamples
-%   insig: vector containing values to be evaluated
+%   PercentValue: desired % value exceeded during nSamples
+%   input: vector containing values to be evaluated (typically a time vector)
 %
 % OUTPUT:
-%   OUT: percentile value
+%   OUT: value exceeded  during <PercentValue> of the time
 %
 % Standalone example:%
-% compute the percentiles from a gaussian function 
+% compute the percentiles from a gaussian function, where x-axis is considered to be increasing time  
 %   x = 0:0.1:10;
 %   y = gaussmf(x,[2 5]);
 %   plot(x,y); hold on;
-%   P5=get_percentile(y,5); % 5% percentile
-%   yline(p5);
-%   p90=get_percentile(y,90); % 90% percentile
-%   yline(p90);
+%   P5=get_percentile(y,5); % value exceed 5% of the time 
+%   yline(P5);
+%   P90=get_percentile(y,90); % value exceed 90% of the time 
+%   yline(P90);
 %
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-X_index = floor( (100-PercentileValue)/100 * length(input) );
+X_index = floor( (100-PercentValue)/100 * length(input) );
 
 if X_index==0
     X_index=1;