stimupy.stimuli.sbcs#

Demos#

Functions#

generalized

Simultaneous contrast stimulus with free target placement

basic

Simultaneous contrast stimulus with central target

square

Simultaneous contrast stimulus with square target and surround field

circular

Simultaneous contrast stimulus with circular target and surround field

with_dots

Simultaneous contrast stimulus with dots

dotted

Dotted simultaneous contrast

basic_two_sided

Simultaneous contrast stimulus with central target

square_two_sided

Simultaneous contrast stimulus with square target and surround field

circular_two_sided

Simultaneous contrast stimulus with circular target and surround field

with_dots_two_sided

Simultaneous contrast stimulus with dots

dotted_two_sided

Dotted simultaneous contrast
generalized(visual_size=None, ppd=None, shape=None, target_size=None, target_position=None, intensity_background=0.0, intensity_target=0.5, rotation=0.0)[source]#

Simultaneous contrast stimulus with free target placement

Parameters:

  • visual_size (Sequence[Number, Number], Number, or None (default)) – visual size [height, width] of image, in degrees

  • ppd (Sequence[Number, Number], Number, or None (default)) – pixels per degree [vertical, horizontal]

  • shape (Sequence[Number, Number], Number, or None (default)) – shape [height, width] of image, in pixels

  • target_size (float or (float, float)) – size [height, width] of the target, in degrees visual angle

  • target_position (float or (float, float)) – position of the target in degree visual angle (height, width); if None, place target centrally

  • intensity_background (float, optional) – intensity value for background, by default 0.0

  • intensity_target (float, optional) – intensity value for target, by default 0.5

  • rotation (float, optional) – rotation (in degrees), counterclockwise, by default 0.0 (horizontal)

Returns:

dict with the stimulus (key: “img”), mask with integer index for the target (key: “target_mask”), and additional keys containing stimulus parameters

Return type:

dict[str, Any]

References

Chevreul, M. (1855).

The principle of harmony and contrast of colors.

basic(visual_size=None, ppd=None, shape=None, target_size=None, intensity_background=0.0, intensity_target=0.5)[source]#

Simultaneous contrast stimulus with central target

Parameters:

  • visual_size (Sequence[Number, Number], Number, or None (default)) – visual size [height, width] of image, in degrees

  • ppd (Sequence[Number, Number], Number, or None (default)) – pixels per degree [vertical, horizontal]

  • shape (Sequence[Number, Number], Number, or None (default)) – shape [height, width] of image, in pixels

  • target_size (float or (float, float)) – size [height, width] of the target, in degrees visual angle

  • intensity_background (float, optional) – intensity value for background, by default 0.0

  • intensity_target (float, optional) – intensity value for target, by default 0.5

Returns:

dict with the stimulus (key: “img”), mask with integer index for the target (key: “target_mask”), and additional keys containing stimulus parameters

Return type:

dict[str, Any]

References

Chevreul, M. (1855).

The principle of harmony and contrast of colors.

square(target_radius, visual_size=None, ppd=None, shape=None, surround_radius=None, rotation=0.0, intensity_surround=0.0, intensity_background=0.5, intensity_target=0.5, origin='mean')[source]#

Simultaneous contrast stimulus with square target and surround field

Parameters:

  • visual_size (Sequence[Number, Number], Number, or None (default)) – visual size [height, width] of image, in degrees

  • ppd (Sequence[Number, Number], Number, or None (default)) – pixels per degree [vertical, horizontal]

  • shape (Sequence[Number, Number], Number, or None (default)) – shape [height, width] of image, in pixels

  • target_radius (float) – radius of target, in degrees visual angle

  • surround_radius (float) – radius of surround context field, in degrees visual angle

  • rotation (float, optional) – rotation (in degrees), counterclockwise, by default 0.0 (horizontal)

  • intensity_surrond (float, optional) – intensity of surround context field, by default 0.0

  • intensity_background (float, optional) – intensity value of background, by default 0.5

  • intensity_target (float, or Sequence[float, ...], optional) – intensity value for each target, by default 0.5.

  • origin ("corner", "mean" or "center") – if “corner”: set origin to upper left corner if “mean”: set origin to hypothetical image center (default) if “center”: set origin to real center (closest existing value to mean)

Returns:

dict with the stimulus (key: “img”), mask with integer index for each frame (key: “target_mask”), and additional keys containing stimulus parameters

Return type:

dict[str, Any]

circular(target_radius, visual_size=None, ppd=None, shape=None, surround_radius=None, intensity_surround=0.0, intensity_background=0.5, intensity_target=0.5, origin='mean')[source]#

Simultaneous contrast stimulus with circular target and surround field

