pulse2percept.percepts.metrics

FrameMetrics,: PerceptMetrics, measure_percept()

Phosphene measurements. Imported on demand by measure(), not by pulse2percept.percepts.

Functions

measure_percept(percept[, threshold])

Measure the phosphenes in a brightness percept

Classes

`FrameMetrics`(integrated_brightness, ...)	Phosphene measurements for a single frame of a brightness percept
`PerceptMetrics`(frames, threshold)	Phosphene measurements for every frame of a brightness percept

class pulse2percept.percepts.metrics.FrameMetrics(integrated_brightness: float, max_brightness: float, area: float, centroid: tuple[float, float], diameter: float, major_axis: float, minor_axis: float, elongation: float, n_components: int, touches_edge: bool)[source]

Phosphene measurements for a single frame of a brightness percept

Produced by measure_percept(), usually through measure().

Only positive brightness is measured: the frame is clipped at zero first. The support is the set of pixels at or above threshold times the frame’s own positive maximum (half maximum by default). Geometry is measured on that support as a binary set of pixels, unweighted by the brightness within it, and describes the support in full even when it falls into several components. For a sufficiently sampled circular support, major_axis, minor_axis and diameter converge to a common value.

A frame without positive brightness has no phosphene: brightness, area and component count are zero, and position and shape are NaN.

Added in version 0.11.0.

integrated_brightness

Positive brightness integrated over the visual field (brightness units x dva^2): the pixel sum scaled by pixel area. Approximates a spatial integral, so it is insensitive to sampling resolution up to discretization.

Type:: float

max_brightness

Largest positive brightness in the frame (arbitrary units).

Type:: float

area

Area of the support (dva^2).

Type:: float

centroid

Mean position (x, y) of the support pixels (dva).

Type:: (float, float)

diameter

Diameter (dva) of the circle of equal area, 2 * sqrt(area / pi). At threshold=0.5 this approximates the FWHM of a sufficiently sampled circular Gaussian; agreement is limited by grid resolution.

Type:: float

major_axis, minor_axis

Axis lengths (dva) of the ellipse with the same second moments as the support, 4 * sqrt(eigenvalue). Exact for a continuous uniformly filled ellipse; sampled supports approach those values as resolution increases.

Type:: float

elongation

major_axis / minor_axis; approaches 1 for a circular phosphene.

Type:: float

n_components

Number of connected components in the support, using full 2D connectivity so diagonal neighbors count as connected. Descriptive only: the other measurements still describe the combined support.

Type:: int

touches_edge

Whether the support reaches the first or last row or column. If True, the percept may extend beyond the simulated field and the measurements describe only its visible part.

Type:: bool

class pulse2percept.percepts.metrics.PerceptMetrics(frames: tuple[FrameMetrics, ...], threshold: float)[source]

Phosphene measurements for every frame of a brightness percept

Produced by measure_percept(), usually through measure(). Frames are measured independently; frame timing stays in time.

Every FrameMetrics measurement is also available as an array over frames: metrics.diameter is the diameter of each frame, metrics.peak.diameter that of the brightest.

Added in version 0.11.0.

frames

One measurement per frame, in the order the frames are stored.

Type:: tuple of FrameMetrics

threshold

Fraction of each frame’s own positive maximum that defined its support.

Type:: float

property peak_frame

Index of the frame with the largest integrated_brightness

Ties go to the earliest frame, as with np.argmax.

property peak: FrameMetrics of the frame at peak_frame

property integrated_brightness: Integrated positive brightness of each frame, (T,)

property max_brightness: Largest positive brightness of each frame, (T,)

property area: Support area (dva^2) of each frame, (T,)

property diameter: Equivalent-circle diameter (dva) of each frame, (T,)

property centroid: Support (x, y) center (dva) of each frame, (T, 2)

property major_axis: Equivalent-ellipse major axis (dva) of each frame, (T,)

property minor_axis: Equivalent-ellipse minor axis (dva) of each frame, (T,)

property elongation: Axis ratio of each frame, (T,)

property n_components: Number of connected support components in each frame, (T,)

property touches_edge: Whether each frame’s support reaches the field border, (T,)

pulse2percept.percepts.metrics.measure_percept(percept, threshold=0.5)[source]

Measure the phosphenes in a brightness percept

Measures each frame independently. See FrameMetrics for the definitions and units.

Added in version 0.11.0.

Parameters:

percept (Percept) – A (Y, X, T) brightness percept built on a Grid2D. The grid is required because positions and sizes are reported in degrees of visual angle; without one a percept carries pixel indices instead.
threshold (float, optional) – Fraction of a frame’s own positive maximum at or above which a pixel belongs to the support. Must lie in (0, 1]. A Gaussian of standard deviation sigma has support diameter 2 * sigma * sqrt(-2 * log(threshold)), so the default of 0.5 gives approximately its FWHM.

Returns:

metrics

Return type:

PerceptMetrics

Raises:

ValueError – For an RGB percept, a percept without visual-field coordinates, a threshold outside (0, 1], or non-finite data.

Notes

These measurements describe the modeled percept image, not behavioral performance such as acuity or discriminability.