comparison equalLoudness.py @ 10:c5e7162fb8ea

* A bit of commenting

 dArray = np.array([8, 16, 32, 64, 128, 256, 512, 1024])/1000.0
 
 def get_elc_range(xtol=0.0000005, verbose=False):
     """
         Plot the prediction of the equal loudness contours of frequencies for a range of SPL levels from 10 to 120dB, intervals of 10dB.
+        
+        Parameters:
+            * xtol (type: float) - x tolerance of fsolve
+            * verbose (type: boolean) - I tell you what I know
+        
+        Returns:
+            * elc (type: numpy array of floats) - SPL at which each frequency in fArray is equal to i*10 phons, where i is the first dimension index
+        
         """
     levels = range(20, 100, 20)
     elc = np.zeros((len(levels), len(fArray)))
     
     for i in range(len(levels)):

     return elc
 
 def get_elc(SPL = 90, xtol=0.0000005, verbose=False):
     """
         Plot the prediction of the equal loudness contours for specified level.
+        
+        Parameters:
+        * SPL (type: float) - SPL of the reference, or the loudness level
+        * xtol (type: float) - x tolerance of fsolve
+        * verbose (type: boolean) - I tell you what I know if you give me True
+        
+        Returns:
+        * elc (type: numpy array of floats) - SPL at which each frequency in fArray is equal to SPL phons
         """
     fs = 44100
     t = np.array(range(44100))
     elc = np.zeros((len(fArray)))
     env = get_cos2_env(44100, fs)

 
     return elc
 
 def get_temporal_descrimination(verbose=False):
     """
-        Return the prediction of STL and peak of STL for tones with short durations.
+        Return the prediction of STL and peak of STL for tones with short duration.
+        
+        Parameters
+        * verbose (type: boolean) - I tell you what I know if you give me True
+        
+        Returns:
+            * STLMax (type: array-like of floats) - peak short term loudness for each duration
+            * STL (type: array-like of floats) - short term loudness function for each duration
         """
 
 
     fs = 44100
     STLMax = np.zeros((len(dArray)))

         Parameters:
         * input (type: array-like of floats) - input signal
         * fs (type: int) - sampling frequency
         * SPL (type: float) - the level to start searching at
         * xtol (type: float) - x tolerance of fsolve
-        * verbose (type: boolean) - tell me everything I need to know
+        * verbose (type: boolean) - I tell you what I know if you give me True
+        
+        Returns:
+            x (type: float) - sound pressure level at equal loudness
         """
     
     x = opt.fsolve(getLoudnessDifference, SPL, (input, fs, refL, verbose), factor=0.1, xtol=xtol)
     
     return x

         
         Parameters:
         * SPL (type: float) - the level to set input to
         * input (type: array-like of floats) - input signal
         * fs (type: int) - sampling frequency
+        
+        Returns:
+            difference (type: float) - difference in loudness
         """
     if(verbose):
         print "SPL: ", SPL
     input = input/rms(input)
     compLoudness = pp.calc_loudness_quiet(input, fs, SPL, rectify=False, inc_loud_region=True)[2].max()

     return difference
 
 def rms(input):
     """
         RMS of the input
+        
+        Parameters:
+        * input (type: array-like of floats): input array
+        
+        Returns:
+        * output (type: float): the rms
         """
-    output = np.sqrt(np.mean(input**2))
+    output = np.sqrt(np.mean(input**2, -1))
 
     return output
 
-def plot_elc(ppOut, show = True):
+def plot_elc(elc, show = True):
     """
         Plot an equal loudness contour
+        
+        Parameters:
+            * elc (type: array-like of floats) - equal loudness contour x, obtained from get_elc
+            * show (type: boolean) - show the figure or turn hold on
         """
     plt.gca().set_xscale('log')
     plt.ylim((0,170))
-    plt.plot(fArray, ppOut, 'x-')
+    plt.plot(fArray, elc, 'x-')
     if(show):
         plt.show()
     else:
         plt.hold(True)