Plotting Utilities

champollion.plot.plot_aggregated_transport_plan(heat_mtx, annotations, annotations_ordered, annotations_2=None, annotations_ordered_2=None, cbar_label='transport mass', save_path=None, reduction='sum', figsize=(6, 6), x_rotation=45, x_ha='right')

Plot a transport plan aggregated by cell annotations (e.g. cell types).

The transport plan is sum-aggregated block-wise, which can help visualize whether transported mass between annotated cell populations makes sense.

Parameters:

  • heat_mtx – Cell-level transport matrix with cells from modality 1 on rows and cells from modality 2 on columns.

  • annotations – Annotation labels for the rows of heat_mtx. For example, cell types.

  • annotations_ordered – Annotation values to show on the y-axis, in plotting order.

  • annotations_2 – Annotation labels for the columns of heat_mtx. If None, the row labels are reused.

  • annotations_ordered_2 – Annotation values to show on the x-axis, in plotting order. If None, the row annotation order is reused.

  • cbar_label – Label shown next to the colorbar.

  • save_path – Optional path where the figure should be saved.

  • reduction – Aggregation applied within each annotation pair. With "sum", each block is summed and divided by the smaller block size.

  • figsize – Matplotlib figure size.

  • x_rotation – Rotation angle for x-axis tick labels.

  • x_ha – Horizontal alignment for x-axis tick labels.

Returns:

  • aggregated – Annotation-by-annotation aggregated transport matrix.

  • fig – Matplotlib figure.

  • ax – Matplotlib axes.

champollion.plot.plot_aggregated_cost_matrix(heat_mtx, annotations, annotations_ordered, annotations_2=None, annotations_ordered_2=None, cbar_label='cost', save_path=None, reduction='median', figsize=(6, 6), x_rotation=45, x_ha='right')

Plot a cost matrix aggregated by cell annotations (e.g. cell types).

The cost matrix is median-aggregated block-wise, which can help visualize whether relative inferred costs between annotated cell populations make sense.

Parameters:

  • heat_mtx – Cell-level cost matrix with cells from modality 1 on rows and cells from modality 2 on columns.

  • annotations – Annotation labels for the rows of heat_mtx. For example, cell types.

  • annotations_ordered – Annotation values to show on the y-axis, in plotting order.

  • annotations_2 – Annotation labels for the columns of heat_mtx. If None, the row labels are reused.

  • annotations_ordered_2 – Annotation values to show on the x-axis, in plotting order. If None, the row annotation order is reused.

  • cbar_label – Label shown next to the colorbar.

  • save_path – Optional path where the figure should be saved.

  • reduction – Aggregation applied within each annotation pair. With "median", each block is summarized by its median value.

  • figsize – Matplotlib figure size.

  • x_rotation – Rotation angle for x-axis tick labels.

  • x_ha – Horizontal alignment for x-axis tick labels.

Returns:

  • aggregated – Annotation-by-annotation aggregated cost matrix.

  • fig – Matplotlib figure.

  • ax – Matplotlib axes.

champollion.plot.plot_ordered_transport_plan(heat_mtx, annotations, annotations_ordered, annotations_2=None, annotations_ordered_2=None, cmap='magma', figsize=(7, 7), tick_fontsize=10, linecolor='white', linewidth=1.0, title=None, vmin=1e-08, vmax=None, xlabel='ATAC cells', ylabel='RNA cells')

Plot a transport plan after reordering cells by annotations.

Cells are reordered so that the same annotation values appear in contiguous blocks on each axis, which can help visualize whether transported mass concentrates between biologically matching annotated populations.

Parameters:

  • heat_mtx – Cell-level transport matrix with cells from modality 1 on rows and cells from modality 2 on columns.

  • annotations – Annotation labels for the rows of heat_mtx. For example, cell annotations such as cell types.

  • annotations_ordered – Annotation values used to reorder the rows and display tick labels.

  • annotations_2 – Annotation labels for the columns of heat_mtx. If None, the row annotations are reused.

  • annotations_ordered_2 – Annotation values used to reorder the columns and display tick labels. If None, the row annotation order is reused.

  • cmap – Matplotlib colormap used to display the reordered matrix.

  • figsize – Matplotlib figure size.

  • tick_fontsize – Font size used for annotation tick labels.

  • linecolor – Color used for boundaries between annotation blocks.

  • linewidth – Line width used for boundaries between annotation blocks.

  • title – Plot title. If None, a default title is used.

  • vmin – Positive lower bound used for logarithmic color scaling.

  • vmax – Optional upper bound used for logarithmic color scaling. If None, the maximum finite matrix entry is used.

  • xlabel – Label for the x-axis.

  • ylabel – Label for the y-axis.

Returns:

  • ordered_mtx – Dense transport matrix after annotation-based row and column reordering.

  • row_order – Integer indices used to reorder the rows of heat_mtx.

  • col_order – Integer indices used to reorder the columns of heat_mtx.

  • fig – Matplotlib figure.

  • ax – Matplotlib axes.

champollion.plot.top_interactions_bar(interactions, title=None, colors=None)

Plot a horizontal bar chart of top feature interaction scores.

Parameters:

  • interactions – DataFrame returned by champollion.Champollion.top_interactions(). Must contain "target_feature" and "weight" columns.

  • title – Plot title. If None, a generic title is used.

  • colors – Matplotlib-compatible color or sequence of colors. If None, a red sequential palette is used.

Returns:

  • fig – Matplotlib figure.

  • ax – Matplotlib axes.

champollion.plot.get_plot_top_interactions(model, feature, modality, k=10, direction='both', title=None, colors=None)

Get and plot top inferred interactions for one feature directly.

Parameters:

  • model – Fitted champollion.Champollion model used to retrieve the fit interaction matrix.

  • feature – Feature name passed to champollion.Champollion.top_interactions().

  • modality – Modality containing feature.

  • k – Maximum number of non-zero interactions to request from the model.

  • direction – "positive", "negative", or "both". Passed through to champollion.Champollion.top_interactions().

  • title – Plot title. If None, a title is generated from feature and direction.

  • colors – Matplotlib-compatible color or sequence of colors. If None, a red sequential palette is used.

Returns:

  • fig – Matplotlib figure.

  • ax – Matplotlib axes.