Plotting#

Matplotlib-based plotters with no global pyplot state, so they embed cleanly in the GUI and in your own figures. Reusable single-axis plotters plus the 12-, 6- and 4-panel composites. See Post-processing and plotting.

Matplotlib plotting for retrieval results.

Provides custom colormaps (white at the low end; a red band for negatives), reusable single-axis plotters (so the GUI embeds exactly the same code), and composite figures: the 12-panel plot_retrieval(), the 6-panel plot_frog_filter(), and plot_simulated_trace().

The retrieval summary is assembled from twelve independent panels (draw_<key>(ax, data) over one RetrievalPlotData bundle, registered in RETRIEVAL_PANELS). plot_retrieval() lays them out as the 3×4 overview; plot_retrieval_page() draws one of the three 2×2 pages (RETRIEVAL_PAGES: Traces, Pulse, Diagnostics) the GUI shows as tabs.

Figures are built with matplotlib.figure.Figure directly (no pyplot global state), so they embed cleanly in a Qt canvas and also save standalone via fig.savefig(...).

class croak.plotting.PlotScale(font=1.0)[source]#

Bases: object

Text density of a figure relative to the size its layout was designed for.

Parameters:: font (float) – Multiplier applied to every rc font size (and text padding), in [FONT_SCALE_MIN, 1.0]. 1.0 is matplotlib’s default 10 pt base.

Examples

>>> PlotScale(0.85).compact
True
>>> FULL_SCALE.compact
False

property compact: bool#: Whether the figure is tight enough to drop optional decoration.

croak.plotting.FULL_SCALE = PlotScale(font=1.0)#

matplotlib’s defaults.

Type:: The unscaled density

croak.plotting.FONT_SCALE_MIN = 0.7#: Smallest fraction of the design font size that text may shrink to. Below ~70 % a 10 pt label is 7 pt, the limit of comfortable legibility on a laptop panel.

croak.plotting.FONT_SCALE_STEP = 0.05#: Quantisation step of plot_scale(). A window resize re-plots only when the scale crosses a step, so a few pixels of drag never trigger a redraw.

croak.plotting.COMPACT_BELOW = 0.9#: Below this scale PlotScale.compact is set, for plotting code that wants to drop optional decoration (a second legend entry, a colorbar label) when tight.

croak.plotting.plot_scale(width_in, height_in, design_in)[source]#

Return the text density for a figure of the given size.

The scale is the fraction of the design size that fits in the tighter direction, min(width / design_width, height / design_height), quantised to FONT_SCALE_STEP and clamped to [FONT_SCALE_MIN, 1.0]. A figure at or above its design size is drawn at full scale; one squeezed to 60 % of its design height gets the minimum.

Parameters:

width_in (float) – Current figure size in inches (Figure.get_size_inches()). On a Qt canvas this is the logical pixel size / 100 on every display, because matplotlib folds the device-pixel ratio into figure.dpi.
height_in (float) – Current figure size in inches (Figure.get_size_inches()). On a Qt canvas this is the logical pixel size / 100 on every display, because matplotlib folds the device-pixel ratio into figure.dpi.
design_in (tuple of float) – (width, height) in inches the figure’s layout was designed for — the figsize a stage passes to its canvas.

Returns:

PlotScale

Raises:

ValueError – If any size is not positive.

Return type:

PlotScale

Examples

>>> plot_scale(9.91, 4.21, (12.0, 7.0)).font   # Retrieve page at 1366x768
0.7
>>> plot_scale(15.45, 7.33, (12.0, 7.0)).font  # ... at 1920x1080
1.0

croak.plotting.scaled_rc(scale)[source]#

Return rcParams overrides that shrink every font size and pad by scale.

Use with matplotlib.rc_context() around the plotting call: matplotlib resolves relative sizes (fontsize="small", the 'large' title default) against font.size when an artist is created, not when it is drawn, so the context must enclose everything that creates text.

Parameters:: scale (PlotScale) – The density; FULL_SCALE reproduces matplotlib’s defaults.
Returns:: dict – {rc key: value in points} for the font-size and padding keys.
Return type:: dict[str, float]

Examples

>>> round(scaled_rc(PlotScale(0.7))["axes.titlesize"], 2)
8.4

croak.plotting.cmap_white(base='viridis', *, n=8, white=True, N=512)[source]#

Build a base colormap with (optionally) a white point at the low end.

Parameters:

base (str)
n (int)
white (bool)
N (int)

croak.plotting.cmap_negwhite(base='viridis', *, n=8, white=True, negfrac=0.0, N=512)[source]#

Like cmap_white() but with a red gradient for negative values.

Parameters:

base (str)
n (int)
white (bool)
negfrac (float)
N (int)

