phasorpy.plot#

Plot phasor coordinates and related data.

The phasorpy.plot module provides functions and classes to visualize phasor coordinates and related data using the matplotlib library.

class phasorpy.plot.LifetimePlots(frequency, lifetime, fraction=None, *, frequency_range=(10.0, 200.0, 1.0), lifetime_range=(0.0, 20.0, 0.1), interactive=False, **kwargs)[source]#

Plot lifetimes in time domain, frequency domain, and phasor plot.

Plot the time domain signals, phasor coordinates, and multi-frequency phase and modulation curves for a set of lifetime components and their mixture at given frequency and fractional intensities.

Parameters:

  • frequency (float) – Fundamental laser pulse or modulation frequency in MHz. If None, an optimal frequency is calculated from the mean of the lifetime components.

  • lifetime (array_like) – Lifetime components in ns. Up to 6 components are supported.

  • fraction (array_like, optional) – Fractional intensities of lifetime components. Fractions are normalized to sum to 1. If not given, all components are assumed to have equal fractions.

  • frequency_range (tuple[float, float, float], optional) – Range of frequencies in MHz for frequency slider. Default is (10.0, 200.0, 1.0).

  • lifetime_range (tuple[float, float, float], optional) – Range of lifetimes in ns for lifetime sliders. Default is (0.0, 20.0, 0.1).

  • interactive (bool) – If True, add sliders to change frequency and lifetimes interactively. Default is False.

  • **kwargs – Additional arguments passed to matplotlib figure.

show()[source]#

Display all open figures. Call matplotlib.pyplot.show().

class phasorpy.plot.PhasorPlot(allquadrants=None, ax=None, *, frequency=None, grid=None, pad=None, **kwargs)[source]#

Phasor plot.

Create publication quality visualizations of phasor coordinates.

Parameters:

  • allquadrants (bool, optional) – Show all quadrants of phasor space. By default, only the first quadrant with universal semicircle is shown.

  • ax (matplotlib.axes.Axes, optional) – Matplotlib axes used for plotting. By default, a new subplot axes is created.

  • frequency (float, optional) – Laser pulse or modulation frequency in MHz.

  • pad (float, optional) – Padding around the plot. The default is 0.05.

  • grid (dict or bool, optional) – Display universal semicircle (default) or polar grid (allquadrants). If False, no grid is displayed. If a dictionary, it is passed to PhasorPlot.polar_grid() or PhasorPlot.semicircle().

  • **kwargs – Additional properties to set on ax.

See also

phasorpy.plot.plot_phasor, Phasor plot

arrow(point0, point1, /, *, angle=None, **kwargs)[source]#

Draw arrow between points.

By default, draw a straight arrow with a '-|>' style, a mutation scale of 20, and a miter join style.

Parameters:

  • point0 (array_like) – X and y coordinates of start point of arrow.

  • point1 (array_like) – X and y coordinates of end point of arrow.

  • angle (float, optional) – Angle in radians, controlling curvature of line between points. If None (default), draw a straight line.

  • **kwargs – Additional parameters passed to matplotlib.patches.FancyArrowPatch.

property ax#

Matplotlib matplotlib.axes.Axes.

circle(real, imag, /, radius, **kwargs)[source]#

Draw grid circle of radius around center.

Parameters:

  • real (float) – Real component of circle center coordinate.

  • imag (float) – Imaginary component of circle center coordinate.

  • radius (float) – Circle radius.

  • **kwargs – Additional parameters passed to matplotlib.patches.Circle.

components(real, imag, /, fraction=None, labels=None, label_offset=None, **kwargs)[source]#

Plot linear combinations of phasor coordinates or ranges thereof.

Parameters:

  • real ((N,) array_like) – Real component of phasor coordinates.

  • imag ((N,) array_like) – Imaginary component of phasor coordinates.

  • fraction ((N,) array_like, optional) – Weight associated with each component. If None (default), outline the polygon area of possible linear combinations of components. Else, draw lines from the component coordinates to the weighted average.

  • labels (Sequence of str, optional) – Text label for each component.

  • label_offset (float, optional) – Distance of text label to component coordinate.

  • **kwargs – Additional parameters passed to matplotlib.patches.Polygon, matplotlib.lines.Line2D, or matplotlib.axes.Axes.annotate

contour(real, imag, /, **kwargs)[source]#

Plot contours of imag versus real coordinates (not implemented).

