added docstrings and updated READMEs

computational-psychology · Aug 19, 2021 · 3d47a1d · 3d47a1d
1 parent e1226ad
commit 3d47a1d
Show file tree

Hide file tree

Showing 16 changed files with 448 additions and 138 deletions.
diff --git a/README.md b/README.md
@@ -1,16 +1,16 @@
 # Stimuli
 
 Contains submodules for
-- creating different stimuli used in lightness perception ([lightness](src/lightness/README.md))
-- creating different brightness illusions ([illusions](src/illusions/README.md))
+- creating different brightness illusions ([illusions](stimuli/illusions/))
+- replicating illusions in certain published papers  ([papers](stimuli/papers/))
 - creating 2D patterns or renderings of 3D checkerboards with transparent 
-layers covering part of the image ([transparency](src/transparency/README.md))
-- various functions that calculate contrast metrics ([contrast_metrics](src/contrest_metrics/README.md))
+layers covering part of the image ([transparency](stimuli/transparency/))
+- various functions that calculate contrast metrics ([contrast_metrics](stimuli/contrest_metrics/))
 - some helper functions for padding, resizing, computing Munsell values, and
-converting pixel values to degrees of visual angle ([utils](src/utils/README.md#utils))
-- (creating different random and deterministic textures ([texture](src/texture/README.md)) [yet to be fixed])
+converting pixel values to degrees of visual angle ([utils](stimuli/utils/))
+- (creating different random and deterministic textures ([texture](stimuli/texture/)) [yet to be fixed])
 
-For details, please refer to the source directory (src/), the respective subdirectories and the docstrings.
+For details, please refer to the source directory (stimuli/), the respective subdirectories and the docstrings.
 
 ## Dependencies
 - Required: numpy, matplotlib, PIL
@@ -34,7 +34,7 @@ This makes changes to files immediately usable,
 rather than having to reinstall the package after every change.
 
 ## Importing
-To use in your own code, import the modules. See READMEs in src/ for example usages.
+To use in your own code, import the modules. See READMEs in stimuli/ for example usages.
 ```python
 from stimuli import lightness
 from stimuli import illusions

diff --git a/stimuli/illusions/README.md b/stimuli/illusions/README.md
@@ -1,3 +1,20 @@
-## Brightness Illusions
+## Illusions
 
-For example usage, see `/tests/test_brightness_illusions.py`.
+This directory contains modules for creating various brightness illusions. 
+Each module contains a function to create the general version of the illusion with suitable default parameters.
+Beside that, in each module one can find the implementations of functions for generating illusions used in published papers.
+These functions are the one being called from the modules in `papers` directory.
+
+An overview of all illusions can be generated by running the `overview.py` module.
+Each functions returns a `Stimulus` object. `img` attribute contains a 2D numpy array
+representing the illusion and `target_mask` attribute contains an integer mask specifying
+the location of target patches inside the illusion.
+### Example usage
+```python
+from stimuli import illusions, utils
+import matplotlib.pyplot as plt
+
+stimulus = illusions.whites.white()
+utils.plot_stim(stimulus, mask=True)
+plt.show()
+```
diff --git a/stimuli/illusions/benary_cross.py b/stimuli/illusions/benary_cross.py
@@ -9,17 +9,26 @@ def benarys_cross(ppd=10, cross_size=(8,8,8,8), cross_thickness=5, padding=(1,1,
 
     Parameters
     ----------
-    cross_size: size of the cross in degrees visual angle in form (top, bottom, left, right) specifying the length of each of the cross' bars
-    cross_thickness: width of the cross bars in degrees visual angle
-    padding: 4-valued tuple specifying padding (top, bottom, left, right) in degrees visual angle
-    target_size: size of the side of target square in degrees visual angle
-    back: background value
-    cross: cross value
-    target: target value
+    ppd : int
+        pixels per degree (visual angle)
+    cross_size : (float, float, float, float)
+        size of the cross in degrees visual angle in form (top, bottom, left, right) specifying the length of each of the cross' bars
+    cross_thickness : float
+        width of the cross bars in degrees visual angle
+    padding : (float, float, float, float)
+        4-valued tuple specifying padding (top, bottom, left, right) in degrees visual angle
+    target_size : float
+        size of the side of target square in degrees visual angle
+    back : float
+        background value
+    cross : float
+        cross value
+    target : float
+        target value
 
     Returns
     -------
-    2D numpy array
+    A stimulus object
     """
 
 
@@ -58,6 +67,10 @@ def benarys_cross(ppd=10, cross_size=(8,8,8,8), cross_thickness=5, padding=(1,1,
     return stim
 
 def domijan2015():
+    """
+    Generates Benary Cross illusion as used in the Domijan 2015 paper.
+    """
+
     return illusions.benarys_cross(ppd=10, cross_size=(3,3,3,3), cross_thickness=2.1, padding=(.9,1.0,.9,1.0),target_size=1.1,  back=9., cross=1., target=5.)
 
 if __name__ == '__main__':

diff --git a/stimuli/illusions/bullseye.py b/stimuli/illusions/bullseye.py
@@ -11,16 +11,28 @@ def bullseye_illusion(ppd=10, n_rings=8, ring_width=.5, target_pos_l=0, target_p
 
     Parameters
     ----------
-    n_rings: the number of rings
-    ring_width: width per ring in px
-    padding: 4-valued tuple specifying padding (top, bottom, left, right) in px
-    back: value for background
-    rings: value for grid cells
-    target: value for target
+    ppd : int
+        pixels per degree (visual angle)
+    n_rings : int
+        the number of rings
+    ring_width : float
+        width per ring in degrees visual angle
+    target_pos_l : int
+        specify the target index in the left ring
+    target_pos_r : int
+        specify the target index in the right ring
+    padding : (float, float, float, float)
+        4-valued tuple specifying padding (top, bottom, left, right) in degrees visual angle
+    back : float
+        background value
+    rings : float
+        value for grid cells
+    target : float
+        value for target
 
     Returns
     -------
-    2D numpy array
+    A stimulus object
     """
     stim1 = ring_pattern(n_rings=n_rings, target_pos_l=target_pos_l, ring_width=ring_width, padding=padding,
                         back=back, rings=rings, target=target, invert_rings=False, double=False)
@@ -37,13 +49,24 @@ def bullseye_illusion(ppd=10, n_rings=8, ring_width=.5, target_pos_l=0, target_p
     return stim
 
 def domijan2015():
+    """
+    Generates Bullseye illusion as used in the Domijan 2015 paper.
+    """
+
     img =  illusions.bullseye_illusion(n_rings=8, ring_width=.5, target_pos_l=0, target_pos_r=0, padding=(.9,1.0,.9,1.0), back=1., rings=9., target=5.)
     return img
 
 def RHS2007_bullseye_thin():
+    """
+    Generates Bullseye thin illusion as used in the Robinson, Hammon and de Sa 2007 paper.
+    """
     return illusions.bullseye_illusion(n_rings=8, ring_width=1, padding=(100,100,100,100), back=1., rings=9., target=5.)
 
 def RHS2007_bullseye_thick():
+    """
+    Generates Bullseye thick illusion as used in the Robinson, Hammon and de Sa 2007 paper.
+    """
+
     return illusions.bullseye_illusion(n_rings=8, ring_width=1, padding=(50,50,50,50), back=1., rings=9., target=5.)
 
 if __name__ == '__main__':

diff --git a/stimuli/illusions/checkerboard_contrast_contrast.py b/stimuli/illusions/checkerboard_contrast_contrast.py
@@ -10,18 +10,28 @@ def checkerboard_contrast_contrast_effect(ppd=10, n_checks=8, check_size=1.0, ta
 
     Parameters
     ----------
-    n_checks: number of checks per board in each direction
-    check_size: size of a check in px
-    target_length: size of the target in # checks
-    padding: 4-valued tuple specifying padding (top, bottom, left, right) in px
-    check1: a check value
-    check2: other check value
-    tau: tau of transparency
-    alpha: alpha of transparency
+    ppd : int
+        pixels per degree (visual angle)
+    n_checks : int
+        number of checks per board in each direction
+    check_size : float
+        size of a check in degrees visual angle
+    target_length : int
+        size of the target in # checks
+    padding : (float, float, float, float)
+        4-valued tuple specifying padding (top, bottom, left, right) in degrees visual angle
+    check1 : float
+        first check value
+    check2 : float
+        other check value
+    tau : float
+        tau of transparency
+    alpha : float
+        alpha of transparency
 
     Returns
     -------
-    2D numpy array
+    A stimulus object
     """
 
     check_size_px = degrees_to_pixels(check_size, ppd)
@@ -71,6 +81,9 @@ def checkerboard_contrast_contrast_effect(ppd=10, n_checks=8, check_size=1.0, ta
 
 
 def domijan2015():
+    """
+    Generates checkerboard contrast contrast illusion as used in Domijan 2015 paper.
+    """
     return illusions.checkerboard_contrast_contrast_effect(ppd=10, n_checks=8, check_size=1.0, target_length=4, padding=(.9,1.1,.9,1.1), check1=1.,
                                                  check2=9., tau=5, alpha= .5)
 

diff --git a/stimuli/illusions/checkerboard_sbc.py b/stimuli/illusions/checkerboard_sbc.py
@@ -11,19 +11,30 @@ def checkerboard_contrast(ppd=10, board_shape=(8,8), check_size=1.0, target1_coo
 
     Parameters
     ----------
-    board shape: number of checks per board in y, x direction
-    check_size: size of a check in px
-    target1_coords: check-coordinates of target check 1
-    target2_coords: check-coordinates of target check 2
-    extend_targets: cross targets instead of single-check targets
-    padding: 4-valued tuple specifying padding (top, bottom, left, right) in px
-    check1: a check value
-    check2: other check value
-    target: target value
+    ppd : int
+        pixels per degree (visual angle)
+    board shape : (int, int)
+        number of checks per board in y, x direction
+    check_size : float
+        size of a check in degrees visual angle
+    target1_coords : (int, int)
+        check-coordinates of target check 1
+    target2_coords : (int, int)
+        check-coordinates of target check 2
+    extend_targets : bool
+        cross targets instead of single-check targets
+    padding : (float, float, float, float)
+        4-valued tuple specifying padding (top, bottom, left, right) in degrees visual angle
+    check1 : float
+        first check value
+    check2 : float
+        other check value
+    target: float
+        target value
 
     Returns
     -------
-
+    A stimulus object
     """
 
     check_size_px = degrees_to_pixels(check_size, ppd)
@@ -60,6 +71,9 @@ def checkerboard_contrast(ppd=10, board_shape=(8,8), check_size=1.0, target1_coo
 
 
 def domijan2015():
+    """
+    Generates checkerboard_sbc illusion as used in Domijan 2015 paper.
+    """
     stim = illusions.checkerboard_contrast(ppd=10, board_shape=(8,8), check_size=1.0, target1_coords=(3, 2), target2_coords=(5, 5), extend_targets=False, check1=1., check2=9., target=5.)
     padding = (.9, 1.1, .9, 1.1)
     stim.img = pad_img(stim.img, padding, ppd=10, val=5.)
@@ -68,6 +82,9 @@ def domijan2015():
 
 
 def domijan2015_extended():
+    """
+    Generates checkerboard_sbc extended illusion as used in Domijan 2015 paper.
+    """
     stim = illusions.checkerboard_contrast(ppd=10, board_shape=(8,8), check_size=1.0, target1_coords=(3, 2), target2_coords=(5, 5), extend_targets=True, check1=1., check2=9., target=5.)
     padding = (.9, 1.1, .9, 1.1)
     stim.img = pad_img(stim.img, padding, ppd=10, val=5.)
@@ -76,6 +93,9 @@ def domijan2015_extended():
 
 
 def RHS2007_Checkerboard016():
+    """
+    Generates checkerboard 0.16 illusion as used in Robinson, Hammon and de Sa 2007 paper.
+    """
     total_height, total_width, ppd = (32,) * 3
     height_checks, width_checks = 40, 102
     check_height = 32/102
@@ -93,6 +113,9 @@ def RHS2007_Checkerboard016():
 
 
 def RHS2007_Checkerboard0938():
+    """
+    Generates checkerboard 0.94 illusion as used in Robinson, Hammon and de Sa 2007 paper.
+    """
     total_height, total_width, ppd = (32,) * 3
     height_checks, width_checks = 7, 25
     check_height = 0.938
@@ -109,6 +132,9 @@ def RHS2007_Checkerboard0938():
 
 
 def RHS2007_Checkerboard209():
+    """
+    Generates checkerboard 2.1 illusion as used in Robinson, Hammon and de Sa 2007 paper.
+    """
     total_height, total_width, ppd = (32,) * 3
     height_checks, width_checks = 3, 10
     check_height = 2.09

diff --git a/stimuli/illusions/cube.py b/stimuli/illusions/cube.py
@@ -6,27 +6,43 @@
 def cube_illusion(ppd=10, n_cells=5, target_length=2, cell_long=1.5, cell_short=1.0, corner_cell_width=1.8, corner_cell_height=1.8,
                   cell_spacing=.5, padding=(1.0,1.0,1.0,1.0), occlusion_overlap=(.7,.7,.7,.7), back=0., grid=1., target=.5, double=True):
 
-
     """
     Cube illusion (Agostini & Galmonte, 2002)
 
     Parameters
     ----------
-    n_cells: the number of square cells (not counting background) per dimension
-    target_length: length in # cells per edge of the square
-    cell_long: long side of a cell in px
-    cell_short: short side of a cell in px
-    cell_spacing: distance between two cells in px
-    padding: 4-valued tuple specifying padding (top, bottom, left, right) in px
-    occlusion_overlap: 4-valued tuple specifying how many px the big central square overlaps the cells on (top, bottom, left, right
-    back: value for background
-    grid: value for grid cells
-    target: value for target
-    double: whether to return the full illusion with two grids side-by-side (inverting back and grid values)
+    ppd : int
+        pixels per degree (visual angle)
+    n_cells : int
+        the number of square cells (not counting background) per dimension
+    target_length : int
+        length in # cells per edge of the square
+    cell_long : float
+        long side of a cell in degrees visual angle
+    cell_short : float
+        short side of a cell in degrees visual angle
+    corner_cell_width : float
+        width of the corner cells in degrees visual angle
+    corner_cell_height: float
+        height of the corner cells in degrees visual angle
+    cell_spacing : float
+        distance between two cells in degrees visual angle
+    padding : (float, float, float, float)
+        4-valued tuple specifying padding (top, bottom, left, right) in degrees visual angle
+    occlusion_overlap : (float, float, float, float)
+        4-valued tuple specifying how much the big central square overlaps the cells on (top, bottom, left, right) in degrees visual angle
+    back : float
+        value for background
+    grid : float
+        value for grid cells
+    target : float
+        value for target
+    double : bool
+        whether to return the full illusion with two grids side-by-side (inverting back and grid values)
 
     Returns
     -------
-    2D numpy array
+    A stimulus object
     """
     cell_long_px, cell_short_px = degrees_to_pixels(cell_long, ppd), degrees_to_pixels(cell_short, ppd)
     corner_cell_width_px, corner_cell_height_px = degrees_to_pixels(corner_cell_width, ppd), degrees_to_pixels(corner_cell_height, ppd)

diff --git a/stimuli/illusions/disc_and_ring.py b/stimuli/illusions/disc_and_ring.py
@@ -7,7 +7,6 @@ def disc_and_ring(
     shape=(10, 10), radii=(4, 2), values=(0.5, 1), bg=0, ppd=30, ssf=5
 ):
     # TODO: the parameters aren't analogous to the other stimuli
-    # TODO: figure out defeault parameters that create something that makes sense
     """
     Create a disc and ring stimulus with an arbitrary number of rings.