Parameters:

  • visual_size (Sequence[Number, Number], Number, or None (default)) – visual size [height, width] of image, in degrees

  • ppd (Sequence[Number, Number], Number, or None (default)) – pixels per degree [vertical, horizontal]

  • shape (Sequence[Number, Number], Number, or None (default)) – shape [height, width] of image, in pixels

  • target_radius (float) – radius of target, in degrees visual angle

  • surround_radius (float) – radius of surround context field, in degrees visual angle

  • rotation (float, optional) – rotation (in degrees), counterclockwise, by default 0.0 (horizontal)

  • intensity_surrond (float, optional) – intensity of surround context field, by default 0.0

  • intensity_background (float (optional)) – intensity value of background, by default 0.5

  • intensity_target (float, or Sequence[float, ...], optional) – intensity value for each target, by default 0.5. Can specify as many intensities as number of target_indices; If fewer intensities are passed than target_indices, cycles through intensities

  • origin ("corner", "mean" or "center") – if “corner”: set origin to upper left corner if “mean”: set origin to hypothetical image center (default) if “center”: set origin to real center (closest existing value to mean)

Returns:

dict with the stimulus (key: “img”), mask with integer index for each frame (key: “target_mask”), and additional keys containing stimulus parameters

Return type:

dict[str, Any]

with_dots(visual_size=None, ppd=None, shape=None, n_dots=None, dot_radius=None, distance=None, target_shape=None, intensity_background=0.0, intensity_dots=1.0, intensity_target=0.5)[source]#

Simultaneous contrast stimulus with dots

Parameters:

  • visual_size (Sequence[Number, Number], Number, or None (default)) – visual size [height, width] of grating, in degrees

  • ppd (Sequence[Number, Number], Number, or None (default)) – pixels per degree [vertical, horizontal]

  • shape (Sequence[Number, Number], Number, or None (default)) – shape [height, width] of grating, in pixels

  • n_dots (int or (int, int)) – stimulus size defined as the number of dots in y and x-directions

  • dot_radius (float) – radius of dots

  • distance (float) – distance between dots in degree visual angle

  • target_shape (int or (int, int)) – target shape defined as the number of dots that fit into the target

  • intensity_background (float) – intensity value for background

  • intensity_dots (float) – intensity value for dots

  • intensity_target (float) – intensity value for target

Returns:

dict with the stimulus (key: “img”), mask with integer index for the target (key: “target_mask”), and additional keys containing stimulus parameters

Return type:

dict[str, Any]

References

Bressan, P., & Kramer, P. (2008).

Gating of remote effects on lightness. Journal of Vision, 8(2), 16-16. https://doi.org/10.1167/8.2.16

dotted(visual_size=None, ppd=None, shape=None, n_dots=None, dot_radius=None, distance=None, target_shape=None, intensity_background=0.0, intensity_dots=1.0, intensity_target=0.5)[source]#

Dotted simultaneous contrast

Parameters:

  • visual_size (Sequence[Number, Number], Number, or None (default)) – visual size [height, width] of grating, in degrees

  • ppd (Sequence[Number, Number], Number, or None (default)) – pixels per degree [vertical, horizontal]

  • shape (Sequence[Number, Number], Number, or None (default)) – shape [height, width] of grating, in pixels

  • n_dots (int or (int, int)) – stimulus size defined as the number of dots in y and x-directions

  • dot_radius (float) – radius of dots

  • distance (float) – distance between dots in degree visual angle

  • target_shape (int or (int, int)) – target shape defined as the number of dots that fit into the target

  • intensity_background (float) – intensity value for background

  • intensity_dots (float) – intensity value for dots

  • intensity_target (float) – intensity value for target

Returns:

dict with the stimulus (key: “img”), mask with integer index for the targets (key: “target_mask”), and additional keys containing stimulus parameters

Return type:

dict[str, Any]

References

Bressan, P., & Kramer, P. (2008).

Gating of remote effects on lightness. Journal of Vision, 8(2), 16-16. https://doi.org/10.1167/8.2.16

basic_two_sided(visual_size=None, ppd=None, shape=None, target_size=None, intensity_background=0.0, intensity_target=0.5)#

Simultaneous contrast stimulus with central target

Parameters:

  • visual_size (Sequence[Number, Number], Number, or None (default)) – visual size [height, width] of image, in degrees

  • ppd (Sequence[Number, Number], Number, or None (default)) – pixels per degree [vertical, horizontal]

  • shape (Sequence[Number, Number], Number, or None (default)) – shape [height, width] of image, in pixels

  • target_size (float or (float, float)) – size [height, width] of the target, in degrees visual angle

  • intensity_background (float, optional) – intensity value for background, by default 0.0

  • intensity_target (float, optional) – intensity value for target, by default 0.5

Returns:

dict with the stimulus (key: “img”), mask with integer index for the target (key: “target_mask”), and additional keys containing stimulus parameters

Return type:

dict[str, Any]

References

Chevreul, M. (1855).

The principle of harmony and contrast of colors.

square_two_sided(target_radius, visual_size=None, ppd=None, shape=None, surround_radius=None, rotation=0.0, intensity_surround=0.0, intensity_background=0.5, intensity_target=0.5, origin='mean')#

Simultaneous contrast stimulus with square target and surround field