Parameters:

  • real (array_like) – Real component of phasor coordinates.

  • imag (array_like) – Imaginary component of phasor coordinates. Must be of same shape as real.

  • **kwargs – Additional parameters passed to numpy.histogram2d() and matplotlib.axes.Axes.contour().

cursor(real, imag, real_limit=None, imag_limit=None, /, *, radius=None, radius_minor=None, angle=None, color=None, label=None, crosshair=False, polar=False, **kwargs)[source]#

Draw cursor(s) at phasor coordinates.

Parameters:

  • real (array_like) – Real component of phasor coordinate.

  • imag (array_like) – Imaginary component of phasor coordinate.

  • real_limit (array_like, optional) – Real component of limiting phasor coordinate.

  • imag_limit (array_like, optional) – Imaginary component of limiting phasor coordinate.

  • radius (array_like, optional) – Radius of circular cursor.

  • radius_minor (array_like, optional) – Radius of elliptic cursor along semi-minor axis. By default, radius_minor is equal to radius, that is, the ellipse is circular.

  • angle (array_like or {'phase', 'semicircle'}, optional) – Rotation angle of semi-major axis of elliptic cursor in radians. If None or ‘phase’, align the minor axis of the ellipse with the closest tangent on the unit circle. If ‘semicircle’, align the ellipse with the universal semicircle.

  • color (array_like, optional) – Color of cursor.

  • label (array_like, optional) – String label for cursor.

  • crosshair (bool, optional) – If true, draw polar or Cartesian lines or arcs limited by radius. Else, draw circle or ellipse (default). Only applies if radius is provided.

  • polar (bool, optional) – If true, draw phase line and modulation arc. Else, draw Cartesian lines.

  • **kwargs – Additional parameters passed to matplotlib.lines.Line2D, matplotlib.patches.Circle, matplotlib.patches.Ellipse, or matplotlib.patches.Arc.

See also

phasorpy.plot.PhasorPlot.polar_cursor

property dataunit_to_point#

Factor to convert data to point unit.

property fig#

Matplotlib matplotlib.figure.Figure.

hist2d(real, imag, /, **kwargs)[source]#

Plot two-dimensional histogram of imag versus real coordinates.

Parameters:

  • real (array_like) – Real component of phasor coordinates.

  • imag (array_like) – Imaginary component of phasor coordinates. Must be of same shape as real.

  • **kwargs – Additional parameters passed to numpy.histogram2d() and matplotlib.axes.Axes.pcolormesh().

imshow(image, /, **kwargs)[source]#

Plot an image, for example, a 2D histogram (not implemented).

This method is not yet implemented and raises NotImplementedError.

Parameters:

  • image (array_like) – Image to display.

  • **kwargs – Additional parameters passed to matplotlib.axes.Axes.imshow().

legend(**kwargs)[source]#

Add legend to plot.

Parameters:

**kwargs – Keyword arguments passed to matplotlib.axes.Axes.legend().

line(real, imag, /, **kwargs)[source]#

Draw grid line.

Parameters:

  • real (array_like, shape (n, )) – Real components of line start and end coordinates.

  • imag (array_like, shape (n, )) – Imaginary components of line start and end coordinates.

  • **kwargs – Additional parameters passed to matplotlib.lines.Line2D.

Returns:

List containing plotted line.

Return type:

list[matplotlib.lines.Line2D]

plot(real, imag, /, fmt='o', *, label=None, **kwargs)[source]#

Plot imaginary versus real coordinates as markers or lines.

Parameters:

  • real (array_like) – Real component of phasor coordinates. Must be one or two dimensional.

  • imag (array_like) – Imaginary component of phasor coordinates. Must be of same shape as real.

  • fmt (str, optional, default: 'o') – Matplotlib style format string.

  • label (sequence of str, optional) – Plot label. May be a sequence if phasor coordinates are two dimensional arrays.

  • **kwargs – Additional parameters passed to matplotlib.axes.Axes.plot().

Returns:

Lines representing data plotted last.

Return type:

list[matplotlib.lines.Line2D]

polar_cursor(phase=None, modulation=None, phase_limit=None, modulation_limit=None, *, radius=None, radius_minor=None, angle=None, color=None, label=None, crosshair=False, polar=True, **kwargs)[source]#

Draw cursor(s) at polar coordinates.