croak.plotting.signed_pcolormesh(ax, x, y, C, *, db, tracedb=30.0, cmap_pos, vmax=None)[source]#

Pcolormesh that splits an image’s sign onto two colormaps.

Positive samples are drawn with cmap_pos (e.g. viridis); negative samples are drawn by magnitude with a white→red map. Both maps share the same scale ([0, vmax] linear, [-tracedb, 0] dB), so a negative is only as saturated as a positive of equal magnitude — small negatives stay faint instead of dominating — and zero is white in both (pair cmap_pos with cmap_white()). C follows the usual pcolormesh() convention — shape (len(y), len(x)) (a FROG (Nλ, Nτ) array already has this shape for x = delay and y = wavelength).

Returns (mappable_pos, mappable_neg) (the second is None when there are no negative samples).

croak.plotting.si_power(watts)[source]#

Return (scale, unit) to display watts with an SI power prefix.

Picks the largest prefix not exceeding |watts| (so e.g. 1.2e7 W → (1e6, "MW")). Non-finite or non-positive inputs fall back to plain watts; values below the smallest prefix use that smallest prefix.

Parameters:: watts (float)
Return type:: tuple[float, str]

croak.plotting.sig3(value)[source]#

Format a number to three significant digits, for a read-out.

Three significant digits keeps a read-out equally informative across the ranges croak covers (sub-fs attosecond pulses through hundreds of fs; nanometre-wide through hundred-nanometre-wide spectra), where a fixed number of decimals is too coarse at one end and spuriously precise at the other. Unlike the g format this keeps trailing zeros (so 7.00, not 7) and never switches to exponent notation, both of which read badly beside a sibling entry in a legend or a table column.

Parameters:: value (float) – The number to format, already in its display unit.
Returns:: str – The formatted number, with no unit attached.
Return type:: str

Examples

>>> sig3(9.512), sig3(7.0), sig3(0.85), sig3(953.2)
('9.51', '7.00', '0.850', '953')

croak.plotting.plot_residual(ax, omega, delays, resid, omega0, *, halfwidth=None, flim=None)[source]#

Plot the measured−retrieved residual with a symmetric blue-white-red map.

flim optionally bounds the frequency axis, as (f_min, f_max) in Hz.

croak.plotting.plot_temporal(ax, pr, *, halfwidth=None, power_scale=None, truth=None)[source]#

Temporal intensity/power (left) and phase (right twin axis); phase masked.

When pr.peak_power is set (a measured pulse energy was supplied to process_result()), the intensity is shown as absolute instantaneous power on an SI-prefixed axis; otherwise it stays normalised (“a.u.”). power_scale is an optional (scale, unit) pair (see si_power()) so several panels can share one prefix; when None it is derived from the larger of the retrieved/TL peak powers.

truth (a TruthPulse: a synthetic generating field, or a simulated scan’s reference intensity) is overlaid as a thin black line under the retrieved/TL curves, labelled with its own FWHM, and — when it carries a temporal phase — as a dotted phase in the same display gauge as the retrieved one (see croak.processing.normalize_temporal_phase()).

Returns the twin phase axes. draw_temporal() is the same panel for the registry, returning every artist (TemporalArtists).

Parameters:

pr (ProcessedResult)
truth (TruthPulse | None)

croak.plotting.plot_spectral(ax, pr, *, lam_min=None, lam_max=None, truth=None, axis='frequency')[source]#

Spectral intensity (left) and phase (right twin axis) against axis.

axis is "frequency" (PHz, the default: the space the retrieval works in, where |E(ω)|² of a symmetric pulse is symmetric) or "wavelength" (nm, the spectrometer’s axis, carrying the 1/λ² density Jacobian). Both spectra are drawn as unit-peak densities in the chosen variable; lam_min/lam_max (m) bound the axis on either. The phase curves are the same on both.

truth, when it carries a spectrum, is overlaid as a thin black line under the retrieved curve; when it carries a known spectral phase, that phase is overlaid on the phase axis. It is drawn in the SAME gauge as the retrieved phase (unwrapped, de-tilted, zeroed at the spectral peak — see croak.processing.normalize_spectral_phase()), because spectral phase is defined only up to a constant and a linear term; a truth pinned any other way would show a tilt or offset that is gauge, not error.

Returns the twin phase axes. draw_spectral() is the same panel for the registry, returning every artist (SpectralArtists).

Parameters:

pr (ProcessedResult)
truth (TruthPulse | None)
axis (SpectralAxis)

croak.plotting.SPECTRAL_AXES: tuple[str, ...] = ('frequency', 'wavelength')#: Abscissae the spectrum panel can be drawn against (see plot_spectral()).

