mutopia.plot.track_plot

Genome track plotting utilities for visualizing genomic data.

This module provides functions for creating genome browser-style visualizations with multiple data tracks including line plots, heatmaps, and genomic annotations.

To plot a genome view from a G-Tensor object, first define a view, and a configuration. A configuration is a Python function which describes the layout of the plot, but does not reference any specific data. For example:

import mutopia.plot.track_plot as tr

view = tr.make_view(dataset, region="chr1:100000-200000", title="Example Region")

config = lambda view: (
    tr.scale_bar(length=1e7, height=0.1, scale="mb"),
    tr.ideogram(cytobands_file="path/to/cytobands.txt"),
    tr.line_plot(
        tr.select("Features/H3K9me3"),
        label="H3K9me3",
    )
)

ax = tr.plot_view(config, view)

You can create multi-column layouts and overlayed plots using tr.columns(...) and tr.stack_plots(...), respectively:

import mutopia.plot.track_plot as tr

view = tr.make_view(dataset, region="chr1:100000-200000", title="Example Region")

config = lambda view: (
    tr.columns(
        ...,  # Ellipsis to leave a blank column
        tr.line_plot(tr.select("Regions/exposures"), label="Exposure"),
    ),
    tr.columns(
        tr.stack_plots(
            tr.line_plot(tr.select("Regions/length"), label="Length"),
            tr.fill_plot(tr.select("Regions/exposures"), label="Exposure"),
            label="Overlayed Tracks",
        ),
        ...,
    ),
)

ax = tr.plot_view(config, view)

This way, the configuration can be reused for different datasets or regions of the genome.

track_plot API

mutopia.plot.track_plot.track_plot.bar_plot(accessor, label=None, height=1, yticks=False, name=None, ax_fn=<function <lambda>>, color='#acacacff', **kwargs)

Create a bar plot track for discrete genomic data.

Parameters:

• accessor (callable) – Function to extract data from dataset

• label (str, optional) – Track label

• height (float, default 1) – Track height in figure units

• yticks (bool, default False) – Whether to show y-axis ticks

• name (str, optional) – Track name

• ax_fn (callable) – Function for additional axis customization

• color (str or array-like, default "#acacacff") – Bar color(s)

• **kwargs – Additional arguments passed to plt.bar

Returns:

Bar plot function.

Return type:

callable

Examples

>>> import mutopia.plot.track_plot as tr
>>> cfg = lambda v: tr.bar_plot(tr.select("Regions/length"), label="Length")
>>> fig = tr.plot_view(cfg, tr.make_view(ds, region="chr1:1-1_000_000"))

mutopia.plot.track_plot.track_plot.categorical_plot(accessor, order=None, label=None, height=1, palette='tab10', edgecolor=None, name=None, ax_fn=<function <lambda>>, **kwargs)

Create a categorical data track with colored rectangles.

Parameters:

• accessor (callable) – Function to extract categorical data from dataset

• order (list, optional) – Order of categories for display

• label (str, optional) – Track label

• height (float, default 1) – Track height in figure units

• palette (str or list, default "tab10") – Color palette name or list of colors

• edgecolor (str, optional) – Edge color for rectangles

• name (str, optional) – Track name

• ax_fn (callable) – Function for additional axis customization

• **kwargs – Additional arguments passed to plt.Rectangle

Returns:

Categorical plot function.

Return type:

callable

Examples

>>> import mutopia.plot.track_plot as tr
>>> cfg = lambda v: tr.categorical_plot(tr.select("Regions/chrom"))
>>> fig = tr.plot_view(cfg, tr.make_view(ds, region="chr1:1-1_000_000"))

mutopia.plot.track_plot.track_plot.center_at_zero(ax)

Center the y-axis of the plot at zero.

Parameters:

ax (matplotlib.axes.Axes) – The axes to modify.

Return type:

matplotlib.axes.Axes

mutopia.plot.track_plot.track_plot.columns(*plotting_fns, height=1, name=None)

Create a multi-column track container.

Use this to lay out multiple plotting tracks side-by-side within a single row. Pass plotting callables for each column. Use ... (Ellipsis) to leave a blank column in the layout.