Parameters:

  • phase (array_like, optional) – Angular component of polar coordinate in radians.

  • modulation (array_like, optional) – Radial component of polar coordinate.

  • phase_limit (array_like, optional) – Angular component of limiting polar coordinate (in radians). Modulation arcs are drawn between phase and phase_limit if polar is true.

  • modulation_limit (array_like, optional) – Radial component of limiting polar coordinate. Phase lines are drawn from modulation to modulation_limit if polar is true.

  • radius (array_like, optional) – Radius of circular cursor.

  • radius_minor (array_like, optional) – Radius of elliptic cursor along semi-minor axis. By default, radius_minor is equal to radius, that is, the ellipse is circular.

  • angle (array_like or {'phase', 'semicircle'}, optional) – Rotation angle of semi-major axis of elliptic cursor in radians. If None or ‘phase’, align the minor axis of the ellipse with the closest tangent on the unit circle. If ‘semicircle’, align the ellipse with the universal semicircle.

  • color (array_like, optional) – Color of cursor.

  • label (array_like, optional) – String label for cursor.

  • crosshair (bool, optional) – If true, draw polar or Cartesian lines or arcs limited by radius. Else, draw circle or ellipse (default). Only applies if radius is provided.

  • polar (bool, optional) – If true, draw phase line and modulation arc. Else, draw Cartesian lines.

  • **kwargs – Additional parameters passed to matplotlib.lines.Line2D, matplotlib.patches.Circle, matplotlib.patches.Ellipse, or matplotlib.patches.Arc.

See also

phasorpy.plot.PhasorPlot.cursor

polar_grid(radii=None, angles=None, samples=None, labels=None, ticks=None, tick_space=None, tick_format=None, **kwargs)[source]#

Draw polar coordinate system.

Parameters:

  • radii (int or sequence of float, optional) – Position of radial gridlines in range (0, 1]. If an integer, the number of equidistant radial gridlines. By default, three equidistant radial gridlines are drawn. The unit circle (radius 1), if included, is drawn in major style.

  • angles (int or sequence of float, optional) – Position of angular gridlines in range [0, 2 pi]. If an integer, the number of equidistant angular gridlines. By default, 12 equidistant angular gridlines are drawn.

  • samples (int, optional) – Number of vertices of polygon inscribed in unit circle. By default, no inscribed polygon is drawn.

  • labels (sequence of str, optional) – Tick labels on unit circle. Labels are placed at equidistant angles if ticks are not provided.

  • ticks (array_like, optional) – Values at which to place tick labels on unit circle. If labels are not provided, ticks values formatted with tick_format are used as labels. If tick_space is not provided, tick values are angles in radians.

  • tick_space (array_like, optional) – Values used to convert ticks to angles. For example, the wavelengths used to calculate spectral phasors or the minimum and maximum wavelengths of a sine-cosine filter.

  • tick_format (str, optional) – Format string for tick values if labels is None. By default, the tick format is “{}”.

  • **kwargs – Parameters passed to matplotlib.patches.Circle and matplotlib.lines.Line2D.

Raises:

ValueError – If number of ticks doesn’t match number of labels. If tick_space has less than two values.

Notes

Use radii=1, angles=4 to draw major gridlines only.

The values of ticks (\(v\)) are converted to angles (\(\theta\)) using tick_space (\(s\)) according to:

\[\theta = \frac{v - s_0}{s_{-1} + s_1 - 2 s_0} \cdot 2 \pi\]
save(file, /, **kwargs)[source]#

Save current figure to file.

Parameters:

  • file (str, path-like, or binary file-like) – Path or Python file-like object to write the current figure to.

  • **kwargs – Additional keyword arguments passed to matplotlib:pyplot.savefig().

semicircle(frequency=None, *, polar_reference=None, phasor_reference=None, lifetime=None, labels=None, show_circle=True, use_lines=False, **kwargs)[source]#

Draw universal semicircle.

Parameters:

  • frequency (float, optional) – Laser pulse or modulation frequency in MHz.

  • polar_reference ((float, float), optional, default: (0, 1)) – Polar coordinates of zero lifetime.

  • phasor_reference ((float, float), optional, default: (1, 0)) – Phasor coordinates of zero lifetime. Alternative to polar_reference.

  • lifetime (sequence of float, optional) – Single component lifetimes at which to draw ticks and labels. Only applies when frequency is specified.

  • labels (sequence of str, optional) – Tick labels. By default, the values of lifetime. Only applies when frequency and lifetime are specified.

  • show_circle (bool, optional, default: True) – Draw universal semicircle.

  • use_lines (bool, optional, default: False) – Draw universal semicircle using lines instead of arc.

  • **kwargs – Additional parameters passed to matplotlib.lines.Line2D or matplotlib.patches.Arc and matplotlib.axes.Axes.plot().

