pyfli.phasor.phasorS.phasor_additional_plots#

Provide supplementary phasor plots as a PhasorAnalyzer subclass.

This module belongs to pyfli.phasor.phasorS and is part of PyFLI’s compact phasor analyzer for CPU and optional GPU FLI workflows. Public API includes the class PhasorAdditionalPlots.

Classes

PhasorAdditionalPlots(frequency_hz, time_axis_ns)

Extra phasor visualizations layered on top of PhasorAnalyzer.
class PhasorAdditionalPlots(frequency_hz, time_axis_ns, n_harmonics=1, device=None)[source]#

Bases: PhasorAnalyzer

Extra phasor visualizations layered on top of PhasorAnalyzer.

An instance is a full phasor analyzer (compute, calibrate, lifetime conversion, and every PhasorPlotsMixin plot) plus:

  • phasorlifetime_to_phasor() – the phase-lifetime map beside the matching phasor scatter, sharing one colormap so a pixel’s color and its phasor point’s color are identical.

  • phasor_kde_to_px() – the filled kernel-density regions of the phasor cloud carried back onto the grayscale intensity image.

Construction matches PhasorAnalyzer (frequency_hz, time_axis_ns, n_harmonics, device).

Parameters:
phasorlifetime_to_phasor(Gc, Sc, boolean_mask=None, cmap='jet', cmap_scale=(0.0, 5.0), harmonic=0, axes=None, figsize=(14, 6), half_circle=True, xlim=(-0.1, 1.1), ylim=(0.0, 0.6), point_size=6.0, background='black', title='Phasor Lifetime')[source]#

Plot the phase-lifetime map beside its matching phasor scatter.

Panel (0, 0) is the per-pixel phase-lifetime map (compute_lifetime() of the calibrated coordinates) shown with imshow using cmap and vmin, vmax = cmap_scale; pixels outside boolean_mask or with an undefined lifetime render in background. Panel (0, 1) scatters the calibrated phasor points (Gc[harmonic], Sc[harmonic]) for the masked pixels, colored through the same cmap and Normalize(vmin, vmax) as the map, so a pixel’s color and its phasor point’s color are identical.

Parameters:

  • Gc (np.ndarray) – Calibrated phasor real coordinate. Either a (H, W) map or a (n_harmonics, H, W) stack (the harmonic slice is used).

  • Sc (np.ndarray) – Calibrated phasor imaginary coordinate, matching Gc.

  • boolean_mask (np.ndarray | None) – Boolean (H, W) mask selecting the pixels to display and scatter. When None every pixel is used.

  • cmap (str | matplotlib.colors.Colormap) – Colormap shared by the lifetime map and the phasor scatter.

  • cmap_scale (tuple[float, float]) – (vmin, vmax) in nanoseconds; vmin, vmax = cmap_scale[0], cmap_scale[1].

  • harmonic (int) – Harmonic slice used when Gc/Sc are 3-D stacks (0 is the first harmonic).

  • axes (Any | None) – Length-2 sequence of Matplotlib axes (map_ax, scatter_ax). A new 1x2 figure is created when None.

  • figsize (tuple[float, float]) – Figure size used when a new figure is created.

  • half_circle (bool) – Whether to draw only the upper half of the universal phasor circle.

  • xlim (tuple[float, float]) – Axis limits for the phasor scatter panel.

  • ylim (tuple[float, float]) – Axis limits for the phasor scatter panel.

  • point_size (float) – Marker size for the phasor scatter points.

  • background (str) – Color used for masked / undefined pixels in the lifetime map.

  • title (str) – Base title; panel titles are derived from it.

Returns:

The Matplotlib figure containing both panels.

Return type:

Any

phasor_kde_to_px(Gc, Sc, decay, boolean_mask=None, hexbin_color='autumn', harmonic=0, kde_levels=3, kde_color='red', kde_linewidths=1.0, kde_alpha=0.5, kde_thresh=0.05, fill_alpha=0.4, gridsize=200, bw_method=None, region_cmap='tab10', peak_footprint=None, min_peak_height=0.1, max_centers=8, axes=None, figsize=(14, 5), half_circle=True, xlim=(-0.1, 1.1), ylim=(0.0, 0.6), title='Phasor KDE')[source]#

Fill KDE regions on a phasor plot and carry those colors back to pixels.

Panel (0, 0) reproduces the usual phasor diagram (PhasorPlotsMixin.plot_phasor_diagram(): hexbin density, universal semicircle, lifetime ticks), overlays the KDE iso-density contour lines (like kdeplot=True, in kde_color), and then fills the kernel-density regions of the masked phasor cloud. Filled bands run from the innermost (highest density) outward; when the KDE has several modes each mode’s territory is filled with its own clearly distinct color, so every (mode, level) region is a unique color (drawn at fill_alpha).