Parameters:

  • visual_size (Sequence[Number, Number], Number, or None (default)) – visual size [height, width] of image, in degrees

  • ppd (Sequence[Number, Number], Number, or None (default)) – pixels per degree [vertical, horizontal]

  • shape (Sequence[Number, Number], Number, or None (default)) – shape [height, width] of image, in pixels

  • target_radius (float) – radius of target, in degrees visual angle

  • surround_radius (float) – radius of surround context field, in degrees visual angle

  • rotation (float, optional) – rotation (in degrees), counterclockwise, by default 0.0 (horizontal)

  • intensity_surrond (float, optional) – intensity of surround context field, by default 0.0

  • intensity_background (float, optional) – intensity value of background, by default 0.5

  • intensity_target (float, or Sequence[float, ...], optional) – intensity value for each target, by default 0.5.

  • origin ("corner", "mean" or "center") – if “corner”: set origin to upper left corner if “mean”: set origin to hypothetical image center (default) if “center”: set origin to real center (closest existing value to mean)

Returns:

dict with the stimulus (key: “img”), mask with integer index for each frame (key: “target_mask”), and additional keys containing stimulus parameters

Return type:

dict[str, Any]

circular_two_sided(target_radius, visual_size=None, ppd=None, shape=None, surround_radius=None, intensity_surround=0.0, intensity_background=0.5, intensity_target=0.5, origin='mean')#

Simultaneous contrast stimulus with circular target and surround field

Parameters:

  • visual_size (Sequence[Number, Number], Number, or None (default)) – visual size [height, width] of image, in degrees

  • ppd (Sequence[Number, Number], Number, or None (default)) – pixels per degree [vertical, horizontal]

  • shape (Sequence[Number, Number], Number, or None (default)) – shape [height, width] of image, in pixels

  • target_radius (float) – radius of target, in degrees visual angle

  • surround_radius (float) – radius of surround context field, in degrees visual angle

  • rotation (float, optional) – rotation (in degrees), counterclockwise, by default 0.0 (horizontal)

  • intensity_surrond (float, optional) – intensity of surround context field, by default 0.0

  • intensity_background (float (optional)) – intensity value of background, by default 0.5

  • intensity_target (float, or Sequence[float, ...], optional) – intensity value for each target, by default 0.5. Can specify as many intensities as number of target_indices; If fewer intensities are passed than target_indices, cycles through intensities

  • origin ("corner", "mean" or "center") – if “corner”: set origin to upper left corner if “mean”: set origin to hypothetical image center (default) if “center”: set origin to real center (closest existing value to mean)

Returns:

dict with the stimulus (key: “img”), mask with integer index for each frame (key: “target_mask”), and additional keys containing stimulus parameters

Return type:

dict[str, Any]

with_dots_two_sided(visual_size=None, ppd=None, shape=None, n_dots=None, dot_radius=None, distance=None, target_shape=None, intensity_background=0.0, intensity_dots=1.0, intensity_target=0.5)#

Simultaneous contrast stimulus with dots

Parameters:

  • visual_size (Sequence[Number, Number], Number, or None (default)) – visual size [height, width] of grating, in degrees

  • ppd (Sequence[Number, Number], Number, or None (default)) – pixels per degree [vertical, horizontal]

  • shape (Sequence[Number, Number], Number, or None (default)) – shape [height, width] of grating, in pixels

  • n_dots (int or (int, int)) – stimulus size defined as the number of dots in y and x-directions

  • dot_radius (float) – radius of dots

  • distance (float) – distance between dots in degree visual angle

  • target_shape (int or (int, int)) – target shape defined as the number of dots that fit into the target

  • intensity_background (float) – intensity value for background

  • intensity_dots (float) – intensity value for dots

  • intensity_target (float) – intensity value for target

Returns:

dict with the stimulus (key: “img”), mask with integer index for the target (key: “target_mask”), and additional keys containing stimulus parameters

Return type:

dict[str, Any]

References

Bressan, P., & Kramer, P. (2008).

Gating of remote effects on lightness. Journal of Vision, 8(2), 16-16. https://doi.org/10.1167/8.2.16

dotted_two_sided(visual_size=None, ppd=None, shape=None, n_dots=None, dot_radius=None, distance=None, target_shape=None, intensity_background=0.0, intensity_dots=1.0, intensity_target=0.5)#

Dotted simultaneous contrast

Parameters:

  • visual_size (Sequence[Number, Number], Number, or None (default)) – visual size [height, width] of grating, in degrees

  • ppd (Sequence[Number, Number], Number, or None (default)) – pixels per degree [vertical, horizontal]

  • shape (Sequence[Number, Number], Number, or None (default)) – shape [height, width] of grating, in pixels

  • n_dots (int or (int, int)) – stimulus size defined as the number of dots in y and x-directions

  • dot_radius (float) – radius of dots

  • distance (float) – distance between dots in degree visual angle

  • target_shape (int or (int, int)) – target shape defined as the number of dots that fit into the target

  • intensity_background (float) – intensity value for background

  • intensity_dots (float) – intensity value for dots

  • intensity_target (float) – intensity value for target

Returns:

dict with the stimulus (key: “img”), mask with integer index for the targets (key: “target_mask”), and additional keys containing stimulus parameters

Return type:

dict[str, Any]

References

Bressan, P., & Kramer, P. (2008).

Gating of remote effects on lightness. Journal of Vision, 8(2), 16-16. https://doi.org/10.1167/8.2.16