Returns:

Lines representing plotted semicircle and ticks.

Return type:

list of matplotlib.lines.Line2D

show()[source]#

Display all open figures. Call matplotlib.pyplot.show().

class phasorpy.plot.PhasorPlotFret(*, frequency=60.0, donor_lifetime=4.2, acceptor_lifetime=3.0, fret_efficiency=0.5, donor_fretting=1.0, donor_bleedthrough=0.0, acceptor_bleedthrough=0.0, acceptor_background=0.0, donor_background=0.0, background_real=0.0, background_imag=0.0, ax=None, interactive=False, **kwargs)[source]#

FRET phasor plot.

Plot Förster Resonance Energy Transfer efficiency trajectories of donor and acceptor channels in phasor space.

Parameters:

  • frequency (array_like) – Laser pulse or modulation frequency in MHz.

  • donor_lifetime (array_like) – Lifetime of donor without FRET in ns.

  • acceptor_lifetime (array_like) – Lifetime of acceptor in ns.

  • fret_efficiency (array_like, optional, default 0) – FRET efficiency in range [0, 1].

  • donor_fretting (array_like, optional, default 1) – Fraction of donors participating in FRET. Range [0, 1].

  • donor_bleedthrough (array_like, optional, default 0) – Weight of donor fluorescence in acceptor channel relative to fluorescence of fully sensitized acceptor. A weight of 1 means the fluorescence from donor and fully sensitized acceptor are equal. The background in the donor channel does not bleed through.

  • acceptor_bleedthrough (array_like, optional, default 0) – Weight of fluorescence from directly excited acceptor relative to fluorescence of fully sensitized acceptor. A weight of 1 means the fluorescence from directly excited acceptor and fully sensitized acceptor are equal.

  • acceptor_background (array_like, optional, default 0) – Weight of background fluorescence in acceptor channel relative to fluorescence of fully sensitized acceptor. A weight of 1 means the fluorescence of background and fully sensitized acceptor are equal.

  • donor_background (array_like, optional, default 0) – Weight of background fluorescence in donor channel relative to fluorescence of donor without FRET. A weight of 1 means the fluorescence of background and donor without FRET are equal.

  • background_real (array_like, optional, default 0) – Real component of background fluorescence phasor coordinate at frequency.

  • background_imag (array_like, optional, default 0) – Imaginary component of background fluorescence phasor coordinate at frequency.

  • ax (matplotlib axes, optional) – Matplotlib axes used for plotting. By default, a new subplot axes is created. Cannot be used with interactive mode.

  • interactive (bool, optional, default: False) – Use matplotlib slider widgets to interactively control parameters.

  • **kwargs – Additional parameters passed to phasorpy.plot.PhasorPlot.

See also

phasorpy.phasor.phasor_from_fret_donor, phasorpy.phasor.phasor_from_fret_acceptor, Förster Resonance Energy Transfer

phasorpy.plot.plot_histograms(*data, title=None, xlabel=None, ylabel=None, labels=None, show=True, **kwargs)[source]#

Plot histograms of flattened data arrays.

Parameters:

  • *data (array_like) – Data arrays to be plotted as histograms.

  • title (str, optional) – Figure title.

  • xlabel (str, optional) – Label for x-axis.

  • ylabel (str, optional) – Label for y-axis.

  • labels (sequence of str, optional) – Labels for each data array.

  • show (bool, optional, default: True) – Display figure.

  • **kwargs – Additional arguments passed to matplotlib.pyplot.hist().

phasorpy.plot.plot_image(*images, percentile=None, columns=None, title=None, labels=None, show=True, **kwargs)[source]#

Plot images.

Parameters:

  • *images (array_like) – Images to be plotted. Must be two or more dimensional. The last two axes are assumed to be the image axes. Other axes are averaged for display. Three-dimensional images with last axis size of three or four are plotted as RGB(A) images.

  • percentile (float, optional) – The (q, 100-q) percentiles of image data are covered by colormaps. By default, the complete value range is covered. Does not apply to RGB images.

  • columns (int, optional) – Number of columns in figure. By default, up to four columns are used.

  • title (str, optional) – Figure title.

  • labels (sequence of str, optional) – Labels for each image.

  • show (bool, optional, default: True) – Display figure.

  • **kwargs – Additional arguments passed to matplotlib.pyplot.imshow().

Raises:

ValueError – Percentile is out of range.

