display

Display subsystem for tables and plots.

This package contains user-facing facades and backend implementations to render tabular data and plots in different environments.

• Tables: see :mod:easydiffraction.display.tables and the engines in :mod:easydiffraction.display.tablers. - Plots: see :mod:easydiffraction.display.plotting and the engines in :mod:easydiffraction.display.plotters.

Modules:

Name	Description
base	Common base classes for display components and their factories.
plotters	Plotting backends.
plotting	Plotting facade for measured and calculated patterns.
progress	Environment-aware activity indicator for long-running tasks.
structure	crysview structure-visualization subsystem.
tablers	Tabular rendering backends.
tables	Table rendering engines: console (Rich) and Jupyter (pandas).
theme	Shared display theme colors for plots and notebook tables.
utils

Modules

base

Common base classes for display components and their factories.

Classes:

Name	Description
RendererBase	Base class for display components with pluggable engines.
RendererFactoryBase	Base factory that manages discovery and creation of backends.

Classes

RendererBase()

Base class for display components with pluggable engines.

Subclasses provide a factory and a default engine. This class manages the active backend instance and exposes helpers to inspect supported engines in a table-friendly format.

Methods:

Name	Description
show_config	Display the current renderer configuration.
show_supported_engines	List supported engines with descriptions in a table.
show_current_engine	Display the currently selected engine.
get	Return the shared instance, creating it if needed.

Attributes:

Name	Type	Description
engine	str	Return the name of the currently active rendering engine.

Attributes

engine property writable

Return the name of the currently active rendering engine.

Returns:

Type	Description
str	Identifier of the active engine.

Functions

show_config() abstractmethod

Display the current renderer configuration.

show_supported_engines()

List supported engines with descriptions in a table.

show_current_engine()

Display the currently selected engine.

get() classmethod

Return the shared instance, creating it if needed.

RendererFactoryBase

Base factory that manages discovery and creation of backends.

Methods:

Name	Description
create	Create a backend instance for the given engine.
supported_engines	Return a list of supported engine identifiers.
descriptions	Return (name, description) pairs for each engine.

Functions

create(engine_name) classmethod

Create a backend instance for the given engine.

Parameters:

Name	Type	Description	Default
engine_name	str	Identifier of the engine to instantiate as listed in _registry().	required

Returns:

Type	Description
object	A new backend instance corresponding to engine_name.

Raises:

Type	Description
ValueError	If the engine name is not supported.

supported_engines() classmethod

Return a list of supported engine identifiers.

descriptions() classmethod

Return (name, description) pairs for each engine.

plotters

Plotting backends.

This subpackage implements plotting engines used by the high-level plotting facade:

• :mod:.ascii for terminal-friendly ASCII plots. - :mod:.plotly for interactive plots in notebooks or browsers.

Modules:

Name	Description
ascii	ASCII plotting backend.
base	Abstract base and shared constants for plotting backends.
plotly	Plotly plotting backend.

Modules

ascii

ASCII plotting backend.

Renders compact line charts in the terminal using asciichartpy. This backend is well suited for quick feedback in CLI environments and keeps a consistent API with other plotters.

Classes:

Name	Description
AsciiPlotter	Terminal-based plotter using ASCII art.

Classes

AsciiPlotter

Terminal-based plotter using ASCII art.

Methods:

Name	Description
plot_powder	Render a line plot for powder diffraction data.
plot_powder_meas_vs_calc	Render a composite powder plot in the terminal.
plot_single_crystal	Render a scatter plot for single crystal diffraction data.
plot_scatter	Render a scatter plot with error bars in ASCII.
plot_correlation_heatmap	Render a graphical heatmap for a correlation matrix.

Functions

plot_powder(x, y_series, labels, axes_labels, title, height=None, excluded_ranges=())

Render a line plot for powder diffraction data.

Suitable for powder diffraction data where intensity is plotted against an x-axis variable (2θ, TOF, d-spacing). Uses ASCII characters for terminal display.

Parameters:

Name	Type	Description	Default
x	object	1D array-like of x values (only used for range display).	required
y_series	object	Sequence of y arrays to plot.	required
labels	object	Series identifiers corresponding to y_series.	required
axes_labels	object	Ignored; kept for API compatibility.	required
title	str	Figure title printed above the chart.	required
height	int | None	Number of text rows to allocate for the chart.	None
excluded_ranges	tuple[tuple[float, float], ...]	Excluded x-ranges to print below the selected x-range.	()

plot_powder_meas_vs_calc(plot_spec)

Render a composite powder plot in the terminal.

The ASCII backend falls back to the existing single-chart view for measured, calculated, and residual series. Bragg tick rows are announced but not rendered graphically.

plot_single_crystal(x_calc, y_meas, y_meas_su, axes_labels, title, height=None)

Render a scatter plot for single crystal diffraction data.

Creates an ASCII scatter plot showing measured vs calculated values with a diagonal reference line.

Parameters:

Name	Type	Description	Default
x_calc	object	1D array-like of calculated values (x-axis).	required
y_meas	object	1D array-like of measured values (y-axis).	required
y_meas_su	object	1D array-like of measurement uncertainties (ignored in ASCII mode).	required
axes_labels	object	Pair of strings for the x and y titles.	required
title	str	Figure title.	required
height	int | None	Number of text rows for the chart (default: 15).	None

plot_scatter(x, y, sy, axes_labels, title, height=None)

Render a scatter plot with error bars in ASCII.

plot_correlation_heatmap(corr_df, title, threshold, precision)

Render a graphical heatmap for a correlation matrix.

The default implementation does nothing. Graphical backends (e.g. Plotly) override this method and set _supports_graphical_heatmap = True so the facade knows a heatmap was rendered.

Parameters:

Name	Type	Description	Default
corr_df	object	Square correlation DataFrame.	required
title	str	Figure title.	required
threshold	float | None	Absolute-correlation cutoff used for value labels.	required
precision	int	Number of decimals to show in labels and hover text.	required

base

Abstract base and shared constants for plotting backends.

Classes:

Name	Description
BraggTickSet	Bragg tick data for one linked phase row.
PowderMeasVsCalcSpec	Specification for one composite powder plot.
XAxisType	X-axis types for diffraction plots.
PlotterBase	Abstract base for plotting backends.

Classes

BraggTickSet(phase_id, x, h, k, ell, f_squared_calc, f_calc) dataclass

Bragg tick data for one linked phase row.

The plotting facade converts experiment reflection-category data into this display-specific container so plotting backends stay decoupled from experiment datablock internals.

PowderMeasVsCalcSpec(x, y_meas, y_calc, y_resid, bragg_tick_sets, axes_labels, title, residual_height_fraction, bragg_peaks_height_fraction, height=None, y_bkg=None, predictive_lower_95=None, predictive_upper_95=None, predictive_draws=None, y_calc_name=None, y_calc_line_dash=None, excluded_ranges=(), y_meas_su=None) dataclass

Specification for one composite powder plot.

The plotting facade assembles the measured, background, calculated, residual, and Bragg-tick data into this display-specific object before delegating to a backend.

