stimupy.stimuli.whites#
Demos#
Functions#
General function to create White's stimulus |
|
White's stimulus where all targets are vertically aligned at half the stimulus height |
|
White's stimulus where targets are placed in two rows (top, bottom) that have the same distance from the center. |
|
Anderson variation of White's stimulus |
|
Howe variation of White's stimulus |
|
Yazsdanbakhsh variation of White's stimulus |
|
Pinwheel / radial White stimulus |
|
Circular square-wave grating (set of rings) over the whole image, with some ring(s) as target(s) |
|
Wedding cake stimulus |
- generalized(visual_size=None, ppd=None, shape=None, frequency=None, n_bars=None, bar_width=None, period='ignore', rotation=0.0, intensity_bars=(0.0, 1.0), target_indices=(), intensity_target=0.5, target_center_offsets=0, target_heights=None, origin='corner', round_phase_width=True)[source]#
General function to create White’s stimulus
- 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
frequency (Number, or None (default)) – spatial frequency of grating, in cycles per degree visual angle
n_bars (int, or None (default)) – number of bars in the grating
bar_width (Number, or None (default)) – width of a single bar, in degrees visual angle
period ("even", "odd", "either" or "ignore" (default)) – ensure whether the grating has “even” number of phases, “odd” number of phases, either or whether not to round the number of phases (“ignore”)
rotation (float, optional) – rotation (in degrees), counterclockwise, by default 0.0 (horizontal)
intensity_bars (Sequence[float, ...]) – intensity value for each bar, by default (1.0, 0.0). Can specify as many intensities as n_bars; If fewer intensities are passed than n_bars, cycles through intensities
target_indices (int, or Sequence[int, ...]) – indices segments where targets will be placed
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
target_center_offsets (float, or Sequence[float, ...]) – center offset of targets in degrees visual angle (default: 0)
target_heights (float, or Sequence[float, ...]) – height of targets in degrees visual angle
origin ("corner", "mean" or "center") – if “corner”: set origin to upper left corner (default) if “mean”: set origin to hypothetical image center if “center”: set origin to real center (closest existing value to mean)
round_phase_width (Bool) – if True (default), round phase width of grating
- Returns:
dict with the stimulus (key: “img”), mask with integer index for each target (key: “mask”), and additional keys containing stimulus parameters
- Return type:
References
- White, M. (1979).
A new effect of pattern on perceived lightness. Perception, 8(4), 413-416. https://doi.org/10.1068/p080413
- white(visual_size=None, ppd=None, shape=None, frequency=None, n_bars=None, bar_width=None, period='ignore', rotation=0.0, intensity_bars=(0.0, 1.0), target_indices=(), intensity_target=0.5, target_heights=None, origin='corner', round_phase_width=True)[source]#
White’s stimulus where all targets are vertically aligned at half the stimulus height
- 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
frequency (Number, or None (default)) – spatial frequency of grating, in cycles per degree visual angle
n_bars (int, or None (default)) – number of bars in the grating
bar_width (Number, or None (default)) – width of a single bar, in degrees visual angle
period ("even", "odd", "either" or "ignore" (default)) – ensure whether the grating has “even” number of phases, “odd” number of phases, either or whether not to round the number of phases (“ignore”)
rotation (float, optional) – rotation (in degrees), counterclockwise, by default 0.0 (horizontal)
phase_shift (float) – phase shift of grating in degrees
intensity_bars (Sequence[float, ...]) – intensity value for each bar, by default (1.0, 0.0). Can specify as many intensities as n_bars; If fewer intensities are passed than n_bars, cycles through intensities
target_indices (int, or Sequence[int, ...]) – indices segments where targets will be placed
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
target_heights (float, or Sequence[float, ...]) – height of targets in degrees visual angle
origin ("corner", "mean" or "center") – if “corner”: set origin to upper left corner (default) if “mean”: set origin to hypothetical image center if “center”: set origin to real center (closest existing value to mean)
round_phase_width (Bool) – if True (default), round phase width of grating
- Returns:
dict with the stimulus (key: “img”), mask with integer index for each target (key: “mask”), and additional keys containing stimulus parameters
- Return type:
References
- White, M. (1979).
A new effect of pattern on perceived lightness. Perception, 8(4), 413-416. https://doi.org/10.1068/p080413
- white_two_rows(visual_size=None, ppd=None, shape=None, frequency=None, n_bars=None, bar_width=None, period='ignore', rotation=0.0, intensity_bars=(0.0, 1.0), intensity_target=0.5, target_indices_top=(), target_indices_bottom=(), target_center_offset=None, target_heights=None, origin='corner', round_phase_width=True)[source]#
White’s stimulus where targets are placed in two rows (top, bottom) that have the same distance from the center.
- 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
frequency (Number, or None (default)) – spatial frequency of grating, in cycles per degree visual angle
n_bars (int, or None (default)) – number of bars in the grating
bar_width (Number, or None (default)) – width of a single bar, in degrees visual angle
period ("even", "odd", "either" or "ignore" (default)) – ensure whether the grating has “even” number of phases, “odd” number of phases, either or whether not to round the number of phases (“ignore”)
rotation (float, optional) – rotation (in degrees), counterclockwise, by default 0.0 (horizontal)
intensity_bars (Sequence[float, ...]) – intensity value for each bar, by default (1.0, 0.0). Can specify as many intensities as n_bars; If fewer intensities are passed than n_bars, cycles through intensities
intensity_target (float) – intensity value of target
target_indices_top (int or tuple of ints) – bar indices where top target(s) will be placed. As many targets as ints.
target_indices_bottom (int or tuple of ints) – bar indices where bottom target(s) will be placed. As many targets as ints.
target_center_offset (float) – offset from target centers to image center in degree visual angle.
target_heights (float, or Sequence[float, ...]) – height of targets in degrees visual angle
origin ("corner", "mean" or "center") – if “corner”: set origin to upper left corner (default) if “mean”: set origin to hypothetical image center if “center”: set origin to real center (closest existing value to mean)
round_phase_width (Bool) – if True (default), round phase width of grating
- Returns:
dict with the stimulus (key: “img”), mask with integer index for each target (key: “mask”), and additional keys containing stimulus parameters
- Return type:
References
- White, M. (1979).
A new effect of pattern on perceived lightness. Perception, 8(4), 413-416. https://doi.org/10.1068/p080413
- anderson(visual_size=None, ppd=None, shape=None, frequency=None, n_bars=None, bar_width=None, period='ignore', intensity_bars=(0.0, 1.0), intensity_target=0.5, target_indices_top=None, target_indices_bottom=None, target_center_offset=0, target_height=None, intensity_stripes=(0.0, 1.0), stripe_center_offset=0, stripe_height=None, round_phase_width=True)[source]#
Anderson variation of White’s stimulus
- 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
frequency (Number, or None (default)) – spatial frequency of grating, in cycles per degree visual angle
n_bars (int, or None (default)) – number of bars in the grating
bar_width (Number, or None (default)) – width of a single bar, in degrees visual angle
period ("even", "odd", "either" or "ignore" (default)) – ensure whether the grating has “even” number of phases, “odd” number of phases, either or whether not to round the number of phases (“ignore”)
intensity_target (float) – intensity value of target
target_indices_top (int or tuple of ints) – bar indices where top target(s) will be placed. As many targets as ints.
target_indices_bottom (int or tuple of ints) – bar indices where bottom target(s) will be placed. As many targets as ints.
target_center_offset (float) – offset from target centers to image center in degree visual angle.
target_height (float, or Sequence[float, ...]) – height of targets in degrees visual angle
intensity_stripes ((float, float)) – intensity values of horizontal stripes
stripe_center_offset (float) – offset from stripe centers to image center in degree visual angle.
float (stripe_height =) – stripe height in degrees visual angle
round_phase_width (Bool) – if True (default), round phase width of grating
- Returns:
dict with the stimulus (key: “img”), mask with integer index for each target (key: “mask”), and additional keys containing stimulus parameters
- Return type:
References
- Anderson, B. L. (2001).
Contrasting theories of White’s illusion. Perception, 30, 1499-1501.
- Blakeslee, B., Pasieka, W., & McCourt, M. E. (2005).
Oriented multiscale spatial filtering and contrast normalization: a parsimonious model of brightness induction in a continuum of stimuli including White, Howe and simultaneous brightness contrast. Vision Research, 45, 607-615.
- howe(visual_size=None, ppd=None, shape=None, frequency=None, n_bars=None, bar_width=None, period='ignore', intensity_bars=(0.0, 1.0), intensity_target=0.5, target_indices_top=None, target_indices_bottom=None, target_center_offset=0, target_height=None, intensity_stripes=(0.0, 1.0), round_phase_width=True)[source]#
Howe variation of White’s stimulus
- 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
frequency (Number, or None (default)) – spatial frequency of grating, in cycles per degree visual angle
n_bars (int, or None (default)) – number of bars in the grating
bar_width (Number, or None (default)) – width of a single bar, in degrees visual angle
period ("even", "odd", "either" or "ignore" (default)) – ensure whether the grating has “even” number of phases, “odd” number of phases, either or whether not to round the number of phases (“ignore”)
intensity_target (float) – intensity value of target
target_indices_top (int or tuple of ints) – bar indices where top target(s) will be placed. As many targets as ints.
target_indices_bottom (int or tuple of ints) – bar indices where bottom target(s) will be placed. As many targets as ints.
target_center_offset (float) – offset from target centers to image center in degree visual angle.
target_height (float, or Sequence[float, ...]) – height of targets in degrees visual angle
intensity_stripes ((float, float)) – intensity values of horizontal stripes
round_phase_width (Bool) – if True (default), round phase width of grating
- Returns:
dict with the stimulus (key: “img”), mask with integer index for each target (key: “mask”), and additional keys containing stimulus parameters
- Return type:
References
- Blakeslee, B., Pasieka, W., & McCourt, M. E. (2005).
Oriented multiscale spatial filtering and contrast normalization: a parsimonious model of brightness induction in a continuum of stimuli including White, Howe and simultaneous brightness contrast. Vision Research, 45, 607-615.
- Howe, P. D. L. (2001).
A comment on the Anderson (1997), the Todorovic (1997), and the Ross and Pessoa (2000) explanations of White’s effect. Perception, 30, 1023-1026
- yazdanbakhsh(visual_size=None, ppd=None, shape=None, frequency=None, n_bars=None, bar_width=None, period='ignore', intensity_bars=(0.0, 1.0), intensity_target=0.5, target_indices_top=None, target_indices_bottom=None, target_center_offset=0, target_heights=None, gap_size=None, round_phase_width=True)[source]#
Yazsdanbakhsh variation of White’s stimulus
- 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
frequency (Number, or None (default)) – spatial frequency of grating, in cycles per degree visual angle
n_bars (int, or None (default)) – number of bars in the grating
bar_width (Number, or None (default)) – width of a single bar, in degrees visual angle
period ("even", "odd", "either" or "ignore" (default)) – ensure whether the grating has “even” number of phases, “odd” number of phases, either or whether not to round the number of phases (“ignore”)
intensity_target (float) – intensity value of target
target_indices_top (int or tuple of ints) – bar indices where top target(s) will be placed. As many targets as ints.
target_indices_bottom (int or tuple of ints) – bar indices where bottom target(s) will be placed. As many targets as ints.
target_center_offset (float) – offset from target centers to image center in degree visual angle.
target_heights (float, or Sequence[float, ...]) – height of targets in degrees visual angle
gap_size (float) – size of gap between target and grating bar
round_phase_width (Bool) – if True (default), round phase width of grating
- Returns:
dict with the stimulus (key: “img”), mask with integer index for each target (key: “mask”), and additional keys containing stimulus parameters
- Return type:
References
- Yazdanbakhsh, A., Arabzadeh, E., Babadi, B., and Fazl, A. (2002).
Munker-White-like illusions without T-junctions. Perception 31, 711-715. https://doi.org/10.1068/p3348
- angular(visual_size=None, ppd=None, shape=None, frequency=None, n_segments=None, segment_width=None, rotation=0.0, target_indices=(), target_width=None, target_center=None, intensity_segments=(0.0, 1.0), intensity_background=0.5, intensity_target=0.5, origin='mean')#
Pinwheel / radial White stimulus
- Parameters:
visual_size ((float, float)) – The shape of the stimulus in degrees of visual angle. (y,x)
ppd (int) – pixels per degree (visual angle)
shape (Sequence[int, int], int, or None (default)) – shape [height, width] of image, in pixels
frequency (Number, or None (default)) – angular frequency of angular grating, in cycles per angular degree
n_segments (int, or None (default)) – number of segments
segment_width (Number, or None (default)) – angular width of a single segment, in degrees
rotation (float, optional) – rotation (in degrees), counterclockwise, by default 0.0
target_indices (int, or Sequence[int, ...]) – indices segments where targets will be placed
target_width (float, or Sequence[float, ...], optional) – target width (outer - inner radius) in deg visual angle, by default 1.0 Can specify as many target_widths as target_indices; if fewer widths are passed than indices, cycles through intensities
target_center (float, or Sequence[float, ...], optional) – center (radius) in deg visual angle where each target will be placed within its segment, by default 1.0. Can specify as many centers as target_indices; if fewer centers are passed than indices, cycles through intensities
intensity_segments (Sequence[float, ...]) – intensity value for each segment, by default (1.0, 0.0). Can specify as many intensities as n_segments; If fewer intensities are passed than n_segments, cycles through intensities
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 target (key: “target_mask”), and additional keys containing stimulus parameters
- Return type:
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(visual_size=None, ppd=None, shape=None, frequency=None, n_rings=None, ring_width=None, period='ignore', rotation=0.0, phase_shift=0, intensity_rings=(0.0, 1.0), target_indices=(), intensity_target=0.5, origin='mean', round_phase_width=True, clip=False, intensity_background=0.5)#
Circular square-wave grating (set of rings) over the whole image, with some ring(s) as target(s)
- 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
frequency (Number, or None (default)) – spatial frequency of grating, in cycles per degree visual angle
n_rings (int, or None (default)) – number of rings in the grating
ring_width (Number, or None (default)) – width of a single ring, in degrees visual angle
period ("even", "odd", "either" or "ignore" (default)) – ensure whether the grating has “even” number of phases, “odd” number of phases, either or whether not to round the number of phases (“ignore”)
rotation (float, optional) – rotation (in degrees), counterclockwise, by default 0.0 (horizontal)
phase_shift (float) – phase shift of grating in degrees
intensity_rings (Sequence[float, float]) – intensity value for each ring, by default (1.0, 0.0).
target_indices (int, or Sequence[int, ...]) – indices segments where targets will be placed
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)
round_phase_width (Bool) – if True, round width of rings given resolution
clip (Bool) – if True, clip stimulus to image size (default: False)
intensity_background (float (optional)) – intensity value of background (if clipped), by default 0.5
- Returns:
dict with the stimulus (key: “img”), mask with integer index for each target (key: “target_mask”), and additional keys containing stimulus parameters
- Return type:
- wedding_cake(visual_size=None, ppd=None, shape=None, L_size=None, target_height=None, target_indices1=None, target_indices2=None, intensity_bars=(0.0, 1.0), intensity_target=0.5)[source]#
Wedding cake stimulus
- 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
L_size ((float, float, float)) – size of individual jags (height, width, thickness) in degree visual angle
target_height (float) – height of targets in degree visual angle
target_indices1 (nested tuples) – target indices with intensity1-value; as many tuples as there are targets each with (y, x) indices
target_indices2 (nested tuples) – target indices with intensity2-value; as many tuples as there are targets each with (y, x) indices
intensity_bars ((float, float)) – intensity values of the bars
intensity_target (float) – intensity value of targets
- 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:
References
- Clifford, C. W. G., & Spehar, B. (2003).
Using colour to disambiguate contrast and assimilation in White’s effect. Journal of Vision, 3, 294a. https://doi.org/10.1167/3.9.294