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 space.

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) – 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. The default is (10.0, 200.0, 1.0).

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

  • interactive (bool, optional, default: False) – Add sliders to change frequency and lifetimes interactively.

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

See also

Interactive apps

show()[source]#

Show 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 the 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) – Show universal semicircle (default) or polar grid (allquadrants). If False, do not show any grid. 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. By default, draw a straight line.

  • **kwargs – Optional arguments 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 – Optional arguments 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. By 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 – Optional arguments 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 yet).

Parameters:

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

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

  • **kwargs – Optional arguments 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 elliptical 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 elliptical cursor in radians. If ‘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. The default is ‘phase’

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

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

  • crosshair (bool, optional, default: False) – Draw polar or Cartesian lines or arcs limited by radius instead of circle or ellipse. Only applies if radius is provided.

  • polar (bool, optional, default: False) – Draw phase line and modulation arc instead of Cartesian lines.

  • **kwargs – Optional arguments 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 have the same shape as real.

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

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

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

This method is not implemented yet and raises NotImplementedError.

Parameters:

  • image (array_like) – Image to show.

  • **kwargs – Optional arguments passed to matplotlib.axes.Axes.imshow().

legend(**kwargs)[source]#

Add legend to plot.

Parameters:

**kwargs – Optional 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 – Optional arguments 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 have the 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 – Optional arguments 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 elliptical 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 elliptical cursor in radians. If ‘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. The default is ‘phase’.

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

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

  • crosshair (bool, optional, default: False) – Draw polar or Cartesian lines or arcs limited by radius instead of circle or ellipse. Only applies if radius is provided.

  • polar (bool, optional, default: False) – Draw phase line and modulation arc instead of 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 – Optional arguments 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 – Optional 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 – Optional arguments 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]#

Show 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 (FRET) 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 signal in acceptor channel relative to signal of fully sensitized acceptor. A weight of 1 means the signal 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 signal from directly excited acceptor relative to signal of fully sensitized acceptor. A weight of 1 means the signal from directly excited acceptor and fully sensitized acceptor are equal.

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

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

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

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

  • ax (matplotlib.axes.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 – Optional arguments passed to phasorpy.plot.PhasorPlot.

See also

phasorpy.lifetime.phasor_from_fret_donor, phasorpy.lifetime.phasor_from_fret_acceptor, Förster resonance energy transfer, Interactive apps

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. By default, no title is set.

  • 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) – Show figure.

  • **kwargs – Optional 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. By default, no title is set.

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

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

  • **kwargs – Optional 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 have the same shape as real.

  • style ({'plot', 'hist2d', 'contour'}, optional) – Method used to plot phasor coordinates. By default, if the number of coordinates is 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, show only the first quadrant.

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

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

  • **kwargs – Optional 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 axis 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 the 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 show. If mean is None, a nonzero value indicates the presence of harmonics in the first axis of mean and real. Else, the presence of harmonics is determined from the shapes of mean and real. By default, up to four harmonics are shown.

  • 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. By default, no title is set.

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

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

Raises:

ValueError – The shapes of mean, real, and imag 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 versus 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.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) – Show figure.

  • **kwargs – Optional 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 analyzed 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. By default, no title is set.

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

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

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

Raises:

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