croak.plotting.EDGE_ENERGY_WARN = 0.01#: Edge-energy fraction (see croak.processing.edge_energy_fraction()) above which the spectrum panel flags the retrieval in red. A sound retrieval on a generous band sits two orders of magnitude below this; above it, re-run on a wider grid.

croak.plotting.plot_convergence(ax, errors, *, boundaries=())[source]#

Plot the FROG error vs iteration on a log y-axis.

boundaries are indices into errors where a multi-stage solver handed over to its next stage (stage_boundaries); each is drawn as a dashed rule. Marking them matters because the stages need not count the same unit of work — warm-lbfgs splices COPRA iterations onto L-BFGS function evaluations — so an unmarked kink would read as convergence behaviour rather than as the change of algorithm it is.

The error curve is created even for an empty errors (a result restored from file carries no history), so a live view can grow it in place.

Parameters:

errors (ArrayLike)
boundaries (Sequence[int])

Return type:

ConvergenceArtists

croak.plotting.plot_marginal(ax, x, retrieved, measured=None, *, xlabel='', scale=1.0, halfwidth=None)[source]#

Plot a (retrieved vs measured) trace marginal.

Return type:: MarginalArtists

croak.plotting.plot_spectrogram(ax, t_centers, wavelength, S, *, lam_min=None, lam_max=None, halfwidth=None, cmap=None)[source]#: Plot a Gabor spectrogram (time fs × wavelength nm).

croak.plotting.plot_retrieval(result, *, measured=None, Iomega_meas=None, lam_min=None, lam_max=None, flim=None, tracedb=30.0, cmap='viridis', truth=None, energy=None, figsize=(17.0, 9.45), fig=None, processed=None, spectral_axis='frequency')[source]#

12-panel retrieval summary: the standard at-a-glance quality check.

The panels are RETRIEVAL_PANELS in the RETRIEVAL_OVERVIEW layout — measured/retrieved traces (log and linear) on the left, the pulse, spectrum and marginals on the right, convergence, residual, spectral filter and spectrogram along the bottom. plot_retrieval_page() draws a subset.

lam_min/lam_max (m) bound the wavelength axes — the spectrum and spectrogram panels. flim bounds the frequency axis of the trace and residual panels, as (f_min, f_max) in Hz; the default shows the whole retrieval grid. The two are separate because the trace sits at the signal frequency, which for SHG is twice the pulse’s. Reach for flim when the retrieval grid is much wider than the signal — typical when retrieving directly on a synthesis grid rather than on one cropped by load_and_clean() — where the trace would otherwise be a thin stripe in a mostly empty axis.

energy is an optional measured pulse energy (J); when given, the temporal panel is shown in absolute power (see process_result()).

processed is an optional, already-computed ProcessedResult for this same result: pass it when the caller needs the processed quantities too (the GUI shows them in a table beside the figure) so they are not derived twice. It must have been built with the same measured/Iomega_meas/energy, which are then used only for the trace panels; a mismatched one raises ValueError.

spectral_axis draws the spectrum panel against "frequency" (PHz, the default) or "wavelength" (nm); see plot_spectral().

Raises:

ValueError – If result carries no trace, or processed belongs to another result.

Parameters:

result (RetrievalResult)
measured (ArrayLike | None)
Iomega_meas (ArrayLike | None)
lam_min (float | None)
lam_max (float | None)
flim (tuple[float, float] | None)
tracedb (float)
cmap (str)
truth (TruthPulse | None)
energy (float | None)
fig (Figure | None)
processed (ProcessedResult | None)
spectral_axis (SpectralAxis)

Return type:

Figure

class croak.plotting.RetrievalPlotData(result, processed, measured, retrieved, omega0_trace, halfwidth, lam_min, lam_max, flim, tracedb, cmap_pos, lin_vmax, truth, power_scale, spectral_axis)[source]#

Bases: object

Everything the retrieval panels share, computed once from one result.

Build it with retrieval_plot_data(). The bundle is immutable and carries no figure state, so one instance can feed several figures (the GUI’s pages and their pop-outs) and be redrawn at any size.

Parameters:

result (RetrievalResult)
processed (ProcessedResult)
measured (NDArray[np.float64])
retrieved (NDArray[np.float64])
omega0_trace (float)
halfwidth (float)
lam_min (float)
lam_max (float)
flim (tuple[float, float] | None)
tracedb (float)
cmap_pos (Colormap)
lin_vmax (float)
truth (TruthPulse | None)
power_scale (tuple[float, str] | None)
spectral_axis (str)

result#

The retrieval; result.trace is the retrieved trace.

Type:: RetrievalResult

processed#

Display-ready quantities of result (croak.processing.process_result()).