XAxisType

X-axis types for diffraction plots.

Values match attribute names in data models for direct use with getattr(pattern, x_axis).

PlotterBase

Abstract base for plotting backends.

Implementations accept x values, multiple y-series, optional labels and render a plot to the chosen medium.

Two main plot types are supported: - plot_powder: Line plots for powder diffraction patterns (intensity vs. 2θ/TOF/d-spacing). - plot_single_crystal: Scatter plots comparing measured vs. calculated values (e.g., F²meas vs F²calc for single crystal).

Methods:

Name	Description
plot_powder	Render a line plot for powder diffraction data.
plot_powder_meas_vs_calc	Render a composite powder plot with Bragg ticks and residual.
plot_single_crystal	Render a scatter plot for single crystal diffraction data.
plot_scatter	Render a scatter plot with error bars.
plot_correlation_heatmap	Render a graphical heatmap for a correlation matrix.

Functions

plot_powder(x, y_series, labels, axes_labels, title, height, excluded_ranges=()) abstractmethod

Render a line plot for powder diffraction data.

Suitable for powder diffraction data where intensity is plotted against an x-axis variable (2θ, TOF, d-spacing).

Parameters:

Name	Type	Description	Default
x	object	1D array of x-axis values.	required
y_series	object	Sequence of y arrays to plot.	required
labels	object	Identifiers corresponding to y_series.	required
axes_labels	object	Pair of strings for the x and y titles.	required
title	str	Figure title.	required
height	int | None	Backend-specific height (text rows or pixels).	required
excluded_ranges	tuple[tuple[float, float], ...]	Closed x-intervals to highlight as excluded regions.	()

plot_powder_meas_vs_calc(plot_spec) abstractmethod

Render a composite powder plot with Bragg ticks and residual.

Parameters:

Name	Type	Description	Default
plot_spec	PowderMeasVsCalcSpec	Composite powder-plot inputs and layout settings.	required

plot_single_crystal(x_calc, y_meas, y_meas_su, axes_labels, title, height) abstractmethod

Render a scatter plot for single crystal diffraction data.

Suitable for single crystal diffraction data where measured values are plotted against calculated values with error bars.

Parameters:

Name	Type	Description	Default
x_calc	object	1D array of calculated values (x-axis).	required
y_meas	object	1D array of measured values (y-axis).	required
y_meas_su	object	1D array of measurement uncertainties.	required
axes_labels	object	Pair of strings for the x and y titles.	required
title	str	Figure title.	required
height	int | None	Backend-specific height (text rows or pixels).	required

plot_scatter(x, y, sy, axes_labels, title, height) abstractmethod

Render a scatter plot with error bars.

Parameters:

Name	Type	Description	Default
x	object	1-D array of x-axis values.	required
y	object	1-D array of y-axis values.	required
sy	object	1-D array of y uncertainties.	required
axes_labels	object	Pair of strings for x and y axis titles.	required
title	str	Figure title.	required
height	int | None	Backend-specific height (text rows or pixels).	required

plot_correlation_heatmap(corr_df, title, threshold, precision)

Render a graphical heatmap for a correlation matrix.

The default implementation does nothing. Graphical backends (e.g. Plotly) override this method and set _supports_graphical_heatmap = True so the facade knows a heatmap was rendered.

Parameters:

Name	Type	Description	Default
corr_df	object	Square correlation DataFrame.	required
title	str	Figure title.	required
threshold	float | None	Absolute-correlation cutoff used for value labels.	required
precision	int	Number of decimals to show in labels and hover text.	required

plotly

Plotly plotting backend.

Provides an interactive plotting implementation using Plotly. In notebooks, figures are displayed inline; in other environments a browser renderer may be used depending on configuration.

Classes:

Name	Description
PowderCompositeRows	Resolved row layout for the composite powder figure.
PlotlyPlotter	Interactive plotter using Plotly for notebooks and browsers.

Functions:

Name	Description
single_crystal_axis_range	Return one shared (min, max) range for a single-crystal scatter.
single_crystal_tick_step	Return a 'nice' tick step covering [minimum, maximum].

Classes

PowderCompositeRows(row_count, row_heights, bragg_row, residual_row) dataclass

Resolved row layout for the composite powder figure.

PlotlyPlotter()

Interactive plotter using Plotly for notebooks and browsers.

Methods:

Name	Description
plot_correlation_heatmap	Render a Plotly heatmap for a correlation matrix.
serialize_html	Serialize a Plotly figure with EasyDiffraction controls.
plot_powder	Render a line plot for powder diffraction data.
plot_powder_meas_vs_calc	Render a composite powder plot with optional Bragg ticks.
build_powder_meas_vs_calc_figure	Build a composite powder Plotly figure without displaying it.
plot_single_crystal	Render a scatter plot for single crystal diffraction data.
build_single_crystal_figure	Build a single-crystal Plotly figure without displaying it.
plot_scatter	Render a scatter plot with error bars via Plotly.

Functions

plot_correlation_heatmap(corr_df, title, threshold, precision)

Render a Plotly heatmap for a correlation matrix.

Parameters:

Name	Type	Description	Default
corr_df	object	Square correlation DataFrame.	required
title	str	Figure title.	required
threshold	float | None	Absolute-correlation cutoff used for value labels.	required
precision	int	Number of decimals to show in labels and hover text.	required

serialize_html(fig, *, include_plotlyjs, mode=FigureEmbedMode.STANDALONE, force_template=None, axis_frame_color=None, grid_color=None) classmethod

Serialize a Plotly figure with EasyDiffraction controls.

Parameters:

Name	Type	Description	Default
fig	object	Plotly figure to serialize.	required
include_plotlyjs	bool | str	Plotly JavaScript inclusion mode passed to Plotly.	required
mode	FigureEmbedMode	Embedding mode. SHARED emits a lazy placeholder for the docs loader; INLINE/STANDALONE serialize eagerly.	FigureEmbedMode.STANDALONE
force_template	str | None	Optional template name applied before serialization.	None
axis_frame_color	str | None	Optional explicit axis-frame color.	None
grid_color	str | None	Optional explicit major-grid color.	None

Returns:

Type	Description
str	Inline HTML containing the figure and helper scripts.

plot_powder(x, y_series, labels, axes_labels, title, height=None, excluded_ranges=())

Render a line plot for powder diffraction data.

Suitable for powder diffraction data where intensity is plotted against an x-axis variable (2θ, TOF, d-spacing).

Parameters:

Name	Type	Description	Default
x	object	1D array-like of x-axis values.	required
y_series	object	Sequence of y arrays to plot.	required
labels	object	Series identifiers corresponding to y_series.	required
axes_labels	object	Pair of strings for the x and y titles.	required
title	str	Figure title.	required
height	int | None	Ignored; Plotly auto-sizes based on renderer.	None
excluded_ranges	tuple[tuple[float, float], ...]	Excluded x-ranges to shade on the figure.	()

plot_powder_meas_vs_calc(plot_spec)