Panel (0, 1) shows the grayscale intensity image np.sum(decay, axis=-1). Every masked pixel whose phasor point lands in a filled KDE region is tinted, at fill_alpha, with that region’s color, so the phasor-space grouping is projected back onto the image.

Parameters:

  • Gc (np.ndarray) – Calibrated phasor real coordinate, a (H, W) map or a (n_harmonics, H, W) stack.

  • Sc (np.ndarray) – Calibrated phasor imaginary coordinate, matching Gc.

  • decay (np.ndarray) – Decay cube (H, W, T); the intensity image is np.sum(decay, -1).

  • boolean_mask (np.ndarray | None) – Boolean (H, W) mask selecting the pixels fed to the KDE and tinted in the overlay. When None every finite pixel is used.

  • hexbin_color (str) – Colormap for the phasor hexbin density in panel (0, 0).

  • harmonic (int) – Harmonic slice used when Gc/Sc are 3-D stacks.

  • kde_levels (int) – Number of iso-proportion KDE contour levels (as in seaborn.kdeplot).

  • kde_color (str) – Color of the KDE contour lines.

  • kde_linewidths (float) – Width of the KDE contour lines.

  • kde_alpha (float) – Opacity of the KDE contour lines.

  • kde_thresh (float) – Lowest enclosed-mass proportion contoured (seaborn’s thresh).

  • fill_alpha (float) – Opacity of the region fills and of the pixel tint in the overlay.

  • gridsize (int) – Resolution of the square grid the KDE is evaluated on.

  • bw_method (Any | None) – Bandwidth selector passed to scipy.stats.gaussian_kde.

  • region_cmap (str) – Preferred qualitative colormap for the distinct region colors.

  • peak_footprint (int | None) – Neighborhood size, in grid cells, for the local-maximum search that locates KDE modes. Defaults to max(3, gridsize // 20).

  • min_peak_height (float) – A density local maximum counts as a KDE mode only when it exceeds this fraction of the global peak density (rejects tail noise bumps).

  • max_centers (int | None) – Cap on the number of KDE modes kept (strongest first); None keeps all of them.

  • axes (Any | None) – Length-2 sequence of axes (phasor_ax, overlay_ax); a new 1x2 figure is created when None.

  • figsize (tuple[float, float]) – Figure size used when a new figure is created.

  • half_circle (bool) – Whether to draw only the upper half of the universal phasor circle.

  • xlim (tuple[float, float]) – Axis limits for the phasor panel.

  • ylim (tuple[float, float]) – Axis limits for the phasor panel.

  • title (str) – Base title; panel titles are derived from it.

Returns:

The Matplotlib figure containing both panels.

Return type:

Any

multidata_phasor_plot(gs_list, labels=None, colors=None, harmonic=0, region_cmap='tab10', ax=None, figsize=(8, 6), half_circle=True, xlim=(-0.1, 1.1), ylim=(0.0, 0.6), title='Multi-dataset Phasor', legend=True)[source]#

Scatter several phasor clouds on one shared phasor diagram.

Each (G, S) pair in gs_list is raveled to points and drawn on a single diagram produced by PhasorPlotsMixin.plot_phasor_diagram() (universal semicircle, lifetime ticks, frequency label, axis styling). Every dataset is handed to that one call as a concatenated point cloud together with a matching per-point RGB array, so each dataset keeps its own distinct color; a legend then maps the colors back to labels.

Parameters:

  • gs_list (list[tuple[np.ndarray, np.ndarray]]) – One (G, S) pair per dataset. Each array is either a (H, W) map or a (n_harmonics, H, W) stack (the harmonic slice is used); the datasets need not share a shape.

  • labels (list[str] | None) – Legend label for each dataset. Defaults to ["dataset 1", ...].

  • colors (Any | None) – Explicit color per dataset (anything matplotlib.colors.to_rgb() accepts). When None, visually distinct colors are taken from region_cmap via _distinct_colors().

  • harmonic (int) – Harmonic slice used for any 3-D G/S stack (0 is the first harmonic).

  • region_cmap (str) – Qualitative colormap the automatic per-dataset colors come from.

  • ax (Any | None) – Axes to draw into. A new figure/axes is created when None.

  • figsize (tuple[float, float]) – Figure size used when a new figure is created.

  • half_circle (bool) – Whether to draw only the upper half of the universal phasor circle.

  • xlim (tuple[float, float]) – Axis limits for the phasor panel.

  • ylim (tuple[float, float]) – Axis limits for the phasor panel.

  • title (str) – Title for the phasor diagram.

  • legend (bool) – Whether to draw the color-to-label legend.

Returns:

The Matplotlib figure containing the phasor diagram.

Return type:

Any