Type:: ProcessedResult

measured, retrieved

Measured and retrieved traces, shape (Nω, Nτ).

Type:: ndarray

omega0_trace#

Centre angular frequency of the signal (twice omega0 for SHG), so the trace panels’ frequency axis reads at the signal frequency.

Type:: float

halfwidth#

Half the delay span (s); bounds the delay axes.

Type:: float

lam_min, lam_max

Wavelength bounds (m) of the spectrum and spectrogram panels.

Type:: float

flim#

Optional (f_min, f_max) (Hz) bounds of the trace/residual frequency axes.

Type:: tuple of float or None

tracedb#

Dynamic range (dB) of the logarithmic trace panels.

Type:: float

cmap_pos#

White-based positive colormap shared by the trace and spectrogram panels.

Type:: Colormap

lin_vmax#

Common scale of the linear trace pair, so their colorbar is meaningful.

Type:: float

truth#

Known pulse to overlay (synthetic and simulated data).

Type:: TruthPulse or None

power_scale#

SI (scale, unit) for absolute power when a pulse energy was given.

Type:: tuple of (float, str) or None

spectral_axis#

"frequency" or "wavelength": the spectrum panel’s abscissa.

Type:: str

property spectrogram: tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.float64]][source]#

(t_centres, wavelength, S) of croak.processing.spectrogram().

The Gabor transform is the costliest thing the panels compute (hundreds of FFTs), so it runs only when the spectrogram panel is first drawn and is then cached on the bundle for every later draw of it.

croak.plotting.retrieval_plot_data(result, *, measured=None, Iomega_meas=None, lam_min=None, lam_max=None, flim=None, tracedb=30.0, cmap='viridis', truth=None, energy=None, processed=None, spectral_axis='frequency')[source]#

Bundle a retrieval’s plot inputs for the panels (see plot_retrieval()).

The arguments are those of plot_retrieval(), which is this bundle drawn as the overview; see there for their meaning. processed is an already-computed ProcessedResult for this same result (the GUI computes it once for its read-out); it must have been built with the same measured/Iomega_meas/energy.

Raises:

ValueError – If result carries no trace, processed belongs to another result, or spectral_axis is not one of SPECTRAL_AXES.

Parameters:

result (RetrievalResult)
measured (ArrayLike | None)
Iomega_meas (ArrayLike | None)
lam_min (float | None)
lam_max (float | None)
flim (tuple[float, float] | None)
tracedb (float)
cmap (str)
truth (TruthPulse | None)
energy (float | None)
processed (ProcessedResult | None)
spectral_axis (str)

Return type:

RetrievalPlotData

class croak.plotting.TraceArtists(mesh_pos, mesh_neg, label=None)[source]#

Bases: object

Artists of a trace-image panel.

Parameters:

mesh_pos (QuadMesh)
mesh_neg (QuadMesh | None)
label (Text | None)

mesh_pos, mesh_neg

The positive-sample image and, when the data hold negatives, the white→red magnitude image of the negative samples (else None).

Type:: QuadMesh

label#

The bold error/shape annotation of the retrieved-linear panel.

Type:: Text or None

class croak.plotting.ResidualArtists(mesh)[source]#

Bases: object

Artists of the residual panel: its signed image (None if no residual).

Parameters:: mesh (QuadMesh | None)

class croak.plotting.TemporalArtists(line_retr, line_tl, line_phase, ax_phase, legend, legend_retr, legend_tl, line_truth=None, line_truth_phase=None)[source]#

Bases: object

Artists of the temporal panel.

Parameters:

line_retr (Line2D)
line_tl (Line2D)
line_phase (Line2D)
ax_phase (Axes)
legend (Legend)
legend_retr (Text)
legend_tl (Text)
line_truth (Line2D | None)
line_truth_phase (Line2D | None)

line_retr, line_tl

Retrieved and transform-limited intensity (or power) curves.

Type:: Line2D

line_phase#

Retrieved temporal phase on the twin axis ax_phase.

Type:: Line2D

ax_phase#

The right-hand phase axis.

Type:: Axes

legend#

The combined intensity + phase legend.

Type:: Legend

legend_retr, legend_tl

The legend entries carrying the R and TL durations (they change with the result, so a live update rewrites them in place).

Type:: Text

line_truth, line_truth_phase

Ground-truth intensity and phase overlays, when a truth was given.

Type:: Line2D or None

class croak.plotting.SpectralArtists(line_retr, line_phase, line_phase_fit, ax_phase, legend, text_dispersion, text_edge, line_meas=None, line_truth=None, line_truth_phase=None)[source]#

Bases: object

Artists of the spectrum panel.

Parameters:

line_retr (Line2D)
line_phase (Line2D)
line_phase_fit (Line2D)
ax_phase (Axes)
legend (Legend)
text_dispersion (Text)
text_edge (Text)
line_meas (Line2D | None)
line_truth (Line2D | None)
line_truth_phase (Line2D | None)

line_retr#

Retrieved spectral intensity.

Type:: Line2D

line_phase, line_phase_fit

Retrieved spectral phase and its dashed polynomial fit, on ax_phase.

Type:: Line2D

ax_phase#

The right-hand phase axis.

Type:: Axes

legend#

The combined intensity + phase legend.

Type:: Legend

text_dispersion, text_edge

The GDD/TOD block and the edge-energy warning.

Type:: Text

line_meas, line_truth, line_truth_phase

Measured spectrum, truth spectrum and truth phase, when available.

Type:: Line2D or None

class croak.plotting.ConvergenceArtists(line, boundaries=(), legend=None)[source]#

Bases: object

Artists of the convergence panel: the error curve, stage rules, legend.

Parameters:

line (Line2D)
boundaries (tuple[Line2D, ...])
legend (Legend | None)

class croak.plotting.LineArtists(line)[source]#

Bases: object

A single-curve panel (the spectral filter).

Parameters:: line (Line2D)

class croak.plotting.MarginalArtists(line_retr, legend, line_meas=None)[source]#

Bases: object

Artists of a marginal panel: retrieved and (optional) measured curves.

Parameters:

line_retr (Line2D)
legend (Legend)
line_meas (Line2D | None)

class croak.plotting.SpectrogramArtists(mesh)[source]#

Bases: object

Artists of the spectrogram panel: its image.

Parameters:: mesh (QuadMesh)

class croak.plotting.PanelSpec(key, title, draw, update)[source]#

Bases: object

One retrieval panel: registry key, axes title, draw and in-place update.

Parameters:

key (str)
title (str)
draw (PanelDraw)
update (PanelUpdate)

class croak.plotting.PageSpec(key, title, mosaic)[source]#

Bases: object

A figure’s worth of panels laid out as a grid of registry keys.

Parameters:

key (str)
title (str)
mosaic (tuple[tuple[str, ...], ...])

key, title

Identifier and human-readable name (the GUI’s tab label).

Type:: str

mosaic#

Rows of panel keys, as subplot_mosaic() takes them.

Type:: tuple of tuple of str

property keys: tuple[str, ...]#: The page’s panel keys in reading order.

class croak.plotting.ColorbarSpec(panels, shrink=0.6, neg_label='neg |·|')[source]#

Bases: object

A colorbar shared by the listed panels (drawn only when all are present).

A positive colorbar is always drawn; a second, neg_label-ed one appears when any of the panels holds negative samples (see signed_pcolormesh()).

Parameters:

panels (tuple[str, ...])
shrink (float)
neg_label (str)

croak.plotting.RETRIEVAL_PANELS: Mapping[str, PanelSpec] = {'convergence': PanelSpec(key='convergence', title='Convergence', draw=<function draw_convergence>, update=<function update_convergence>), 'delay_marginal': PanelSpec(key='delay_marginal', title='Delay marginal', draw=<function draw_delay_marginal>, update=<function update_delay_marginal>), 'freq_marginal': PanelSpec(key='freq_marginal', title='Frequency marginal', draw=<function draw_freq_marginal>, update=<function update_freq_marginal>), 'measured_lin': PanelSpec(key='measured_lin', title='Measured (lin)', draw=<function draw_measured_lin>, update=<function update_measured_lin>), 'measured_log': PanelSpec(key='measured_log', title='Measured (log)', draw=<function draw_measured_log>, update=<function update_measured_log>), 'residual': PanelSpec(key='residual', title='Residuals', draw=<function draw_residual>, update=<function update_residual>), 'retrieved_lin': PanelSpec(key='retrieved_lin', title='Retrieved (lin)', draw=<function draw_retrieved_lin>, update=<function update_retrieved_lin>), 'retrieved_log': PanelSpec(key='retrieved_log', title='Retrieved (log)', draw=<function draw_retrieved_log>, update=<function update_retrieved_log>), 'spectral': PanelSpec(key='spectral', title='Spectrum', draw=<function draw_spectral>, update=<function update_spectral>), 'spectral_filter': PanelSpec(key='spectral_filter', title='Spectral filter', draw=<function draw_spectral_filter>, update=<function update_spectral_filter>), 'spectrogram': PanelSpec(key='spectrogram', title='Spectrogram', draw=<function draw_spectrogram>, update=<function update_spectrogram>), 'temporal': PanelSpec(key='temporal', title='Retrieved pulse', draw=<function draw_temporal>, update=<function update_temporal>)}#: The twelve retrieval panels, keyed, in the overview’s reading order.