Parameters:

• *plotting_fns (callable | Ellipsis) – Plotting callables to place in each column (e.g., line_plot(...), heatmap_plot(...)). Use ... to skip a column.

• height (float, default 1) – Track row height in figure units.

• name (str, optional) – Optional track name for referencing.

Returns:

A plotting callable that receives an array of Axes for the row and draws each column.

Return type:

callable

Examples

>>> import mutopia.plot.track_plot as tr
>>> view = tr.make_view(ds, region="chr1:1_000_000-1_100_000")
>>> cfg = lambda v: tr.columns(
...     tr.line_plot(tr.select("Regions/length"), label="Length"),
...     ...,  # leave middle column blank
...     tr.bar_plot(tr.select("Regions/exposures"), label="Exposure"),
... )
>>> fig = tr.plot_view(cfg, view, width_ratios=[1, 0.6, 1.2])

mutopia.plot.track_plot.track_plot.custom_plot(fn, height=1, name=None)

Create a custom plotting track from a user-defined function.

Parameters:

• fn (callable) – Custom plotting function that takes an axes object

• height (float, default 1) – Track height in figure units

• name (str, optional) – Track name

Returns:

Custom plot function.

Return type:

callable

mutopia.plot.track_plot.track_plot.fill_plot(accessor, label=None, height=1, yticks=False, name=None, color='#acacacff', ax_fn=<function <lambda>>, **kwargs)

Create a filled area plot track.

Parameters:

• accessor (callable) – Function to extract data from dataset

• label (str, optional) – Track label

• height (float, default 1) – Track height in figure units

• yticks (bool, default False) – Whether to show y-axis ticks

• name (str, optional) – Track name

• color (str, default "#acacacff") – Fill color

• ax_fn (callable) – Function for additional axis customization

• **kwargs – Additional arguments passed to plt.fill_between

Returns:

Fill plot function.

Return type:

callable

Examples

>>> import mutopia.plot.track_plot as tr
>>> cfg = lambda v: tr.fill_plot(tr.select("Regions/length"), label="Length")
>>> fig = tr.plot_view(cfg, tr.make_view(ds, region="chr1:1-1_000_000"))

mutopia.plot.track_plot.track_plot.heatmap_plot(accessor, palette=<matplotlib.colors.LinearSegmentedColormap object>, label=None, yticks=True, height=1, row_cluster=False, cluster_kw={}, name=None, cbar=True, cbar_kw={}, ax_fn=<function <lambda>>, **kwargs)

Create a heatmap track for matrix data.

Parameters:

• accessor (callable) – Function to extract 2D data from dataset

• palette (str or colormap, default diverging_palette) – Color palette for heatmap

• label (str, optional) – Track label

• yticks (bool, default True) – Whether to show y-axis tick labels

• height (float, default 1) – Track height in figure units

• row_cluster (bool, default False) – Whether to cluster rows hierarchically

• cluster_kw (dict, default {}) – Keyword arguments for clustering

• name (str, optional) – Track name

• cbar (bool, default True) – Whether to show colorbar

• cbar_kw (dict, default {}) – Keyword arguments for colorbar

• ax_fn (callable) – Function for additional axis customization

• **kwargs – Additional arguments passed to plt.pcolormesh

Returns:

Heatmap plotting function.

Return type:

callable

Examples

>>> import mutopia.plot.track_plot as tr
>>> cfg = lambda v: tr.heatmap_plot(tr.select("Some/Matrix"), label="Matrix")
>>> fig = tr.plot_view(cfg, tr.make_view(ds, region="chr1:1-1_000_000"))

mutopia.plot.track_plot.track_plot.ideogram(cytobands_file, height=0.15, name=None, **kwargs)

Create an ideogram track showing chromosome bands.

Parameters:

• cytobands (pandas.DataFrame) – DataFrame with columns ‘chrom’, ‘start’, ‘end’, ‘band’, ‘stain’

• height (float, default 0.15) – Track height in figure units

• name (str, optional) – Track name

• **kwargs – Additional arguments passed to plt.Rectangle

Returns:

Ideogram plotting function.

Return type:

callable

Examples

