Plot function#

Pyrangeyes main function.

pyrangeyes.plot(data, *, id_col=None, regions=None, limits=None, reverse=False, pack=True, shrink=False, sort_ranges=False, label=None, fill_col=None, outline_col=False, label_color_col=False, colormap=None, legend=False, panel_title=None, tooltip=None, theme=None, to_file=None, return_plot=None, max_shown=25, warnings=None, height_col=None, depth_col=None, shape_col=None, add_aligned_plots=None, **kargs)#

Plot genomic intervals from one or more PyRanges or Track objects.

Parameters:

data ({pyranges.PyRanges, Track, or list}) – Input intervals. A list is shown as separate tracks.
id_col (str, default None) – Column used to group rows into one interval/group, such as exons into transcripts.
regions ({None, list, str, pyranges.PyRanges}, default None) – Panels to show, replacing the default one-panel-per-chromosome layout. Use (chromosome, start, end) tuples, a PyRanges object, or a column name.
limits ({None, dict, tuple, pyranges.PyRanges}, default None) – Coordinate limits for panels, e.g. {"chr1": (1000, 5000)}. Ignored when regions is provided.
reverse ({bool, "auto", str, list, dict}, default False) – Reverse coordinate axis. Use True for all panels, "auto" for all-negative-strand panels, or explicitly specify panels, e.g. ["chr1", "chr3"] or {"chr5": True}.
pack (bool, default True) – If True, stack non-overlapping intervals/groups on the same row. If False, use one row per interval/group.
shrink (bool, default False) – Compress long gaps between intervals (e.g. introns).
sort_ranges (bool, default False) – Sort intervals/groups by genomic coordinates before plotting.
label ({None, bool, str}, default None) – Display text label next to each interval or group. If True, uses the id_col value. If False, disables labels. None means labels are enabled for packed tracks and disabled for unpacked tracks. A string is formatted with row values, e.g. "tx: {transcript_id}". Use print_options() for additional options affecting label appearance and layout.
fill_col (str, default None) – Column used for interval fill colors. Defaults to id_col when possible.
outline_col ({False, str}, default False) – Column used for interval outline colors. False uses the resolved fill colors. For one fixed outline color, use outline_color="black".
label_color_col ({False, str}, default False) – Column used for label colors. False uses the fixed label_color option.
colormap (str, list, dict, or "direct", default None) –
Colors used for interval fills and, optionally, mapped outlines and labels. None falls back to the global colormap option.

If "direct", values in fill_col and outline_col are interpreted as literal colors. If a string, use the named Matplotlib/Plotly colormap or color sequence. If a list, assign colors from the list to distinct values.

If a dict, use a direct value-to-color mapping for fills, or a channel mapping with required "fill" and optional "outline" and "label" entries. "outline": "fill" reuses the fill mapping. "label": None or an omitted "label" entry uses fixed label_color unless label_color_col is provided; "label": "fill" and "label": "outline" reuse those channels. Other label colormap specs require label_color_col:
```
colormap={"+": "green", "-": "red"}
colormap={
    "fill": {"exon": "skyblue", "CDS": "orange"},
    "outline": "fill",
    "label": {"low": "black", "high": "white"},
}
```
For quantitative coloring, use type="quantitative". Values are normalized to the observed min/max by default; set range=(min, max) to choose the range:
```
colormap={"type": "quantitative", "colors": "viridis"}
colormap={"type": "quantitative", "colors": ["blue", "white", "red"], "range": (-1, 1)}
```
Quantitative colors may be a named continuous colormap, a list of gradient colors, or normalized stops such as [(0, "blue"), (0.5, "white"), (1, "red")].
legend (bool, default False) – Show a color legend.
panel_title ({None, str}, default None) – Panel title template. Available fields include {chrom}, {start}, {end}, {orientation}, and {rev_flag}. Defaults looks like: Chromosome: chr1.
tooltip (str, default None) – Tooltip displayed upon mouse hover over an interval/group. It is added to the default strand, coordinate, and ID tooltip. Use row-value fields, e.g. "{Feature}: {transcript_id}".
theme (str, default "light") – Built-in theme: "light", "dark", "pastel", or "swimming_pool".
to_file ({str, tuple}, default None) – Export path, e.g. "plot.png" or "plot.pdf". Use ("plot.png", (width, height)) to set an explicit pixel size.
return_plot ({None, "fig", "app"}, default None) – Return the backend figure/app instead of displaying or saving it.
max_shown (int, default 25) – Maximum number of intervals/groups shown before subsetting.
warnings (bool, default None) – Show pyrangeyes warnings. If None, use the global warning setting.
height_col (str, default None) – Numeric column controlling interval heights, with values from 0 to 1.
depth_col (str, default None) – Numeric column controlling draw order for overlapping intervals.
shape_col (str, default None) – Column defining interval shapes: "rectangle", "diamond", "triangle-up", "triangle-down", or "circle".
add_aligned_plots (list, default None) – Extra backend plots aligned below the genomic panels.
**kargs – Additional pyrangeyes options. See print_options() and adapter-specific options such as print_options(adapter="mRNA").

Examples

>>> import pyranges1 as pr, pyrangeyes as pe

>>> pe.set_engine('plotly')

>>> p = pr.PyRanges({
...     "Chromosome": ["1"] * 5,
...     "Strand": ["+"] * 3 + ["-"] * 2,
...     "Start": [10, 20, 30, 25, 40],
...     "End": [15, 25, 35, 30, 50],
...     "transcript_id": ["t1"] * 3 + ["t2"] * 2,
...     "Feature": ["exon", "CDS", "exon", "CDS", "exon"],
...     "feature1": ["A", "B", "C", "A", "B"],
...     "fill_hex": ["#1f77b4"] * 5,
...     "outline_hex": ["#333333"] * 5,
... })

>>> pe.plot(p, id_col="transcript_id", max_shown=25, colormap='Set3', label=False)

>>> pe.plot(p, id_col="transcript_id", fill_col='Strand', colormap={'+': 'green', '-': 'red'})

>>> pe.plot(p, id_col="transcript_id", fill_col='fill_hex', outline_col='outline_hex', colormap='direct')

>>> pe.plot(
...     p,
...     id_col="transcript_id",
...     fill_col='Strand',
...     outline_col='Feature',
...     colormap={'fill': {'+': 'green', '-': 'red'}, 'outline': {'exon': 'black', 'CDS': 'gold'}},
... )

>>> pe.plot(p, limits={'1': (1000, 50000)}, panel_title="Chrom: {chrom}")

>>> # Two windows on chromosome 1 shown as separate panels:
>>> pe.plot(p, regions=[('1', 10, 30), ('1', 30, 60)])

>>> # Or use a column to define region panels:
>>> pe.plot(p, regions='transcript_id')

>>> pe.plot([p, p], id_col="transcript_id", shrink=True, tooltip="Feature1: {feature1}")

>>> pe.plot([pe.Track(p, name="first_p"), pe.Track(p, name="second_p")], id_col="transcript_id", pack=False, to_file='my_plot.pdf')