fixed RMS contrast + added documentation

setup.py

@@ -6,7 +6,7 @@
     setuptools.setup(
         name='stimuli',
         description='Library for creating different visual stimuli for psychophysic experiments',
-        version='0.6',
+        version='0.7',
         author='Guillermo Aguilar',
         author_email='guillermo.aguilar@mail.tu-berlin.de',
         license='GPL2',

src/README.md

@@ -116,13 +116,18 @@ cm.SAM(img, mask=(mask==1), mode="unique")
 Available Metrics:
 - SAM: Space Average Michelson Contrast
 - SAMLG: SAM of log luminances
-- SDMC: Standard Deviation of pair-wise Michelson Contrasts
+- SDMC: Standard Deviation of Michelson Contrasts between all pairs of values
 - SAW: Space Average Whittle Contrast
 - SAWLG: SAW of log luminances
-- RMS: Root Mean Sqaure Contrast
 - SD: Standard Deviation of luminances
 - SDLG: SD of log luminances
+- RMS: RMS Contrast, defined as standard_deviation(luminances)/mean(luminances)
 
+Definitions:
+- Michelson Contrast between values a and b: |(a-b)/(a+b)|
+- Whittle Contrast between values a and b: |(a-b)/min(a,b)|
+- Space Average Contrast: mean of contrasts between all pairs of values
+- Log luminances: contrast is computed on log_10(luminances)
 
 # Utils
 Helper functions for padding, resizing, computing Munsell values, and

src/contrast_metrics.py

@@ -170,7 +170,7 @@ def SAWLG(arr, mask=None, mode="unique"):
 
 def RMS(arr, mask=None, mode="complete"):
     """
-    Root mean square of values in arr.
+    RMS contrast, defined as standard_deviation(arr) / mean(arr.)
 
     Parameters
     ----------
@@ -187,7 +187,7 @@ def RMS(arr, mask=None, mode="complete"):
     contrast : float
     """
     arr = preprocess_arr(arr, mask, mode)
-    return np.sqrt(np.mean(arr**2))
+    return np.std(arr) / np.mean(arr)
 
 
 def SD(arr, mask=None, mode="complete"):

test_contrast_metrics.py

@@ -31,15 +31,11 @@
 assert(y==0.5)
 assert(z==0.5)
 
-# TODO: RMS is not returning correct value
 arr = np.vstack((np.ones(s), np.zeros(s)))
 y = cm.RMS(arr, mode="complete")
 z = cm.RMS(arr, mode="unique")
-# assert(y==1.0)
-# assert(z==1.0)
-
-print(cm.SD(arr)/arr.mean())
-
+assert(y==1.0)
+assert(z==1.0)
 
 # %%
 arr = np.random.randint(1, 10, (10, 10))