Render a composite powder plot with optional Bragg ticks.

The main row shows measured and calculated intensities. The Bragg row is added only when tick data is available. The residual row is added only when residual data is requested.

build_powder_meas_vs_calc_figure(plot_spec)

Build a composite powder Plotly figure without displaying it.

Parameters:

Name	Type	Description	Default
plot_spec	PowderMeasVsCalcSpec	Composite powder-plot inputs and layout settings.	required

Returns:

Type	Description
object	Configured :class:plotly.graph_objects.Figure.

plot_single_crystal(x_calc, y_meas, y_meas_su, axes_labels, title, height=None)

Render a scatter plot for single crystal diffraction data.

Suitable for single crystal diffraction data where measured values are plotted against calculated values with error bars and a diagonal reference line.

Parameters:

Name	Type	Description	Default
x_calc	object	1D array-like of calculated values (x-axis).	required
y_meas	object	1D array-like of measured values (y-axis).	required
y_meas_su	object	1D array-like of measurement uncertainties.	required
axes_labels	object	Pair of strings for the x and y titles.	required
title	str	Figure title.	required
height	int | None	Ignored; Plotly auto-sizes based on renderer.	None

build_single_crystal_figure(*, x_calc, y_meas, y_meas_su, axes_labels, title)

Build a single-crystal Plotly figure without displaying it.

Parameters:

Name	Type	Description	Default
x_calc	object	1D array-like of calculated values (x-axis).	required
y_meas	object	1D array-like of measured values (y-axis).	required
y_meas_su	object	1D array-like of measurement uncertainties.	required
axes_labels	object	Pair of strings for the x and y titles.	required
title	str	Figure title.	required

Returns:

Type	Description
object	Configured :class:plotly.graph_objects.Figure.

plot_scatter(x, y, sy, axes_labels, title, height=None)

Render a scatter plot with error bars via Plotly.

Functions

single_crystal_axis_range(x_calc, y_meas, y_meas_su)

Return one shared (min, max) range for a single-crystal scatter.

The range spans the calculated values and the measured values widened by their standard uncertainties, then pads both ends by MAIN_INTENSITY_RANGE_MARGIN_FRACTION. Applying the same range to both axes keeps the y=x diagonal meaningful.

Parameters:

Name	Type	Description	Default
x_calc	object	1D array-like of calculated values (x-axis).	required
y_meas	object	1D array-like of measured values (y-axis).	required
y_meas_su	object	1D array-like of measurement uncertainties, or None.	required

Returns:

Type	Description
tuple[float, float]	The padded (minimum, maximum) shared by both axes.

single_crystal_tick_step(minimum, maximum, target_ticks=6)

Return a 'nice' tick step covering [minimum, maximum].

The raw step span / target_ticks is rounded to the nearest 1/2/5 multiple of a power of ten (the classic axis-label rounding), so the ticks read as round numbers and the same step gives identical x and y ticks over a shared range. Combined with a tick origin of 0 this reproduces Plotly's own choice (e.g. a 500 step, not 750).

Parameters:

Name	Type	Description	Default
minimum	float	Lower bound of the shared axis range.	required
maximum	float	Upper bound of the shared axis range.	required
target_ticks	int	Approximate number of tick intervals to aim for.	6

Returns:

Type	Description
float	The rounded tick step.

plotting

Plotting facade for measured and calculated patterns.

Uses the common :class:RendererBase so plotters and tablers share a consistent configuration surface and engine handling.

Classes:

Name	Description
PlotterEngineEnum	Available plotting engine backends.
PosteriorPairPlotStyleEnum	Available posterior pair-plot rendering modes.
Plotter	User-facing plotting facade backed by concrete plotters.
PlotterFactory	Factory for plotter implementations.

Classes

PlotterEngineEnum

Available plotting engine backends.

Methods:

Name	Description
default	Select default engine based on environment.
description	Human-readable description for UI listings.

Functions

default() classmethod

Select default engine based on environment.

description()

Human-readable description for UI listings.

PosteriorPairPlotStyleEnum

Available posterior pair-plot rendering modes.

Plotter()

User-facing plotting facade backed by concrete plotters.

Methods:

Name	Description
show_config	Display the current plotting configuration.
plot_meas	Plot measured diffraction data for an experiment.
plot_calc	Plot calculated diffraction pattern for an experiment.
plot_meas_vs_calc	Plot measured vs calculated data for an experiment.
plot_param_series	Plot a parameter's value across sequential fit results.
plot_all_param_series	Plot every fitted parameter across sequential fit results.
plot_param_correlations	Plot the parameter correlation matrix from the latest fit.
plot_posterior_pairs	Plot posterior pair relationships for sampled parameters.
plot_param_distribution	Plot the posterior distribution for one sampled parameter.
plot_posterior_predictive	Plot posterior predictive checks for supported experiments.
plot_param_series_from_snapshots	Plot a parameter's value from in-memory snapshots.
get	Return the shared instance, creating it if needed.
show_supported_engines	List supported engines with descriptions in a table.
show_current_engine	Display the currently selected engine.

Attributes:

Name	Type	Description
x_min	float	Minimum x-axis limit.
x_max	float	Maximum x-axis limit.
height	int	Plot height (rows for ASCII, pixels for Plotly).
engine	str	Return the name of the currently active rendering engine.

Attributes

x_min property writable

Minimum x-axis limit.

x_max property writable

Maximum x-axis limit.

height property writable

Plot height (rows for ASCII, pixels for Plotly).

engine property writable

Return the name of the currently active rendering engine.

Returns:

Type	Description
str	Identifier of the active engine.

Functions

show_config()

Display the current plotting configuration.

plot_meas(expt_name, x_min=None, x_max=None, x=None, *, show_excluded=False)

Plot measured diffraction data for an experiment.

Parameters:

Name	Type	Description	Default
expt_name	str	Name of the experiment to plot.	required
x_min	float | None	Lower bound for the x-axis range.	None
x_max	float | None	Upper bound for the x-axis range.	None
x	object | None	Optional explicit x-axis data to override stored values.	None
show_excluded	bool	Whether to show excluded fitting regions on supported plots.	False

plot_calc(expt_name, x_min=None, x_max=None, x=None, *, show_excluded=False)

Plot calculated diffraction pattern for an experiment.

Parameters:

Name	Type	Description	Default
expt_name	str	Name of the experiment to plot.	required
x_min	float | None	Lower bound for the x-axis range.	None
x_max	float | None	Upper bound for the x-axis range.	None
x	object | None	Optional explicit x-axis data to override stored values.	None
show_excluded	bool	Whether to show excluded fitting regions on supported plots.	False

plot_meas_vs_calc(expt_name, x_min=None, x_max=None, *, show_residual=None, show_excluded=False, x=None)

Plot measured vs calculated data for an experiment.

Parameters:

Name	Type	Description	Default
expt_name	str	Name of the experiment to plot.	required
x_min	float | None	Lower bound for the x-axis range.	None
x_max	float | None	Upper bound for the x-axis range.	None
show_residual	bool | None	When None, powder Bragg plots include the residual by default while other measured-vs-calculated plots keep the historical no-residual default.	None
show_excluded	bool	Whether to show excluded fitting regions on supported plots.	False
x	object | None	Optional explicit x-axis data to override stored values.	None

plot_param_series(param, versus=None)

Plot a parameter's value across sequential fit results.

When a results.csv file exists in the project's analysis/ directory, data is read from CSV. Otherwise, falls back to in-memory parameter snapshots (produced by fit() in single mode).

Parameters:

Name	Type	Description	Default
param	object	Descriptor whose unique_name or name identifies the values to plot.	required
versus	str | None	Persisted diffrn path (e.g. 'diffrn.ambient_temperature') whose sequential-results column is used as the x-axis. When None, the experiment sequence number is used instead.	None

plot_all_param_series(versus=None)

Plot every fitted parameter across sequential fit results.

Iterates the fitted parameters recorded in results.csv (or, when absent, in the in-memory parameter snapshots) and emits one plot_param_series plot per parameter.

Parameters:

Name	Type	Description	Default
versus	str | None	Persisted diffrn path (e.g. 'diffrn.ambient_temperature') whose sequential-results column is used as the x-axis. When None, the experiment sequence number is used instead.	None

plot_param_correlations(threshold=DEFAULT_CORRELATION_THRESHOLD, precision=2, *, max_parameters=DEFAULT_CORRELATION_MAX_PARAMETERS, show_diagonal=True)

Plot the parameter correlation matrix from the latest fit.

The matrix is taken from project.analysis.fit_results. When the active engine is Plotly, an interactive heatmap is shown. Otherwise, a rounded correlation table is rendered.

By default the lower triangle is shown with blank diagonal cells so the grid stays square, like posterior pair plots. Set show_diagonal=False to trim the empty outer row and column.

Parameters:

Name	Type	Description	Default
threshold	float | None	Minimum absolute off-diagonal correlation required for a parameter to be shown. When omitted, an automatic cutoff is chosen so the displayed matrix stays at or below max_parameters x max_parameters when possible. Set to 0 to show the full matrix.	DEFAULT_CORRELATION_THRESHOLD
precision	int	Number of decimal places to show in the table fallback.	2
max_parameters	int	Maximum number of parameters to display when threshold is omitted. Ignored when threshold is provided.	DEFAULT_CORRELATION_MAX_PARAMETERS
show_diagonal	bool	Whether to retain blank diagonal cells in the displayed lower-triangle matrix.	True

plot_posterior_pairs(parameters=None, style='auto', *, threshold=DEFAULT_CORRELATION_THRESHOLD, max_parameters=DEFAULT_CORRELATION_MAX_PARAMETERS)

Plot posterior pair relationships for sampled parameters.

Parameters:

Name	Type	Description	Default
parameters	list[object] | None	Optional subset of sampled parameters to include. When provided, threshold and max_parameters are ignored.	None
style	PosteriorPairPlotStyleEnum | str	Pair-plot rendering mode. Defaults to 'auto'. 'auto' keeps contours for compact plots and disables them for wide grids. 'fast' always skips contours. 'full' always renders contours.	'auto'
threshold	float | None	Minimum absolute off-diagonal correlation required for a parameter to be auto-selected. When omitted, an automatic cutoff keeps the plot at or below max_parameters parameters when possible. Set to 0 to show all sampled parameters.	DEFAULT_CORRELATION_THRESHOLD
max_parameters	int	Maximum number of parameters to auto-select when parameters is omitted and threshold is None. Must be at least 2.	DEFAULT_CORRELATION_MAX_PARAMETERS

plot_param_distribution(param)

Plot the posterior distribution for one sampled parameter.

Parameters:

Name	Type	Description	Default
param	object	Parameter descriptor or string identifier selecting the posterior to plot. Strings may be unique names or user-facing labels.	required

plot_posterior_predictive(expt_name, style='band', x_min=None, x_max=None, *, show_residual=None, show_excluded=False, x=None)

Plot posterior predictive checks for supported experiments.

Parameters:

Name	Type	Description	Default
expt_name	str	Experiment name to plot.	required
style	str	'band' shows the 95% credible interval, 'draws' shows sampled predictive curves, and 'band+draws' shows both together. ASCII powder plots fall back to measured and max-posterior lines without uncertainty bands or draws. Single-crystal plots currently render only the interval- based reflection check.	'band'
x_min	float | None	Lower bound for the x-axis range.	None
x_max	float | None	Upper bound for the x-axis range.	None
show_residual	bool | None	Whether to include the residual row in supported powder composite plots.	None
show_excluded	bool	Whether to show excluded fitting regions on supported plots.	False
x	object | None	Optional explicit x-axis data to override stored values.	None

Raises:

Type	Description
ValueError	If style is not one of 'band', 'draws', or 'band+draws'.

plot_param_series_from_snapshots(unique_name, versus_path, experiments, parameter_snapshots)

Plot a parameter's value from in-memory snapshots.

This is a backward-compatibility method used when no CSV file is available (e.g. after fit() in single mode, before PR 13 adds CSV output to the existing fit loop).

Parameters:

Name	Type	Description	Default
unique_name	str	Unique name of the parameter to plot.	required
versus_path	str | None	Persisted diffrn path for the x-axis.	required
experiments	object	Experiments collection for accessing diffrn conditions.	required
parameter_snapshots	dict[str, dict[str, dict]]	Per-experiment parameter value snapshots.	required

get() classmethod

Return the shared instance, creating it if needed.

show_supported_engines()

List supported engines with descriptions in a table.

show_current_engine()

Display the currently selected engine.

PlotterFactory

Factory for plotter implementations.

Methods:

Name	Description
create	Create a backend instance for the given engine.
supported_engines	Return a list of supported engine identifiers.
descriptions	Return (name, description) pairs for each engine.

Functions

create(engine_name) classmethod

Create a backend instance for the given engine.

Parameters:

Name	Type	Description	Default
engine_name	str	Identifier of the engine to instantiate as listed in _registry().	required

Returns:

Type	Description
object	A new backend instance corresponding to engine_name.

Raises:

Type	Description
ValueError	If the engine name is not supported.

supported_engines() classmethod

Return a list of supported engine identifiers.

descriptions() classmethod

Return (name, description) pairs for each engine.

Functions

progress

Environment-aware activity indicator for long-running tasks.

Classes:

Name	Description
ActivityIndicator	Render a live activity indicator for long-running work.
NotebookFitStopControl	Display a Jupyter stop button for fitting runs.

Functions:

Name	Description
resolve_activity_terminal_style	Return a terminal-safe activity indicator style.
make_display_handle	Create a generic in-place display handle for the active environment.
activity_indicator	Manage an activity indicator around a block of work.
notebook_fit_stop_control	Return a notebook stop-control context for fitting runs.

Classes

ActivityIndicator(label=ACTIVITY_LABEL_PROCESSING, *, verbosity, display_handle=None, animated=True, refresh_per_second=None)

Render a live activity indicator for long-running work.