croak.plotting.RETRIEVAL_COLORBARS: tuple[ColorbarSpec, ...] = (ColorbarSpec(panels=('measured_log', 'retrieved_log'), shrink=0.6, neg_label='neg |·|'), ColorbarSpec(panels=('measured_lin', 'retrieved_lin'), shrink=0.6, neg_label='neg |·|'), ColorbarSpec(panels=('residual',), shrink=0.6, neg_label='neg |·|'))#

one per trace pair (they share a scale) and one for the residual.

Type:: Colorbars

croak.plotting.RETRIEVAL_PAGES: Mapping[str, PageSpec] = {'diagnostics': PageSpec(key='diagnostics', title='Diagnostics', mosaic=(('convergence', 'residual'), ('spectral_filter', 'spectrogram'))), 'pulse': PageSpec(key='pulse', title='Pulse', mosaic=(('temporal', 'spectral'), ('delay_marginal', 'freq_marginal'))), 'traces': PageSpec(key='traces', title='Traces', mosaic=(('measured_log', 'retrieved_log'), ('measured_lin', 'retrieved_lin')))}#: The three 2×2 pages the GUI shows as tabs.

croak.plotting.RETRIEVAL_OVERVIEW = PageSpec(key='overview', title='Retrieval overview', mosaic=(('measured_log', 'retrieved_log', 'temporal', 'delay_marginal'), ('measured_lin', 'retrieved_lin', 'spectral', 'freq_marginal'), ('convergence', 'residual', 'spectral_filter', 'spectrogram')))#

traces left, pulse right (the delay marginal beside the time-domain pulse, the frequency marginal beside the spectrum), diagnostics along the bottom.

Type:: The 3×4 overview plot_retrieval() draws

croak.plotting.plot_retrieval_page(data, page, *, figsize=(8.5, 6.3), fig=None)[source]#

Draw one page of retrieval panels (a RETRIEVAL_PAGES entry).

The default figsize gives a 2×2 page the same per-panel size as the overview’s default 17.0×9.45 in.

Parameters:

data (RetrievalPlotData) – From retrieval_plot_data().
page (PageSpec) – Which panels, in which grid; RETRIEVAL_OVERVIEW draws all twelve.
figsize (tuple of float) – Size (in) of a new figure; ignored when fig is given.
fig (Figure, optional) – Existing figure to clear and draw into (a GUI canvas).

Return type:

Figure

Examples

>>> data = retrieval_plot_data(result, measured=trace)
>>> fig = plot_retrieval_page(data, RETRIEVAL_PAGES["pulse"])

croak.plotting.draw_measured_log(ax, data)[source]#

Draw the measured trace, logarithmic (tracedb dynamic range).

Parameters:: data (RetrievalPlotData)
Return type:: TraceArtists

croak.plotting.draw_retrieved_log(ax, data)[source]#

Draw the retrieved trace, logarithmic.

Parameters:: data (RetrievalPlotData)
Return type:: TraceArtists

croak.plotting.draw_measured_lin(ax, data)[source]#

Draw the measured trace, linear, on the scale shared with the retrieved.

Parameters:: data (RetrievalPlotData)
Return type:: TraceArtists

croak.plotting.draw_retrieved_lin(ax, data)[source]#

Draw the retrieved trace, linear, annotated with FROG error and shape.

Parameters:: data (RetrievalPlotData)
Return type:: TraceArtists

croak.plotting.draw_temporal(ax, data)[source]#

Draw the retrieved pulse: intensity/power, TL pulse, phase, truth overlay.

Parameters:: data (RetrievalPlotData)
Return type:: TemporalArtists

croak.plotting.draw_spectral(ax, data)[source]#

Draw the spectrum: retrieved, measured, phase and fit, GDD/TOD, truth.

Parameters:: data (RetrievalPlotData)
Return type:: SpectralArtists

croak.plotting.draw_convergence(ax, data)[source]#

Draw the FROG error against iteration, with the solver’s stage handovers.

Parameters:: data (RetrievalPlotData)
Return type:: ConvergenceArtists

croak.plotting.draw_residual(ax, data)[source]#

Draw the measured − retrieved residual; leave it empty if there is none.

Parameters:: data (RetrievalPlotData)
Return type:: ResidualArtists

croak.plotting.draw_spectral_filter(ax, data)[source]#

Draw the per-frequency scale factor (Rω filter) against wavelength.

Parameters:: data (RetrievalPlotData)
Return type:: LineArtists

croak.plotting.draw_freq_marginal(ax, data)[source]#

Draw the frequency marginal of the retrieved and measured traces.