>>> import mutopia.plot.track_plot as tr
>>> cfg = lambda v: tr.ideogram("/path/to/cytoBand.txt.gz")
>>> fig = tr.plot_view(cfg, tr.make_view(ds, region="chr1:1-5_000_000"))

mutopia.plot.track_plot.track_plot.line_plot(accessor, label=None, height=1, yticks=False, fill=False, name=None, color='#acacacff', ax_fn=<function <lambda>>, **kwargs)

Create a line plot track for continuous genomic data.

Parameters:

• accessor (callable) – Function to extract data from dataset

• label (str, optional) – Track label

• height (float, default 1) – Track height in figure units

• yticks (bool, default False) – Whether to show y-axis ticks

• fill (bool, default False) – Whether to fill area under the line

• name (str, optional) – Track name for referencing

• color (str, default "#acacacff") – Line color

• ax_fn (callable) – Function for additional axis customization

• **kwargs – Additional arguments passed to plt.plot

Returns:

Line plot function.

Return type:

callable

Examples

>>> import mutopia.plot.track_plot as tr
>>> cfg = lambda v: tr.line_plot(tr.select("Regions/length"), label="Length")
>>> fig = tr.plot_view(cfg, tr.make_view(ds, region="chr1:1-1_000_000"))

mutopia.plot.track_plot.track_plot.make_view(dataset, region=None, title=None)

Create a GenomeView for a specific genomic region.

Parameters:

• dataset (GTensorDataset) – Input genomic dataset (or interface) containing Regions coordinates.

• region (str, optional) – Region spec like “chr1:100000-200000”. If None and dataset has a single chromosome, the full range for that chromosome is used.

• title (str, optional) – Optional figure title used by plot_view.

Returns:

Configured genome view object.

Return type:

GenomeView

Examples

>>> import mutopia.plot.track_plot as tr
>>> view = tr.make_view(ds, region="chr1:1_000_000-1_200_000", title="chr1 slice")

mutopia.plot.track_plot.track_plot.plot_view(configuration, view, *args, width=7, gridpsec_kw={'hspace': 0.1, 'wspace': 0.1}, width_ratios=None, **kwargs)

Render a genome view using a configuration of track functions.

Parameters:

• configuration (callable) – A function that takes the GenomeView and returns one or more track callables (e.g., line_plot(…), heatmap_plot(…)).

• view (GenomeView) – The genome view produced by make_view.

• width (float, default 7) – Figure width in inches.

• gridpsec_kw (dict, optional) – GridSpec kwargs for inter-row/column spacing.

• width_ratios (sequence of float, optional) – Relative column widths for multi-column layouts.

Returns:

The rendered figure.

Return type:

matplotlib.figure.Figure

Examples

>>> import mutopia.plot.track_plot as tr
>>> view = tr.make_view(ds, region="chr1:1_000_000-1_100_000")
>>> cfg = lambda v: tr.line_plot(tr.select("Regions/length"), label="Length")
>>> fig = tr.plot_view(cfg, view)

mutopia.plot.track_plot.track_plot.scale_bar(length=10000, height=0.1, name=None, label=None, scale='kb')

Create a scale bar track showing genomic distance.

Parameters:

• length (int, default 10000) – Length of scale bar in base pairs

• height (float, default 0.1) – Track height in figure units

• name (str, optional) – Track name

• label (str, optional) – Track label

Returns:

Scale bar plotting function.

Return type:

callable

Examples

>>> import mutopia.plot.track_plot as tr
>>> cfg = lambda v: tr.scale_bar(length=100_000, scale="kb")
>>> fig = tr.plot_view(cfg, tr.make_view(ds, region="chr1:1-2_000_000"))

mutopia.plot.track_plot.track_plot.scatterplot(accessor, label=None, height=1, yticks=False, c=None, name=None, ax_fn=<function <lambda>>, **kwargs)

Create a scatter plot track for point data.

Parameters:

• accessor (callable) – Function to extract data from dataset

• label (str, optional) – Track label

• height (float, default 1) – Track height in figure units

• yticks (bool, default False) – Whether to show y-axis ticks

• c (str or array-like, optional) – Point colors

• name (str, optional) – Track name