Parameters:

Name	Type	Description	Default
label	str	User-facing activity label.	ACTIVITY_LABEL_PROCESSING
verbosity	VerbosityEnum	Output verbosity controlling whether live display is shown.	required
display_handle	object | None	Optional existing live display handle to reuse.	None
animated	bool	Whether to animate the spinner label continuously.	True
refresh_per_second	float | None	Optional override for the Rich Live refresh rate. When None, defaults to one refresh per spinner frame. Lower values reduce terminal flicker for multi-line live regions.	None

Methods:

Name	Description
start	Start the live activity indicator.
update	Refresh the current label and optional rendered content.
stop	Stop live rendering and keep optional final content visible.

Functions

start()

Start the live activity indicator.

Returns:

Type	Description
None	Starts live rendering unless verbosity is silent.

update(*, label=None, content=None)

Refresh the current label and optional rendered content.

Parameters:

Name	Type	Description	Default
label	str | None	Replacement activity label. When None, keep the current label.	None
content	object | None	Optional content rendered above the indicator. When None, keep the current content.	None

stop(*, final_label=None)

Stop live rendering and keep optional final content visible.

Parameters:

Name	Type	Description	Default
final_label	str | None	Optional final label to leave in place after stopping. When omitted, only the current content remains visible.	None

NotebookFitStopControl(*, verbosity)

Display a Jupyter stop button for fitting runs.

Methods:

Name	Description
__enter__	Show the stop button.
__exit__	Update or clear the stop button when leaving the context.
show	Render the stop button when running in a notebook.
close	Clear the stop button when fitting ends.

Functions

__enter__()

Show the stop button.

__exit__(exc_type, exc_value, traceback)

Update or clear the stop button when leaving the context.

show()

Render the stop button when running in a notebook.

close()

Clear the stop button when fitting ends.

Functions

resolve_activity_terminal_style(console=None)

Return a terminal-safe activity indicator style.

Parameters:

Name	Type	Description	Default
console	object | None	Console-like object whose color_system determines whether the accent color can be rendered directly.	None

Returns:

Type	Description
str	The preferred terminal style for the current console.

make_display_handle(*, auto_refresh=True)

Create a generic in-place display handle for the active environment.

Parameters:

Name	Type	Description	Default
auto_refresh	bool	Whether a terminal live handle should refresh continuously.	True

Returns:

Type	Description
object | None	An IPython DisplayHandle in notebooks, a terminal live handle in the console, or None if neither is available.

activity_indicator(label=ACTIVITY_LABEL_PROCESSING, *, verbosity)

Manage an activity indicator around a block of work.

Parameters:

Name	Type	Description	Default
label	str	User-facing activity label.	ACTIVITY_LABEL_PROCESSING
verbosity	VerbosityEnum	Output verbosity controlling whether live display is shown.	required

Returns:

Type	Description
AbstractContextManager[ActivityIndicator]	Context manager that starts the indicator on entry and stops it on exit.

notebook_fit_stop_control(*, verbosity)

Return a notebook stop-control context for fitting runs.

structure

crysview structure-visualization subsystem.

Modules:

Name	Description
assets	Bundled element data and lookups for the structure view.
builder	Scene builder: crystal structure to renderer-neutral scene.
enums	Enumerations for the crysview structure view.
renderers	Structure-scene renderer engines.
scene	Renderer-neutral structure scene primitives.
viewing	Viewer facade and engine factory for the structure view.

Classes

Modules

assets

Bundled element data and lookups for the structure view.

Modules:

Name	Description
colors	Per-element colours, axis colours, and theme-dependent contrast colours.
elements	Bundled per-element radii and colour palettes.
radii	Per-element radius lookup with covalent fallback.

Modules

colors

Per-element colours, axis colours, and theme-dependent contrast colours.

Functions:

Name	Description
color_for	Return the RGB colour for an element under a colour scheme.
theme_colors	Return annotation contrast colours for the detected theme.

Functions

color_for(element, scheme)

Return the RGB colour for an element under a colour scheme.

Falls back to the element's Jmol colour when the scheme has no entry, and to :data:DEFAULT_COLOR when the element is unknown.

Parameters:

Name	Type	Description	Default
element	str	Bare element symbol, e.g. 'Fe'.	required
scheme	str	One of 'jmol', 'vesta'.	required

Returns:

Type	Description
Rgb	RGB triple in the 0-255 range.

theme_colors(*, dark)

Return annotation contrast colours for the detected theme.

Parameters:

Name	Type	Description	Default
dark	bool	True for a dark host theme, False for light.	required

Returns:

Type	Description
dict[str, Rgb]	Mapping with 'background' and 'foreground' colours.

elements

Bundled per-element radii and colour palettes.

Generated data module; see LICENSES.md for provenance.

radii

Per-element radius lookup with covalent fallback.

Functions:

Name	Description
radius_for	Return a sphere radius for an element under a radius model.

Functions

radius_for(element, model)

Return a sphere radius for an element under a radius model.

Falls back to the element's covalent radius when the selected model has no value for it, and to :data:DEFAULT_RADIUS when the element is unknown.

Parameters:

Name	Type	Description	Default
element	str	Bare element symbol, e.g. 'Fe'.	required
model	str	One of 'vdw', 'covalent', 'ionic'.	required

Returns:

Type	Description
tuple[float, bool]	The radius (angstrom) and a substituted flag that is True when the requested model's value was unavailable and a fallback was used.

builder

Scene builder: crystal structure to renderer-neutral scene.

The easydiffraction-specific adapter. It reads the structure categories, performs symmetry expansion, fractional-to-Cartesian conversion, ADP eigendecomposition, radius/colour lookup, occupancy splitting, and bond detection, and emits a :class:StructureScene. All crystallographic computation lives here so renderers stay thin.

Classes:

Name	Description
FeatureAvailability	What a structure's data supports, for 'auto' resolution + options.

Functions:

Name	Description
build_scene	Build a renderer-neutral scene from a structure.
structure_feature_availability	Report which features a structure supports.

Classes

FeatureAvailability(available, radius_substitutions) dataclass

What a structure's data supports, for 'auto' resolution + options.

Functions

build_scene(structure, *, style, view_range, features)

Build a renderer-neutral scene from a structure.

Builds the scene from the structure and the already-resolved features.

Parameters:

Name	Type	Description	Default
structure	object	A structure datablock with cell, atom_sites, atom_site_aniso, space_group and geom categories.	required
style	object	The project.structure_style category (atom view, colour scheme, ADP probability, atom scale).	required
view_range	ViewRange	Per-axis ((min, max), (min, max), (min, max)) fractional range.	required
features	frozenset[str]	The already-resolved set of primitives to emit (never 'auto'); the builder never re-implements visibility precedence.	required

Returns:

Type	Description
StructureScene	The flat Cartesian primitive set for the renderers.

structure_feature_availability(structure, *, style)

Report which features a structure supports.

Computes availability without building a scene. Used by the display facade for include='auto' resolution and by show_structure_options(); the builder is the only reader of the structure, so availability is computed once here.