Parameters:: data (RetrievalPlotData)
Return type:: MarginalArtists

croak.plotting.draw_delay_marginal(ax, data)[source]#

Draw the delay marginal of the retrieved and measured traces.

Parameters:: data (RetrievalPlotData)
Return type:: MarginalArtists

croak.plotting.draw_spectrogram(ax, data)[source]#

Draw the Gabor spectrogram of the retrieved pulse (computed once, cached).

Parameters:: data (RetrievalPlotData)
Return type:: SpectrogramArtists

croak.plotting.update_measured_log(artists, data)[source]#

Update draw_measured_log()’s artists in place.

Parameters:

artists (TraceArtists)
data (RetrievalPlotData)

Return type:

None

croak.plotting.update_retrieved_log(artists, data)[source]#

Update draw_retrieved_log()’s artists in place.

Parameters:

artists (TraceArtists)
data (RetrievalPlotData)

Return type:

None

croak.plotting.update_measured_lin(artists, data)[source]#

Update draw_measured_lin()’s artists in place.

Parameters:

artists (TraceArtists)
data (RetrievalPlotData)

Return type:

None

croak.plotting.update_retrieved_lin(artists, data)[source]#

Update draw_retrieved_lin()’s artists in place.

Parameters:

artists (TraceArtists)
data (RetrievalPlotData)

Return type:

None

croak.plotting.update_temporal(artists, data)[source]#

Update draw_temporal()’s artists in place.

Parameters:

artists (TemporalArtists)
data (RetrievalPlotData)

Return type:

None

croak.plotting.update_spectral(artists, data)[source]#

Update draw_spectral()’s artists in place.

Parameters:

artists (SpectralArtists)
data (RetrievalPlotData)

Return type:

None

croak.plotting.update_convergence(artists, data)[source]#

Update draw_convergence()’s artists in place.

Parameters:

artists (ConvergenceArtists)
data (RetrievalPlotData)

Return type:

None

croak.plotting.update_convergence_curve(artists, errors)[source]#

Grow the error curve of plot_convergence() in place and rescale.

Parameters:

artists (ConvergenceArtists)
errors (ArrayLike)

Return type:

None

croak.plotting.update_residual(artists, data)[source]#

Update draw_residual()’s artists in place.

Parameters:

artists (ResidualArtists)
data (RetrievalPlotData)

Return type:

None

croak.plotting.update_spectral_filter(artists, data)[source]#

Update draw_spectral_filter()’s artists in place (x is the fixed grid).

Parameters:

artists (LineArtists)
data (RetrievalPlotData)

Return type:

None

croak.plotting.update_freq_marginal(artists, data)[source]#

Update draw_freq_marginal()’s artists in place.

Parameters:

artists (MarginalArtists)
data (RetrievalPlotData)

Return type:

None

croak.plotting.update_delay_marginal(artists, data)[source]#

Update draw_delay_marginal()’s artists in place.

Parameters:

artists (MarginalArtists)
data (RetrievalPlotData)

Return type:

None

croak.plotting.update_spectrogram(artists, data)[source]#

Update draw_spectrogram()’s artists in place.

Raises:

ValueError – If the spectrogram’s shape differs from the drawn one (a different grid): the panel has to be redrawn, not updated.

Parameters:

artists (SpectrogramArtists)
data (RetrievalPlotData)

Return type:

None

class croak.plotting.RetrievalPageView(page)[source]#

Bases: object

Maintain a page of retrieval plots for repeated GUI updates.

The live preview hands the Retrieve stage a new result a few times a second. Clearing a figure and rebuilding a page’s axes, colourbars and legends for each one costs a full constrained-layout solve and lets legends jump between frames; this view draws the page once and then pushes later results onto the existing artists when can_update() accepts the new data, as FrogFilterView does for the preprocessing figure. It redraws when the grid, optional curves or panel structure change.

Parameters:: page (PageSpec) – Panels and their layout.

Examples

>>> view = RetrievalPageView(RETRIEVAL_PAGES["pulse"])
>>> view.draw(fig, data1)
>>> if view.can_update(data2):
...     view.update(data2)
... else:
...     view.draw(fig, data2)

property attached: bool#: Whether the view has drawn into a figure.

draw(fig, data)[source]#

Clear fig and draw the page afresh for data.

Constrained layout is solved on the first real draw and then frozen (the engine is swapped for matplotlib’s placeholder), so later in-place updates neither re-solve it nor nudge the panels as tick labels change width.

Parameters:

fig (Figure)
data (RetrievalPlotData)

Return type:

None

can_update(data)[source]#

Whether data differs from the drawn result in values only.

Parameters:: data (RetrievalPlotData)
Return type:: bool

update(data)[source]#

Push data onto the drawn artists.

