stimupy.components#

Modules#

stimupy.components.angulars

stimupy.components.edges

stimupy.components.frames

stimupy.components.gaussians

stimupy.components.lines

stimupy.components.radials

stimupy.components.shapes

stimupy.components.texts

stimupy.components.waves

Functions#

overview

Generate example stimuli from this module

plot_overview

Plot overview of examples in this module (and submodules)

image_base

Create coordinate-arrays to serve as image base for drawing

draw_regions

Draw regions defined by mask, with given intensities

mask_regions

Generate mask for regions in image

combine_masks

Combines several masks into a singular mask
overview(skip=False)[source]#

Generate example stimuli from this module

Returns:

Dict mapping names to individual stimulus dicts

Return type:

dict[str, dict]

plot_overview(mask=False, save=None, units='deg')[source]#

Plot overview of examples in this module (and submodules)

Parameters:

  • mask (bool or str, optional) – If True, plot mask on top of stimulus image (default: False). If string is provided, plot this key from stimulus dictionary as mask

  • save (None or str, optional) – If None (default), do not save the plot. If string is provided, save plot under this name.

  • units ("px", "deg" (default), or str) – what units to put on the axes, by default degrees visual angle (“deg”). If a str other than “deg”(/”degrees”) or “px”(/”pix”/”pixels”) is passed, it must be the key to a tuple in stim

image_base(visual_size=None, shape=None, ppd=None, rotation=0.0, origin='mean')[source]#

Create coordinate-arrays to serve as image base for drawing

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

  • rotation (float, optional) – rotation (in degrees) from 3 o’clock, counterclockwise, by default 0.0

  • 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 keys: “visual_size”, “ppd” : resolved from input arguments, “x”, “y” : single axes “horizontal”, “vertical” : numpy.ndarray of shape, with distance from origin, in deg. visual angle, at each pixel “oblique”, “oblique_y” : numpy.ndarray of shape, with oblique distances from origin, in deg. visual angle, at each pixel “radial” : numpyn.ndarray of shape, with radius from origin, in deg. visual angle, at each pixel “angular” : numpy.ndarray of shape, with angle relative to 3 o’clock, in rad, at each pixel “rectilinear” : numpy.ndarray of shape, with rectilinear/cityblock/Manhattan distance from origin, in deg. visual angle, at each pixel

Return type:

dict[str, Any]

draw_regions(mask, intensities, intensity_background=0.5)[source]#

Draw regions defined by mask, with given intensities

Parameters:

  • mask (numpy.ndarray) – image-array with integer-indices for each region to draw

  • intensities (Sequence[float, ...]) – intensity value for each masked region. Can specify as many intensities as number of masked regions; If fewer intensities are passed than masked regions, cycles through intensities

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

Returns:

image-array, same shape as mask, with intensity assigned to each masked region

Return type:

numpy.ndarray

mask_regions(distance_metric, edges, shape=None, visual_size=None, ppd=None, rotation=0.0, origin=None)[source]#

Generate mask for regions in image

Regions are defined by edges along a distance_metric. Regions will be masked consecutively, from origin outwards, such that each edge is the upper-limit of a region.

Parameters:

  • distance_metric (any of keys in stimupy.components.image_base()) – which distance metric to mask over

  • edges (Sequence[Number]) – upper-limit of each consecutive region

  • 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

  • rotation (float, optional) – rotation (in degrees) from 3 o’clock, counterclockwise, by default 0.0

  • 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:

mask with integer index for each angular segment (key: “mask”), and additional keys containing stimulus parameters

Return type:

dict[str, Any]

combine_masks(*masks)[source]#

Combines several masks into a singular mask

Increments mask-indices, such that the resulting mask contains consecutive integer indices. Masks are combined in order.

Parameters:
Returns:

Combined mask, where integer indices are in order of the input masks.

Return type:

numpy.ndarray

Raises:

  • ValueError – if masks do not all have the same shape (in pixels)

  • ValueError – if multiple masks index the same pixel