Parameters:

Name	Type	Description	Default
structure	object	A structure datablock.	required
style	object	The project.structure_style category (its atom view drives the covalent-substitution report).	required

Returns:

Type	Description
FeatureAvailability	Available feature names and the elements whose radius fell back to covalent under the selected model.

Modules

enums

Enumerations for the crysview structure view.

Classes:

Name	Description
ViewerEngineEnum	Available structure-view renderer engines.
AtomViewEnum	How atoms are sized and shaped in the structure view.
ColorSchemeEnum	Standard element colour palette.

Classes

ViewerEngineEnum

Available structure-view renderer engines.

Methods:

Name	Description
default	Select the default engine based on environment.
description	Human-readable description for UI listings.

Functions

default() classmethod

Select the default engine based on environment.

description()

Human-readable description for UI listings.

AtomViewEnum

How atoms are sized and shaped in the structure view.

The radius models draw fixed balls; adp draws displacement surfaces (spheres for isotropic sites, ellipsoids for anisotropic).

Methods:

Name	Description
default	Select the default atom view (covalent-radius balls).
radius_model	Return the radius-table name for ball sizing.
description	Human-readable description for UI listings.

Attributes:

Name	Type	Description
is_adp	bool	Return whether atoms are drawn as displacement surfaces.

Attributes

is_adp property

Return whether atoms are drawn as displacement surfaces.

Functions

default() classmethod

Select the default atom view (covalent-radius balls).

radius_model()

Return the radius-table name for ball sizing.

The adp view still needs ball radii for mixed-occupancy sites and as a fallback for zero-displacement atoms, where it uses covalent radii.

description()

Human-readable description for UI listings.

ColorSchemeEnum

Standard element colour palette.

Methods:

Name	Description
default	Select the default colour scheme (Jmol/CPK).
description	Human-readable description for UI listings.

Functions

default() classmethod

Select the default colour scheme (Jmol/CPK).

description()

Human-readable description for UI listings.

Functions

renderers

Structure-scene renderer engines.

Modules:

Name	Description
ascii	ASCII terminal renderer: a schematic single-cell structure view.
base	Abstract base for structure-scene renderer engines.
raster	Raster renderer: a z-buffered PNG structure image for reports.
threejs	Three.js renderer: an interactive, self-contained HTML structure view.

Classes

Modules

ascii

ASCII terminal renderer: a schematic single-cell structure view.

Classes:

Name	Description
AsciiStructureRenderer	Reduced-fidelity terminal renderer (one schematic cell).

Classes

AsciiStructureRenderer

Reduced-fidelity terminal renderer (one schematic cell).

Methods:

Name	Description
supported_features	Return the features the ASCII engine can draw.
render	Render a schematic ASCII view and announce 3D-only features.

Functions

supported_features()

Return the features the ASCII engine can draw.

render(scene, *, features)

Render a schematic ASCII view and announce 3D-only features.

Parameters:

Name	Type	Description	Default
scene	StructureScene	The renderer-neutral primitives to draw.	required
features	frozenset[str]	The content-resolved feature set from the facade.	required

Returns:

Type	Description
str	The schematic single-cell ASCII view.

base

Abstract base for structure-scene renderer engines.

Classes:

Name	Description
StructureRendererBase	Base class an engine implements to draw a structure scene.

Classes

StructureRendererBase

Base class an engine implements to draw a structure scene.

Methods:

Name	Description
render	Draw the scene and return the engine-specific output.
supported_features	Return the feature names this engine can draw.

Functions

render(scene, *, features) abstractmethod

Draw the scene and return the engine-specific output.

Parameters:

Name	Type	Description	Default
scene	StructureScene	The renderer-neutral primitives to draw.	required
features	frozenset[str]	The content-resolved feature set from the facade. The renderer draws the features it supports and announces + skips the rest.	required

Returns:

Type	Description
str	ASCII text or an HTML document, depending on the engine.

Raises:

Type	Description
NotImplementedError	Always; subclasses must override this method.

supported_features() abstractmethod

Return the feature names this engine can draw.

Returns:

Type	Description
frozenset[str]	Subset of atoms, bonds, cell, axes, moments, labels.

Raises:

Type	Description
NotImplementedError	Always; subclasses must override this method.

raster

Raster renderer: a z-buffered PNG structure image for reports.

A tiny software rasteriser with a per-pixel depth buffer, so hidden-surface removal is exact for any structure. Spheres, bonds, cell edges, and axis arrows are all depth-tested against the same numpy buffer; Pillow then draws the a/b/c axis labels and the element legend on top and encodes the PNG.

Classes:

Name	Description
RasterStructureRenderer	Render a structure scene as a z-buffered PNG image.

Classes

RasterStructureRenderer

Render a structure scene as a z-buffered PNG image.

Methods:

Name	Description
render_png	Return PNG bytes of the scene with a per-pixel z-buffer.

Functions

render_png(scene, *, features)

Return PNG bytes of the scene with a per-pixel z-buffer.

threejs

Three.js renderer: an interactive, self-contained HTML structure view.

Classes:

Name	Description
ThreeJsStructureRenderer	Interactive Three.js renderer for notebook and standalone HTML.

Classes

ThreeJsStructureRenderer

Interactive Three.js renderer for notebook and standalone HTML.

Methods:

Name	Description
supported_features	Return the features the Three.js engine can draw.
render	Render the scene as a self-contained interactive HTML document.

Functions

supported_features()

Return the features the Three.js engine can draw.

render(scene, *, features, offline=True, dark=None, mode=None)

Render the scene as a self-contained interactive HTML document.

Parameters:

Name	Type	Description	Default
scene	StructureScene	The renderer-neutral primitives to draw.	required
features	frozenset[str]	The content-resolved feature set; drives the modebar's initial visibility toggles.	required
offline	bool	When True (default), inline the pinned Three.js assets so the view renders with no network; when False link the CDN.	True
dark	bool | None	Force the dark (True) or light (False) theme. When None (default), auto-detect from the environment. Reports pass False so the view matches their light page.	None
mode	FigureEmbedMode | None	Embedding mode; None resolves from the environment. SHARED (docs) omits the per-scene import map and relies on the page-level one; INLINE/STANDALONE emit a per-scene import map per offline.	None

Returns:

Type	Description
str	A complete HTML document.

Functions

scene

Renderer-neutral structure scene primitives.

A :class:StructureScene is a flat set of typed primitives expressed in Cartesian space, carrying no rendering-library or easydiffraction-domain types. The scene builder produces it; renderers consume it. Keeping this module free of domain imports lets the scene model be extracted into a standalone crysview package later.

Classes:

Name	Description
AtomSphere	A single-occupancy atom drawn as a coloured sphere.
OccupancyWedge	One occupancy share (or vacancy) of a mixed site.
OccupancyWedgeSphere	A mixed-occupancy site drawn as a sphere split into wedges.
AdpEllipsoid	An anisotropic ADP probability ellipsoid for one atom.
Bond	A bond between two atoms, split-coloured at its midpoint.
MomentArrow	A magnetic-moment arrow (defined but unused in version 1).
CellEdge	One unit-cell edge as a Cartesian segment.
CellEdges	The twelve unit-cell edges as Cartesian segments.
AxisArrow	One crystallographic axis arrow (a, b, or c).
AxisTriad	The a/b/c axis triad drawn from the cell origin.
TextLabel	A text label anchored at a Cartesian point.
LegendEntry	One element's colour swatch and symbol for the structure legend.
StructureScene	Renderer-neutral Cartesian primitives for one structure.

Classes

AtomSphere(centre, radius, colour, label, asymmetric=False) dataclass

A single-occupancy atom drawn as a coloured sphere.

OccupancyWedge(fraction, colour) dataclass

One occupancy share (or vacancy) of a mixed site.

OccupancyWedgeSphere(centre, radius, wedges, label, asymmetric=False) dataclass

A mixed-occupancy site drawn as a sphere split into wedges.

AdpEllipsoid(centre, semi_axes, orientation, colour, label, wedges=(), asymmetric=False) dataclass

An anisotropic ADP probability ellipsoid for one atom.

wedges splits a shared site into relative-proportion colour wedges (empty for a single atom, which uses colour).

Bond(start, end, start_colour, end_colour, start_element='', end_element='') dataclass

A bond between two atoms, split-coloured at its midpoint.

MomentArrow(origin, vector, colour) dataclass

A magnetic-moment arrow (defined but unused in version 1).

CellEdge(start, end) dataclass

One unit-cell edge as a Cartesian segment.

CellEdges(edges) dataclass

The twelve unit-cell edges as Cartesian segments.

AxisArrow(vector, colour, letter) dataclass

One crystallographic axis arrow (a, b, or c).

AxisTriad(origin, axes) dataclass

The a/b/c axis triad drawn from the cell origin.

TextLabel(anchor, text) dataclass

A text label anchored at a Cartesian point.

LegendEntry(symbol, colour) dataclass

One element's colour swatch and symbol for the structure legend.

StructureScene(cell_basis, atoms=(), occupancy_spheres=(), ellipsoids=(), bonds=(), moments=(), cell_edges=None, axes=None, labels=(), legend=()) dataclass

Renderer-neutral Cartesian primitives for one structure.

viewing

Viewer facade and engine factory for the structure view.

Classes:

Name	Description
ViewerFactory	Factory for structure-view renderer engines.
Viewer	Switchable facade that draws a scene with the active engine.

Classes

ViewerFactory

Factory for structure-view renderer engines.

Methods:

Name	Description
create	Create a backend instance for the given engine.
supported_engines	Return a list of supported engine identifiers.
descriptions	Return (name, description) pairs for each engine.

Functions

create(engine_name) classmethod

Create a backend instance for the given engine.

Parameters:

Name	Type	Description	Default
engine_name	str	Identifier of the engine to instantiate as listed in _registry().	required

Returns:

Type	Description
object	A new backend instance corresponding to engine_name.

Raises:

Type	Description
ValueError	If the engine name is not supported.

supported_engines() classmethod

Return a list of supported engine identifiers.

descriptions() classmethod

Return (name, description) pairs for each engine.

Viewer()

Switchable facade that draws a scene with the active engine.

Methods:

Name	Description
show_config	Display the active structure-view engine.
render	Draw the scene with the active engine.
supported_features	Return the feature names the active engine can draw.
get	Return the shared instance, creating it if needed.
show_supported_engines	List supported engines with descriptions in a table.
show_current_engine	Display the currently selected engine.

Attributes:

Name	Type	Description
engine	str	Return the name of the currently active rendering engine.

Attributes

engine property writable

Return the name of the currently active rendering engine.

Returns:

Type	Description
str	Identifier of the active engine.

Functions

show_config()

Display the active structure-view engine.

render(scene, *, features)

Draw the scene with the active engine.

Parameters:

Name	Type	Description	Default
scene	StructureScene	The renderer-neutral primitives to draw.	required
features	frozenset[str]	The content-resolved feature set from the display facade.	required

Returns:

Type	Description
str	ASCII text or an HTML document, depending on the active engine.

supported_features()

Return the feature names the active engine can draw.

get() classmethod

Return the shared instance, creating it if needed.

show_supported_engines()

List supported engines with descriptions in a table.

show_current_engine()

Display the currently selected engine.

tablers

Tabular rendering backends.

This subpackage provides concrete implementations for rendering tables in different environments:

• :mod:.rich for terminal and notebooks using the Rich library. - :mod:.pandas for notebooks using DataFrame Styler.

Modules:

Name	Description
base	Low-level backends for rendering tables.
pandas	Pandas-input table renderer emitting inline-styled HTML for notebooks.
rich	Rich-based table renderer for terminals and notebooks.

Modules

base

Low-level backends for rendering tables.

This module defines the abstract base for tabular renderers and small helpers for consistent styling across terminal and notebook outputs.

Classes:

Name	Description
TableBackendBase	Abstract base class for concrete table backends.

Classes

TableBackendBase()

Abstract base class for concrete table backends.

Subclasses implement the render method which receives an index- aware pandas DataFrame and the alignment for each column header.

Methods:

Name	Description
build_renderable	Build a backend-native table representation.
render	Render the provided DataFrame with backend-specific styling.

Functions

build_renderable(alignments, df) abstractmethod

Build a backend-native table representation.

Parameters:

Name	Type	Description	Default
alignments	object	Iterable of column justifications (e.g., 'left' or 'center') corresponding to the data columns.	required
df	object	Index-aware DataFrame with data to render.	required

Returns:

Type	Description
object	Backend-native renderable, such as a Rich table or HTML.

render(alignments, df, display_handle=None, width=None) abstractmethod

Render the provided DataFrame with backend-specific styling.

Parameters:

Name	Type	Description	Default
alignments	object	Iterable of column justifications (e.g., 'left' or 'center') corresponding to the data columns.	required
df	object	Index-aware DataFrame with data to render.	required
display_handle	object | None	Optional environment-specific handle to enable in-place updates.	None
width	int | None	Optional target table width. Honored by fixed-width backends (e.g. Rich); ignored by reflowing ones (e.g. HTML).	None

Returns:

Type	Description
object	Backend-defined return value (commonly None).

Functions

pandas

Pandas-input table renderer emitting inline-styled HTML for notebooks.

Classes:

Name	Description
PandasTableBackend	Render tables as inline-styled HTML for Jupyter notebooks.

Classes

PandasTableBackend()

Render tables as inline-styled HTML for Jupyter notebooks.

Every style is inlined on the table elements rather than collected in a pandas Styler <style> block. Inline styles survive JupyterLab's untrusted-output sanitisation, so a saved notebook reopened before re-execution still shows the themed table instead of falling back to the host default (bold index, row striping).

Methods:

Name	Description
build_renderable	Build notebook HTML for the provided table.
render	Render an inline-styled HTML table in Jupyter.

Functions

build_renderable(alignments, df)