Raises:

RuntimeError – If nothing has been drawn yet.
ValueError – If can_update() is false (different grid or optional artists); draw() it instead.

Parameters:

data (RetrievalPlotData)

Return type:

None

reset()[source]#

Forget the figure (someone else cleared it); the next call must draw.

Return type:: None

croak.plotting.plot_frog_filter(td, *, tracedb=30.0, cmap='viridis', figsize=(9.45, 4.72), fig=None)[source]#

6-panel measured/filtered (wavelength-domain) + regridded (frequency-domain).

Positive values use the viridis (white-low) map; negative values — kept through filtering rather than clamped — are drawn by magnitude on a white→red map so they are visible and not mistaken for signal. Each row (the dB row and the linear row) carries one positive + one negative colorbar on the right-hand side.

Parameters:

tracedb (float)
cmap (str)
fig (Figure | None)

Return type:

Figure

croak.plotting.filter_view_vmax(td)[source]#

Return the shared positive colour scale for the six-panel filter view.

Take the largest positive sample across the measured, filtered and regridded traces, restricting the two wavelength-domain arrays to the measurement window td.lamm_lims when set.

Both restrictions matter on real data. An absolute-calibration curve amplifies the background-subtracted noise far outside the signal band, so scaling by max|·| lets a large negative excursion set the positive scale: on one of our measured deep-UV traces, whose signal peaks at +1 but dips to -5.7 at 1097 nm, every linear panel rendered its signal at 18 % of the colour range.

The three panels share this one number so the row’s single colourbar means something; each array is peak-normalised upstream, so they are comparable. If no positive sample remains, fall back to the largest absolute value, then 1.0, so the returned scale is always positive.

Return type:: float

class croak.plotting.FrogFilterView(*, tracedb=30.0, cmap='viridis', cap=1000)[source]#

Bases: object

Maintain a preprocessing figure for repeated GUI updates.

The artist-reusing twin of plot_frog_filter(), which clears and rebuilds the whole figure (6 panels × up to 2 pcolormesh + 4 colourbars) on every call: ~150–400 ms, the dominant cost of the GUI preprocessing redraw. Call attach() once to create the panels, images and colourbars, then update() to push new data via set_data/set_extent/set_clim onto the persistent images, which benchmarks ~4× faster. Positive and negative samples use the same signed-magnitude convention as signed_pcolormesh(). Non-uniform wavelength arrays are interpolated onto a uniform display grid; the underlying croak.preprocess.TraceData arrays are unchanged.

Parameters:

tracedb (float)
cmap (str)
cap (int)

property attached: bool#: Whether a figure is currently attached to this view.

attach(fig)[source]#

Build the mosaic, images and colourbars once into fig.

Parameters:: fig (Figure)
Return type:: None

update(td)[source]#

Push a new TraceData onto the existing artists.

Return type:: None

croak.plotting.plot_simulated_trace(omega, delays, trace, omega0_trace, *, tracedb=40.0, cmap='viridis', figsize=(7.87, 5.51), fig=None)[source]#

4-panel view of a simulated trace: dB, linear, and the two marginals.

Parameters:

tracedb (float)
cmap (str)
fig (Figure | None)

Return type:

Figure

croak.plotting.plot_fwhm_distribution(ax, uresult, *, truth=None)[source]#

Histogram of bootstrap FWHM samples with the point estimate and intervals.

Parameters:

ax (matplotlib.axes.Axes) – Axis to draw into.
uresult (UncertaintyResult) – The bootstrap result (its samples are histogrammed).
truth (float, optional) – A known true FWHM (s) to mark with a dashed line (synthetic tests).

Return type:

None

croak.plotting.plot_intensity_band(ax, uresult)[source]#

Plot the median temporal intensity and pointwise 68 %/95 % resampling bands.

Requires the bootstrap to have been run with collect_profiles=True. The profiles are peak-aligned (translation gauge removed by shiftnorm), so the band is the spread of the aligned intensity envelope across replicates. The bands are pointwise, not simultaneous bands for the whole curve.

Parameters:: uresult (UncertaintyResult)
Return type:: None

croak.plotting.plot_uncertainty(uresult, *, truth=None, figsize=(11.0, 4.2), fig=None)[source]#

Composite uncertainty figure: FWHM histogram + a confidence band if present.

Parameters:

uresult (UncertaintyResult) – The bootstrap result.
truth (float, optional) – Known true FWHM (s) for the histogram (synthetic tests).
figsize (tuple, optional) – Figure size.
fig (matplotlib.figure.Figure, optional) – Existing figure to draw into (cleared first), e.g. a Qt canvas figure.

Returns:

matplotlib.figure.Figure

Return type:

Figure