vampire.anno.pl.waterfall

Contents

vampire.anno.pl.waterfall#

vampire.anno.pl.waterfall(adata, feature='motif', sample_order=None, color='id', colormap='rainbow', deduplicate=False, row_annotation=None, row_annotation_colormap=None, figsize=(None, None), track_name_dx=-0.01, save=None, **kwargs)[source]#

Create a waterfall plot for motif composition across samples.

The waterfall plot visualizes motif variation across samples in a stacked or ordered layout, where each sample is represented along the y-axis.

Parameters:

  • adata (AnnData) – Annotated data object generated from pp.read_anno().

  • feature (str) – Key prefix for the feature arrays stored in adata.uns. The function looks up uns[f"{feature}_array"] and uns[f"{feature.replace('motif', 'orientation')}_array"]. Common values: "motif" (raw arrays), "aligned_motif" (alignment output from vp.anno.tl.sample_msa()).

  • sample_order (list[str] | None) – Ordered list of sample identifiers defining the x-axis order. If None, samples are ordered based on the default order in adata.obs.

  • color (str) – Column name in adata.var used to assign motif coloring.

  • colormap (dict[str, str] | list | str) –

    Color mapping for features. Default is rainbow.

    • dict: explicit mapping {feature -> color}

    • list: sequential color assignment following input order

    • str: use preset colormap: rainbow, glasbey, sequential

  • deduplicate (bool) – If True, collapse samples with identical motif arrays into a single track. The track label shows the first sample name followed by ... (n=X) where X is the number of collapsed samples. The draw order follows the position of the first occurrence in sample_order.

  • row_annotation (str | list[str] | dict[str, str] | dict[str, dict[str, str]] | None) –

    Sample-level categorical annotation displayed as colored block(s) between the track label and the main plot.

    • str — column name in adata.obs to read categories from.

    • list[str] — list of column names in adata.obs; each column becomes an independent annotation dimension.

    • dict[str, str] — explicit {sample_name -> category}.

    • dict[str, dict[str, str]] — multiple dimensions, e.g. {"haplotype": {sample: label, ...}, "batch": {...}}. Each dimension is rendered as an independent annotation column.

    • None — no annotation drawn.

  • row_annotation_colormap (dict[str, str] | str | dict[str, dict[str, str] | str] | None) –

    Color mapping for row_annotation categories.

    • Non-nested values apply to all dimensions.

    • Nested dict[str, ...] keys must match dimension names.

    • str: preset colormap name ("rainbow", "glasbey", "sequential").

    • None: auto-generate from preset.

  • figsize (tuple[int | None, int | None]) –

    Figure size as (width, height) in pixels. Default is (None, None).

    • (None, None): auto-compute both dimensions from data.

    • (w, None): fixed width, auto-compute height from sample count.

    • (None, h): fixed height, auto-compute width from motif/kmer count.

    • (w, h): use user-specified size.

    width is proportional to the maximum sequence length (max_x) and font size to prevent horizontal crowding. height is proportional to the number of samples (n_tracks) and font size to keep track labels readable and avoid vertical overlap or excessive sparsity.

  • track_name_dx (float) – Horizontal offset applied to track name position along the x-axis,expressed as a fraction of the total width. Default is -0.01.

  • save (str | bool | None) – If True or a str, save the figure. A string is appended to the default filename. Infer the filetype if ending on {‘.pdf’, ‘.png’, ‘.svg’}.

  • **kwargs – Additional keyword arguments passed to Plotly update_layout. Used to control figure-level styling (e.g. template, margin, background color, legend settings).

Returns:

fig – Plotly figure object representing the waterfall visualization.

Return type:

Figure

Examples

>>> import vampire as vp
>>> vp.anno.pl.set_default_plotstyle()
>>> adata = vp.datasets.wdr7_hprc()
>>> vp.anno.pl.waterfall(
...     adata,
...     colormap = "rainbow",
... )
Contents