• ax_fn (callable) – Function for additional axis customization

• **kwargs – Additional arguments passed to plt.scatter

Returns:

Scatter plot function.

Return type:

callable

Examples

>>> import mutopia.plot.track_plot as tr
>>> cfg = lambda v: tr.scatterplot(tr.select("Regions/length"), label="Length")
>>> fig = tr.plot_view(cfg, tr.make_view(ds, region="chr1:1-1_000_000"))

mutopia.plot.track_plot.track_plot.spacer(height=0.1, name=None)

Insert an empty spacer track to separate other tracks.

Parameters:

• height (float, default 0.1) – Spacer height in figure units.

• name (str, optional) – Optional track name.

Returns:

Plotting callable that renders an empty row.

Return type:

callable

Examples

>>> import mutopia.plot.track_plot as tr
>>> cfg = lambda v: (tr.line_plot(tr.select("Regions/length")), tr.spacer(0.25))
>>> _ = tr.plot_view(cfg, tr.make_view(ds, region="chr1:1-2_000_000"))

mutopia.plot.track_plot.track_plot.stack_plots(*plotting_fns, height=1, label=None, legend=True, name=None, ax_fn=<function <lambda>>)

Combine multiple plotting functions into a single track.

Parameters:

• *plotting_fns – Variable number of plotting functions to stack

• height (float, default 1) – Track height in figure units

• label (str, optional) – Track label for y-axis

• legend (bool, default True) – Whether to show legend

• name (str, optional) – Track name for referencing

• ax_fn (callable) – Function to apply final customizations to axes

Returns:

Combined plotting function.

Return type:

callable

Examples

>>> import mutopia.plot.track_plot as tr
>>> cfg = lambda v: tr.stack_plots(
...     tr.line_plot(tr.select("Regions/length"), label="Length"),
...     tr.line_plot(tr.select("Regions/exposures"), label="Exposure"),
...     label="Tracks"
... )
>>> fig = tr.plot_view(cfg, tr.make_view(ds, region="chr1:1-1_000_000"))

mutopia.plot.track_plot.track_plot.static_track(track_type, file, height=1, name=None, label=None, yticks=False, ax_fn=<function <lambda>>, **properties)

Create a static track using pygenometracks.

Parameters:

• track_type (str) – Type of track (e.g., ‘GtfTrack’, ‘BedTrack’, ‘BigwigTrack’)

• file (str) – Path to the data file

• height (float, default 1) – Track height in figure units

• name (str, optional) – Track name

• label (str, optional) – Track label

• yticks (bool, default False) – Whether to show y-axis ticks

• ax_fn (callable) – Function for additional axis customization

• **properties – Additional properties passed to the track

Returns:

Static track plotting function.

Return type:

callable

Examples

>>> import mutopia.plot.track_plot as tr
>>> cfg = lambda v: tr.static_track("BigWigTrack", "/path/to/signal.bw", title="Signal")
>>> fig = tr.plot_view(cfg, tr.make_view(ds, region="chr1:1-1_000_000"))

mutopia.plot.track_plot.track_plot.text_banner(label, height=0.15, name=None)

Create a simple text banner track with a horizontal rule.

Parameters:

• label (str) – Text to display centered across the track.

• height (float, default 0.15) – Track height in figure units.

• name (str, optional) – Optional track name.

Returns:

Plotting callable for use inside a plot_view configuration.

Return type:

callable

Examples

>>> import mutopia.plot.track_plot as tr
>>> cfg = lambda v: tr.text_banner("My Region")
>>> _ = tr.plot_view(cfg, tr.make_view(ds, region="chr1:1-2_000_000"))

mutopia.plot.track_plot.track_plot.xaxis_plot(height=0.1, name=None)

Create a track showing genomic coordinates on x-axis.

Parameters:

• height (float, default 0.1) – Track height in figure units

• name (str, optional) – Track name

Returns:

X-axis plotting function.

Return type:

callable

Examples

>>> import mutopia.plot.track_plot as tr
>>> cfg = lambda v: tr.xaxis_plot()
>>> fig = tr.plot_view(cfg, tr.make_view(ds, region="chr1:1-2_000_000"))