closes #25; add original source to illusions

stimuli/illusions/angular.py

@@ -74,6 +74,12 @@ def radial_white(
         dict with the stimulus (key: "img"),
         mask with integer index for each target (key: "mask"),
         and additional keys containing stimulus parameters
+    
+    References
+    ----------
+    Robinson, A. E., Hammon, P. S., & de Sa, V. R. (2007). Explaining brightness
+        illusions using spatial filtering and local response normalization. Vision
+        research, 47(12), 1631-1644. https://doi.org/10.1016/j.visres.2007.02.017
     """
 
     # Radial grating

stimuli/illusions/benary_cross.py

@@ -59,6 +59,11 @@ def benarys_cross_generalized(
     Returns
     -------
     A stimulus dictionary with the stimulus ['img'] and target mask ['mask']
+    
+    References
+    -----------
+    Benary, W. (1924). Beobachtungen zu einem Experiment ueber Helligkeitskontrast.
+        Psychologische Forschung, 5, 131–142. https://doi.org/10.1007/BF00402398
     """
     if isinstance(visual_size, (float, int)):
         visual_size = (visual_size, visual_size)
@@ -123,6 +128,11 @@ def benarys_cross_rectangles(
     Returns
     -------
     A stimulus dictionary with the stimulus ['img'] and target mask ['mask']
+
+    References
+    -----------
+    Benary, W. (1924). Beobachtungen zu einem Experiment ueber Helligkeitskontrast.
+        Psychologische Forschung, 5, 131–142. https://doi.org/10.1007/BF00402398
     """
 
     if isinstance(visual_size, (float, int)):
@@ -193,6 +203,11 @@ def benarys_cross_triangles(
     Returns
     -------
     A stimulus dictionary with the stimulus ['img'] and target mask ['mask']
+
+    References
+    -----------
+    Benary, W. (1924). Beobachtungen zu einem Experiment ueber Helligkeitskontrast.
+        Psychologische Forschung, 5, 131–142. https://doi.org/10.1007/BF00402398
     """
 
     if isinstance(visual_size, (float, int)):
@@ -275,6 +290,11 @@ def todorovic_benary_generalized(
     Returns
     -------
     A stimulus dictionary with the stimulus ['img'] and target mask ['mask']
+
+    References
+    -----------
+    Benary, W. (1924). Beobachtungen zu einem Experiment ueber Helligkeitskontrast.
+        Psychologische Forschung, 5, 131–142. https://doi.org/10.1007/BF00402398
     """
     if isinstance(visual_size, (float, int)):
         visual_size = (visual_size, visual_size)
@@ -339,6 +359,11 @@ def todorovic_benary_rectangles(
     Returns
     -------
     A stimulus dictionary with the stimulus ['img'] and target mask ['mask']
+
+    References
+    -----------
+    Benary, W. (1924). Beobachtungen zu einem Experiment ueber Helligkeitskontrast.
+        Psychologische Forschung, 5, 131–142. https://doi.org/10.1007/BF00402398
     """
 
     if isinstance(visual_size, (float, int)):
@@ -401,6 +426,11 @@ def todorovic_benary_triangles(
     Returns
     -------
     A stimulus dictionary with the stimulus ['img'] and target mask ['mask']
+
+    References
+    -----------
+    Benary, W. (1924). Beobachtungen zu einem Experiment ueber Helligkeitskontrast.
+        Psychologische Forschung, 5, 131–142. https://doi.org/10.1007/BF00402398
     """
 
     if isinstance(visual_size, (float, int)):

stimuli/illusions/circular.py

@@ -71,6 +71,13 @@ def circular_white(
     dict[str, Any]
         dict with the stimulus (key: "img")
         and additional keys containing stimulus parameters
+
+    References
+    -----------
+    Hong, S. W., and Shevell, S. K. (2004). Brightness contrast and assimilation from patterned
+        inducing backgrounds. Vision Research, 44, 35–43. https://doi.org/10.1016/j.visres.2003.07.010
+    Howe, P. D. L. (2005). White's effect: removing the junctions but preserving the
+        strength of the illusion. Perception, 34, 557–564. https://doi.org/10.1068/p5414
     """
 
     # Get stim
@@ -189,6 +196,15 @@ def circular_bullseye(
     dict[str, Any]
         dict with the stimulus (key: "img")
         and additional keys containing stimulus parameters
+
+    References
+    -----------
+    Bindman, D., & Chubb, C. (2004). Brightness assimilation in Bullseye displays.
+        Vision Research, 44, 309–319. https://doi.org/10.1016/S0042-6989(03)00430-9
+    Hong, S. W., and Shevell, S. K. (2004). Brightness contrast and assimilation from patterned
+        inducing backgrounds. Vision Research, 44, 35–43. https://doi.org/10.1016/j.visres.2003.07.010
+    Howe, P. D. L. (2005). White's effect: removing the junctions but preserving the
+        strength of the illusion. Perception, 34, 557–564. https://doi.org/10.1068/p5414
     """
     stim = circular_white(
         visual_size=visual_size,

stimuli/illusions/cornsweet.py

@@ -48,9 +48,11 @@ def cornsweet(
 
     References
     ----------
-    The formula and default values are adapted from Boyaci, H., Fang, F., Murray,
-    S.O., Kersten, D. (2007). Responses to Lightness Variations in Early Human
-    Visual Cortex. Current Biology 17, 989-993.
+    Boyaci, H., Fang, F., Murray, S.O., Kersten, D. (2007). Responses to lightness
+        variations in early human visual cortex. Current Biology 17, 989-993.
+        https://doi.org/10.1016/j.cub.2007.05.005
+    Cornsweet, T. (1970). Visual perception. Academic press.
+        https://doi.org/10.1016/B978-0-12-189750-5.X5001-5
     """
     if isinstance(visual_size, (float, int)):
         visual_size = (visual_size, visual_size)

stimuli/illusions/cube.py

@@ -1,6 +1,5 @@
 import numpy as np
 from stimuli.utils import degrees_to_pixels
-# from stimuli.illusions.checkerboards import checkerboard
 
 
 __all__ = [
@@ -19,6 +18,42 @@ def cube_varying_cells(
     intensity_grid=1.0,
     intensity_target=0.5,
 ):
+    """
+    Cube illusion (Agostini & Galmonte, 2002) with flexible cell sizes.
+
+    Parameters
+    ----------
+    ppd : int
+        pixels per degree (visual angle)
+    cell_heights : Sequence or float
+        Heights of individual cell elements in degrees. Will be used on each side.
+    cell_widths : Sequence or float
+        Widths of individual cell elements in degrees. Will be used on each side.
+    cell_spacing : Sequence or float
+        distance between individual cells iin degrees. Will be used on each side.
+    targets : Sequence
+        Target indices. Will be used on each side
+    intensity_background : float
+        intensity value for background
+    intensity_grid : float
+        intensity value for grid cells
+    intensity_target : float
+        intensity value for target
+
+    Returns
+    -------
+    A stimulus dictionary with the stimulus ['img'] and target mask ['mask']
+
+    References
+    ----------
+    Agostini, T., and Galmonte, A. (2002). Perceptual organization overcomes the
+        effects of local surround in determining simultaneous lightness contrast.
+        Psychol. Sci. 13, 89–93. https://doi.org/10.1111/1467-9280.00417
+    Domijan, D. (2015). A neurocomputational account of the role of contour
+        facilitation in brightness perception. Frontiers in Human Neuroscience,
+        9, 93. https://doi.org/10.3389/fnhum.2015.00093
+    """
+
     if isinstance(cell_heights, (float, int)):
         cell_heights = (cell_heights,)
     if isinstance(cell_widths, (float, int)):
@@ -85,6 +120,16 @@ def cube_varying_cells(
     stim = {
         "img": img,
         "mask": mask.astype(int),
+        "shape": img.shape,
+        "visual_size": np.array(img.shape) / ppd,
+        "ppd": ppd,
+        "targets": targets,
+        "cell_heights": cell_heights,
+        "cell_widths": cell_widths,
+        "cell_spacing": cell_spacing,
+        "intensity_background": intensity_background,
+        "intensity_grid": intensity_grid,
+        "intensity_target": intensity_target,
         }
     return stim
 
@@ -106,14 +151,16 @@ def cube_illusion(
 
     Parameters
     ----------
-    visual_size :
-        blub
+    visual_size : (float, float)
+        The shape of the stimulus in degrees of visual angle. (y,x)
     ppd : int
         pixels per degree (visual angle)
     n_cells : int
         the number of square cells (not counting background) per dimension
-    cell_thickness : 
-        blub
+    targets : Sequence
+        Target indices. Will be used on each side
+    cell_thickness : float
+        Thickness of each cell in degree of visual angle
     cell_spacing : float or (float, float)
         distance between two cells in degrees visual angle
     intensity_background : float
@@ -126,6 +173,15 @@ def cube_illusion(
     Returns
     -------
     A stimulus dictionary with the stimulus ['img'] and target mask ['mask']
+
+    References
+    ----------
+    Agostini, T., and Galmonte, A. (2002). Perceptual organization overcomes the
+        effects of local surround in determining simultaneous lightness contrast.
+        Psychol. Sci. 13, 89–93. https://doi.org/10.1111/1467-9280.00417
+    Domijan, D. (2015). A neurocomputational account of the role of contour
+        facilitation in brightness perception. Frontiers in Human Neuroscience,
+        9, 93. https://doi.org/10.3389/fnhum.2015.00093
     """
     if isinstance(visual_size, (float, int)):
         visual_size = (visual_size, visual_size)
@@ -186,6 +242,16 @@ def cube_illusion(
     stim = {
         "img": img,
         "mask": mask.astype(int),
+        "shape": img.shape,
+        "visual_size": np.array(img.shape) / ppd,
+        "ppd": ppd,
+        "targets": targets,
+        "n_cells": n_cells,
+        "cell_thickness": cell_thickness,
+        "cell_spacing": cell_spacing,
+        "intensity_background": intensity_background,
+        "intensity_grid": intensity_grid,
+        "intensity_target": intensity_target,
         }
     return stim
 

stimuli/illusions/dungeon.py

@@ -45,6 +45,14 @@ def dungeon_illusion(
     Returns
     -------
     A stimulus dictionary with the stimulus ['img'] and target mask ['mask']
+
+    References
+    -----------
+    Bressan, P. (2001). Explaining lightness illusions. Perception, 30(9), 1031–1046.
+        https://doi.org/10.1068/p3109
+    Domijan, D. (2015). A neurocomputational account of the role of contour
+        facilitation in brightness perception. Frontiers in Human Neuroscience,
+        9, 93. https://doi.org/10.3389/fnhum.2015.00093
     """
 
     if isinstance(visual_size, (float, int)) or (visual_size is None):

stimuli/illusions/frames.py

@@ -58,6 +58,12 @@ def frames(
         dict with the stimulus (key: "img"),
         mask with integer index for each target (key: "mask"),
         and additional keys containing stimulus parameters
+
+    References
+    ----------
+    Domijan, D. (2015). A neurocomputational account of the role of contour
+        facilitation in brightness perception. Frontiers in Human Neuroscience,
+        9, 93. https://doi.org/10.3389/fnhum.2015.00093
     """
 
     # Frames component
@@ -144,6 +150,11 @@ def bullseye(
         dict with the stimulus (key: "img"),
         mask with integer index for each target (key: "mask"),
         and additional keys containing stimulus parameters
+
+    References
+    -----------
+    Bindman, D., & Chubb, C. (2004). Brightness assimilation in Bullseye displays.
+        Vision Research, 44, 309–319. https://doi.org/10.1016/S0042-6989(03)00430-9
     """
 
     stim = frames(

stimuli/illusions/grating.py

@@ -154,11 +154,17 @@ def grating_uniform(
         intensity value of background, by default 0.5.
 
     Returns
-    ----------
+    -------
     dict[str, Any]
         dict with the stimulus (key: "img"),
         mask with integer index for each bar (key: "mask"),
         and additional keys containing stimulus parameters
+    
+    References
+    ----------
+    White, M. (1981). The effect of the nature of the surround on the perceived
+        lightness of grey bars within square-wave test gratings. Perception, 10(2),
+        215–230. https://doi.org/10.1068/p100215
     """
 
     # Spatial square-wave grating
@@ -213,11 +219,17 @@ def grating_grating(
         pixels per degree [vertical, horizontal]
 
     Returns
-    ----------
+    -------
     dict[str, Any]
         dict with the stimulus (key: "img"),
         mask with integer index for each bar (key: "mask"),
         and additional keys containing stimulus parameters
+
+    References
+    ----------
+    White, M. (1981). The effect of the nature of the surround on the perceived
+        lightness of grey bars within square-wave test gratings. Perception, 10(2),
+        215–230. https://doi.org/10.1068/p100215
     """
 
     # Create gratings
@@ -302,11 +314,17 @@ def grating_grating_shifted(
         If fewer intensities are passed than target_indices, cycles through intensities
 
     Returns
-    ----------
+    -------
     dict[str, Any]
         dict with the stimulus (key: "img"),
         mask with integer index for each target (key: "mask"),
         and additional keys containing stimulus parameters
+
+    References
+    ----------
+    White, M. (1981). The effect of the nature of the surround on the perceived
+        lightness of grey bars within square-wave test gratings. Perception, 10(2),
+        215–230. https://doi.org/10.1068/p100215
     """
 
     # Resolve initial params
@@ -399,11 +417,16 @@ def grating_induction(
         amount of Gaussian blur to apply, default is 0.
 
     Returns
-    ----------
+    -------
     dict[str, Any]
         dict with the stimulus (key: "img"),
         mask with integer index for each target (key: "mask"),
         and additional keys containing stimulus parameters
+
+    References
+    ----------
+    McCourt, M. E. (1982). A spatial frequency dependent grating-induction effect.
+        Vision Research, 22, 119–134. https://doi.org/10.1016/0042-6989(82)90173-0
     """
 
     # Draw grating

stimuli/illusions/hermann.py

@@ -32,6 +32,11 @@ def hermann_grid(
     Returns
     -------
     A stimulus dictionary with the stimulus ['img'] and target mask ['mask']
+    
+    References
+    ----------
+    Hermann L (1870). Eine Erscheinung simultanen Contrastes". Pflügers Archiv
+        fuer die gesamte Physiologie. 3: 13–15. https://doi.org/10.1007/BF01855743
     """
     if isinstance(visual_size, (float, int)):
         visual_size = (visual_size, visual_size)

stimuli/illusions/mondrians.py

@@ -40,6 +40,11 @@ def corrugated_mondrians(
     Returns
     -------
     A stimulus dictionary with the stimulus ['img'] and target mask ['mask']
+
+    References
+    ----------
+    Adelson, E. H. (1993). Perceptual organization and the judgment of brightness.
+        Science, 262(5142), 2042–2044. https://doi.org/10.1126/science.8266102
     """
 
     if isinstance(heights, (float, int)):