uchrom.pl¶

uchrom.pl.plot_contact_map(matrix: ndarray, bin_ids: Sequence | None = None, title: str | None = None, cmap: str = 'magma', ax=None)[source]¶: Heatmap of a (n_bins, n_bins) contact frequency matrix (values in [0, 1]).

uchrom.pl.plot_distance_matrix(matrix: ndarray, bin_ids: Sequence | None = None, title: str | None = None, cmap: str = 'viridis_r', ax=None)[source]¶: Heatmap of a (n_bins, n_bins) population-mean distance matrix.

uchrom.pl.plot_rg_histogram(rg_series, bins: int = 30, title: str | None = None, ax=None)[source]¶: Histogram of per-trace radii of gyration.

uchrom.pl.plot_structure_3d(cd_or_coords: Any, chrom: str | None = None, trace_id: int | str | None = None, colour: str | Sequence | ndarray = 'bin', cmap: str = 'viridis', tube_radius: float | None = None, spline_smoothing: bool = True, background: str = 'white', show_scalar_bar: bool | None = None, save_png: str | None = None, window_size: Tuple[int, int] = (900, 700), show: bool = True, plotter: Any = None, notebook: bool | None = None, jupyter_backend: str = 'static', bond_outlier_factor: float | None = None)[source]¶

Render a ChromData (or (n_bins, 3) coords) as a 3-D tube.

Parameters:

cd_or_coords (ChromData or ndarray (n_bins, 3)) – The structure to plot. A ChromData is sorted by (chrom, trace_id, start) and broken into contiguous sub-chains, each drawn as one tube so discontinuities are not bridged by fake edges.
chrom (str, optional) – Restrict to one chromosome.
trace_id (int or str, optional) – Restrict to one trace / allele.
colour ('bin' | 'chrom' | 'trace' | named colour | ndarray) – See the module docstring for the full colour contract.
cmap (str) – Matplotlib colour-map name used when colour is a gradient or a scalar array.
tube_radius (float, optional) – Radius of the rendered tube. If None, auto-picks 1.5 % of the bounding-box diagonal.
spline_smoothing (bool) – If True, interpolate each sub-chain with a Catmull-Rom-style spline before piping (nicer curvature at sharp bends).
background (str) – Colour of the plotter background.
show_scalar_bar (bool, optional) – Whether to render a colour-bar (default: auto based on colour mode).
save_png (str, optional) – If given, write a PNG to this path.
window_size ((int, int)) – Renderer resolution in pixels.
show (bool) – If True, call plotter.show() at the end (pops a window or renders inline in a notebook).
plotter (pyvista.Plotter, optional) – Add to an existing plotter instead of creating one.
notebook (bool, optional) – If None, auto-detect.
jupyter_backend (str) – Passed to plotter.show(jupyter_backend=...) — 'static' renders an inline image (safest for nbconvert / CI), 'trame' gives an interactive widget.
bond_outlier_factor (float, optional) – If set, any consecutive-bin bond longer than factor * median_bond is treated as a discontinuity and the chain is split at that point (rendered as two separate tubes with a visible gap). Default None keeps the chain continuous — use this when the algorithm produces a legitimate chain that just happens to have a scale mismatch between intra-TAD bonds and inter-TAD boundary bonds (the typical two-stage reconstruction case). Set to e.g. 50 to catch only pathologically long “bridges”.

Returns:

plotter – The plotter object (useful for adding annotations before calling show()). None if PyVista is not installed.

Return type:

pyvista.Plotter

Plotting helpers for population-level trace statistics.

uchrom.pl.trace_stats.plot_contact_map(matrix: ndarray, bin_ids: Sequence | None = None, title: str | None = None, cmap: str = 'magma', ax=None)[source]¶: Heatmap of a (n_bins, n_bins) contact frequency matrix (values in [0, 1]).

uchrom.pl.trace_stats.plot_distance_matrix(matrix: ndarray, bin_ids: Sequence | None = None, title: str | None = None, cmap: str = 'viridis_r', ax=None)[source]¶: Heatmap of a (n_bins, n_bins) population-mean distance matrix.

uchrom.pl.trace_stats.plot_rg_histogram(rg_series, bins: int = 30, title: str | None = None, ax=None)[source]¶: Histogram of per-trace radii of gyration.

3-D structure rendering¶

PyVista-based 3-D rendering of reconstructed chromatin structures.

Draws a ChromData (or raw coordinate arrays) as smooth tubes along the genomic chain — matching the look of the interactive uchrom.browser without requiring Qt.

Works in notebooks (inline screenshot or interactive if pythreejs / trame backends are installed) and in scripts (save to PNG, or show an OS window). PyVista is imported lazily so importing uchrom.pl keeps its zero-cost path when the user only needs matplotlib helpers.

Colour options¶

colour accepts:

A matplotlib-style colour name or (r, g, b) tuple → whole chain painted uniformly.
'bin' → gradient along bin index using cmap.
'chrom' → one colour per chromosome (requires spots to carry chrom — automatically true for a ChromData).
'trace' → one colour per trace (distinct alleles).
An (N,) numpy array of scalar values (e.g. epigenetic signal) → mapped through cmap.

uchrom.pl.structure_3d.plot_structure_3d(cd_or_coords: Any, chrom: str | None = None, trace_id: int | str | None = None, colour: str | Sequence | ndarray = 'bin', cmap: str = 'viridis', tube_radius: float | None = None, spline_smoothing: bool = True, background: str = 'white', show_scalar_bar: bool | None = None, save_png: str | None = None, window_size: Tuple[int, int] = (900, 700), show: bool = True, plotter: Any = None, notebook: bool | None = None, jupyter_backend: str = 'static', bond_outlier_factor: float | None = None)[source]¶