phasorpy.plot.plot_phasor(real, imag, /, *, style=None, allquadrants=None, frequency=None, show=True, **kwargs)[source]#

Plot phasor coordinates.

A simplified interface to the PhasorPlot class.

Parameters:

  • real (array_like) – Real component of phasor coordinates.

  • imag (array_like) – Imaginary component of phasor coordinates. Must be of same shape as real.

  • style ({'plot', 'hist2d', 'contour'}, optional) – Method used to plot phasor coordinates. By default, if the number of coordinates are less than 65536 and the arrays are less than three-dimensional, ‘plot’ style is used, else ‘hist2d’.

  • allquadrants (bool, optional) – Show all quadrants of phasor space. By default, only the first quadrant is shown.

  • frequency (float, optional) – Frequency of phasor plot. If provided, the universal semicircle is labeled with reference lifetimes.

  • show (bool, optional, default: True) – Display figure.

  • **kwargs – Additional arguments passed to PhasorPlot, PhasorPlot.plot(), PhasorPlot.hist2d(), or PhasorPlot.contour() depending on style.

Raises:

ValueError – If style is not one of ‘plot’, ‘hist2d’, or ‘contour’.

See also

phasorpy.plot.PhasorPlot, Phasor plot

phasorpy.plot.plot_phasor_image(mean, real, imag, *, harmonics=None, percentile=None, title=None, show=True, **kwargs)[source]#

Plot phasor coordinates as images.

Preview phasor coordinates from time-resolved or hyperspectral image stacks as returned by phasorpy.phasor.phasor_from_signal().

The last two axes are assumed to be the image axes. Harmonics, if any, are in the first axes of real and imag. Other axes are averaged for display.

Parameters:

  • mean (array_like) – Image average. Must be two or more dimensional, or None.

  • real (array_like) – Image of real component of phasor coordinates. The last dimensions must match shape of mean.

  • imag (array_like) – Image of imaginary component of phasor coordinates. Must be same shape as real.

  • harmonics (int, optional) – Number of harmonics to display. If mean is None, a nonzero value indicates the presence of harmonics in the first axes of mean and real. Else, the presence of harmonics is determined from the shapes of mean and real. By default, up to 4 harmonics are displayed.

  • percentile (float, optional) – The (q, 100-q) percentiles of image data are covered by colormaps. By default, the complete value range of mean is covered, for real and imag the range [-1, 1].

  • title (str, optional) – Figure title.

  • show (bool, optional, default: True) – Display figure.

  • **kwargs – Additional arguments passed to matplotlib.pyplot.imshow().

Raises:

ValueError – The shapes of mean, real, and image do not match. Percentile is out of range.

phasorpy.plot.plot_polar_frequency(frequency, phase, modulation, *, ax=None, title=None, show=True, **kwargs)[source]#

Plot phase and modulation verus frequency.

Parameters:

  • frequency (array_like, shape (n, )) – Laser pulse or modulation frequency in MHz.

  • phase (array_like) – Angular component of polar coordinates in radians.

  • modulation (array_like) – Radial component of polar coordinates.

  • ax (matplotlib axes, optional) – Matplotlib axes used for plotting. By default, a new subplot axes is created.

  • title (str, optional) – Figure title. The default is “Multi-frequency plot”.

  • show (bool, optional, default: True) – Display figure.

  • **kwargs – Additional arguments passed to matplotlib.pyplot.plot().

phasorpy.plot.plot_signal_image(signal, /, *, axis=None, percentile=None, title=None, xlabel=None, show=True, **kwargs)[source]#

Plot average image and signal along axis.

Preview time-resolved or hyperspectral image stacks to be anayzed with phasorpy.phasor.phasor_from_signal().

The last two axes, excluding axis, are assumed to be the image axes. Other axes are averaged for image display.

Parameters:

  • signal (array_like) – Image stack. Must be three or more dimensional.

  • axis (int or str, optional) – Axis over which phasor coordinates would be computed. By default, the ‘H’ or ‘C’ axes if signal contains such dimension names, else the last axis (-1).

  • percentile (float or [float, float], optional) – The [q, 100-q] percentiles of image data are covered by colormaps. By default, the complete value range of mean is covered, for real and imag the range [-1, 1].

  • title (str, optional) – Figure title.

  • xlabel (str, optional) – Label of axis over which phasor coordinates would be computed.

  • show (bool, optional, default: True) – Display figure.

  • **kwargs – Additional arguments passed to matplotlib.pyplot.imshow().

Raises:

ValueError – Signal is not an image stack. Percentile is out of range.