Build notebook HTML for the provided table.

Parameters:

Name	Type	Description	Default
alignments	object	Per-column text alignments.	required
df	object	Index-aware DataFrame whose index is shown as the first column.	required

Returns:

Type	Description
object	Inline-styled HTML string for the table.

render(alignments, df, display_handle=None, width=None)

Render an inline-styled HTML table in Jupyter.

Parameters:

Name	Type	Description	Default
alignments	object	Per-column text alignments.	required
df	object	Index-aware DataFrame whose index is shown as the first column.	required
display_handle	object | None	Optional IPython DisplayHandle for in-place updates.	None
width	int | None	Ignored. HTML tables reflow to the available width.	None

Returns:

Type	Description
object	None; the table is displayed as a side effect.

Functions

rich

Rich-based table renderer for terminals and notebooks.

Classes:

Name	Description
RichTableBackend	Render tables to terminal or Jupyter using the Rich library.

Classes

RichTableBackend()

Render tables to terminal or Jupyter using the Rich library.

Methods:

Name	Description
build_renderable	Construct a Rich Table with formatted data and alignment.
render	Render a styled table using Rich.

Functions

build_renderable(alignments, df)

Construct a Rich Table with formatted data and alignment.

Parameters:

Name	Type	Description	Default
alignments	object	Iterable of text alignment values for columns.	required
df	object	DataFrame-like object providing rows to render.	required

Returns:

Type	Description
object	A :class:~rich.table.Table configured for display.

render(alignments, df, display_handle=None, width=None)

Render a styled table using Rich.

Parameters:

Name	Type	Description	Default
alignments	object	Iterable of text-align values for columns.	required
df	object	Index-aware DataFrame to render.	required
display_handle	object	Optional environment handle for in-place updates.	None
width	int | None	Optional target table width. When set, the table is sized to this width so long cells wrap to fit the terminal.	None

Returns:

Type	Description
object	Backend-defined return value (commonly None).

Functions

tables

Table rendering engines: console (Rich) and Jupyter (pandas).

Classes:

Name	Description
TableEngineEnum	Available table rendering backends.
TableRenderer	Renderer for tabular data with selectable engines (singleton).
TableRendererFactory	Factory for creating tabler instances.

Classes

TableEngineEnum

Available table rendering backends.

Methods:

Name	Description
default	Select default engine based on environment.
description	Return a human-readable description of this table engine.

Functions

default() classmethod

Select default engine based on environment.

Returns Pandas when running in Jupyter, otherwise Rich.

description()

Return a human-readable description of this table engine.

Returns:

Type	Description
str	Description string for the current enum member.

TableRenderer()

Renderer for tabular data with selectable engines (singleton).

Methods:

Name	Description
show_config	Display minimal configuration for this renderer.
build_renderable	Build a backend-native renderable without displaying it.
render	Render a DataFrame as a table using the active backend.
get	Return the shared instance, creating it if needed.
show_supported_engines	List supported engines with descriptions in a table.
show_current_engine	Display the currently selected engine.

Attributes:

Name	Type	Description
engine	str	Return the name of the currently active rendering engine.

Attributes

engine property writable

Return the name of the currently active rendering engine.

Returns:

Type	Description
str	Identifier of the active engine.

Functions

show_config()

Display minimal configuration for this renderer.

build_renderable(df)

Build a backend-native renderable without displaying it.

Parameters:

Name	Type	Description	Default
df	object	DataFrame with a two-level column index where the second level provides per-column alignment.	required

Returns:

Type	Description
object	Backend-native renderable, such as a Rich table or HTML.

render(df, display_handle=None, width=None)

Render a DataFrame as a table using the active backend.

Parameters:

Name	Type	Description	Default
df	object	DataFrame with a two-level column index where the second level provides per-column alignment.	required
display_handle	object | None	Optional environment-specific handle used to update an existing output area in-place (e.g., an IPython DisplayHandle or a terminal live handle).	None
width	int | None	Optional target table width passed to the backend. Honored by fixed-width backends (Rich); ignored by HTML.	None

Returns:

Type	Description
object	Backend-specific return value (usually None).

get() classmethod

Return the shared instance, creating it if needed.

show_supported_engines()

List supported engines with descriptions in a table.

show_current_engine()

Display the currently selected engine.

TableRendererFactory

Factory for creating tabler instances.

Methods:

Name	Description
create	Create a backend instance for the given engine.
supported_engines	Return a list of supported engine identifiers.
descriptions	Return (name, description) pairs for each engine.

Functions

create(engine_name) classmethod

Create a backend instance for the given engine.

Parameters:

Name	Type	Description	Default
engine_name	str	Identifier of the engine to instantiate as listed in _registry().	required

Returns:

Type	Description
object	A new backend instance corresponding to engine_name.

Raises:

Type	Description
ValueError	If the engine name is not supported.

supported_engines() classmethod

Return a list of supported engine identifiers.

descriptions() classmethod

Return (name, description) pairs for each engine.

Functions

theme

Shared display theme colors for plots and notebook tables.

Classes:

Name	Description
DisplayThemeColors	Theme colors shared by interactive display outputs.

Functions:

Name	Description
hex_to_rgb	Return the RGB triple for a hex color string.
display_theme_colors	Return the display colors for the requested theme.
display_theme_colors_for_template	Return display colors for a Plotly template name.

Classes

DisplayThemeColors(background, foreground, axis_frame, inner_tick_grid, hover_background, legend_background) dataclass

Theme colors shared by interactive display outputs.

Attributes:

Name	Type	Description
background	str	Plot or output background color.
foreground	str	Primary text color.
axis_frame	str	Axis rectangle and table border color.
inner_tick_grid	str	Inner Plotly tick-grid color.
hover_background	str	Plotly hover label background color.
legend_background	str	Plotly legend background color.

Functions

hex_to_rgb(value)

Return the RGB triple for a hex color string.

Parameters:

Name	Type	Description	Default
value	str	Hex color in #rgb or #rrggbb form.	required

Returns:

Type	Description
tuple[int, int, int]	Red, green, and blue components in the 0-255 range.

display_theme_colors(*, is_dark_theme)

Return the display colors for the requested theme.

Parameters:

Name	Type	Description	Default
is_dark_theme	bool	Whether to return the dark theme colors.	required

Returns:

Type	Description
DisplayThemeColors	Shared colors for the requested theme.

display_theme_colors_for_template(template)

Return display colors for a Plotly template name.

Parameters:

Name	Type	Description	Default
template	str	Plotly template name.	required

Returns:

Type	Description
DisplayThemeColors | None	Theme colors for known Plotly templates, otherwise None.

utils

Classes:

Name	Description
JupyterScrollManager	Ensures Jupyter output cells are not scrollable (once).

Classes

JupyterScrollManager

Ensures Jupyter output cells are not scrollable (once).

Methods:

Name	Description
disable_jupyter_scroll	Inject CSS to prevent output cells from being scrollable.

Functions

disable_jupyter_scroll() classmethod

Inject CSS to prevent output cells from being scrollable.

Functions