Chromosome Visualization library in python.
Applicable across scales, from genomes down to protein domains.

Examples · Explore API

Examples

▶️ CLI

chrov plot ENSG00000187634 examples/outputs/ints_levels examples/inputs/ints.yaml

chrov plot --help

usage: chrov plot [-h] [--species SPECIES] [-e ENSEMBL_RELEASE] [--height-ratios [HEIGHT_RATIOS ...]] [--show-title] [--figsize [FIGSIZE ...]] [-c CMAP] [-l LOG_LEVEL] [--force] gene-id outd levels-path Plots the level-wise interaction heatmaps. Args: gene_id: str: Ensembl gene id, outd: str: Output directory path, levels_path: str: level-wise data paths provided through a yaml file, species: str='homo sapiens': species name, ensembl_release: int=112: Ensembl release, height_ratios: list=[3,1]: ratio of the heatmap and the chrov plot, show_title: bool=False: show title of the level, figsize: list=[2,1]: figure size, cmap: str='Reds_r': colormap, force: bool = False: Over-write, Examples: CLI: chrov plot ENSG00000187634 examples/outputs/ints_levels examples/inputs/ints.yaml Format of the level-wise data: levels.yaml (levels_path) ├── genome.pqt ├── .. └── protein.pqt where, pqt is Apache parquete format (ideal for large data). positional arguments: gene-id - outd - levels-path - options: -h, --help show this help message and exit --species SPECIES 'homo sapiens' -e ENSEMBL_RELEASE, --ensembl-release ENSEMBL_RELEASE 112 --height-ratios [HEIGHT_RATIOS ...] [3, 1] --show-title False --figsize [FIGSIZE ...] [2, 1] -c CMAP, --cmap CMAP 'Reds_r' -l LOG_LEVEL, --log-level LOG_LEVEL 'WARNING' --force False

🏷️Annotations on chromosomes
🧬Visualization of genome, set of chromosomes, a chromosome and an arm
🔥🗺️Visualization of heatmaps along chromosome arm
🔌Integration of custom plots e.g. made using seaborn
📈🍭Integration of basic plots e.g. stem/lollipop plot
↔️↔️Visualization of intervals/ranges/segments along a chromosome arm

Installation

pip install chrov ## with basic dependencies With additional dependencies as required: pip install chrov[dev] ## for local testing

How to cite?

1. Using BibTeX:
   @software{Dandage_chrov, title = {chrov: Chromosome Visualization library in python}, author = {Dandage, Rohan}, year = {2023}, url = {https://zenodo.org/doi/10.5281/zenodo.10211265}, note = {The URL is a DOI link to the permanent archive of the software.}, }

2. DOI link: , or

3. Using citation information from CITATION.CFF file.

Future directions for 🐦‍⬛

• [ ] Set subplot sizes by default: automate setting off and offy.
• [ ] Compatibility of seaborn plots with polar layout.
• [ ] Layering the interval vizualizations on the polar layout.
• [ ] Connection styles.
• [ ] Other features and improvements.

Similar projects

• https://github.com/moshi4/pyCirclize
• https://github.com/ponnhide/pyCircos

API

module chrov.viz.annot

Annotations.

---

function annot_labels

python annot_labels( ax_chrom: Axes, data: DataFrame, colx: str, chrom_y: float, col_label: str, loc: str = 'out', col_start: str = None, ax: Axes = None, coly: str = None, col_labelx: str = 'label x', color: str = 'darkgray', yoff_scales: float = None, off_labels_segments: float = 20, scale_polar: float = 1.5, fig: Figure = None, test: bool = False ) → Axes

Annot labels e.g. gene names

Args:

• ax_chrom (plt.Axes): subplot with the chromosome plot
• col_label (str): column with the labels
• loc (str, optional): locations. Defaults to 'out'.
• color (str, optional): color. Defaults to 'darkgray'.
• yoff_scales (float, optional): y offset. Defaults to None.
• off_labels_segments (float, optional): offset for the label segments. Defaults to 20.
• scale_polar (float, optional): scale for the polar plot. Defaults to 1.5.
• fig (plt.Figure, optional): figure. Defaults to None.
• test (bool, optional): test-mode. Defaults to False.

Returns:

• plt.Axes: subplot

---

function show_segments

python show_segments( ax: Axes, y: float, offy: float, kind: str = 'arrows', segments: dict = None, segments_kws: dict = {}, offytext: float = 0.2, arrow_kws: dict = {'color': 'k', 'lw': 1, 'alpha': 1, 'arrowstyle': '<->'}, test: bool = False, **kws_annotate ) → Axes

Show segments aligned to chromosome arm.

Args:

• ax (plt.Axes): subplot
• data (pd.DataFrame): input data
• size (int): size of the segments

module chrov.viz.chrom

Chromosome plots

---

function to_polar

python to_polar( a: list, range1: list = None, range2: list = None, interval: int = None ) → list

To polar coordinates

Args:

• a (list): Coordinates
• range1 (list, optional): range1. Defaults to None.
• range2 (list, optional): range2. Defaults to None.
• interval (int, optional): interval size. Defaults to None.

Raises:

• ValueError: Coordinates format

Returns:

• list: rescaled coordinates

---

function plot_arm

python plot_arm( data: DataFrame, arc: bool = False, col_start: str = 'start', col_end: str = 'end', y: float = 0, lw: float = 10, ec: str = 'k', pi_span: float = 1, pi_start: int = 0, pi_end: int = None, polar_smoothness_scale: float = 1, kws_pre_xys: dict = None, figsize: list = None, ax: Axes = None, test: bool = False, solid_capstyle='round' ) → Axes

Plot chromosome arm.

Args:

• data (pd.DataFrame): input table.
• y (float, optional): y position. Defaults to 0.
• lw (float, optional): line width. Defaults to 20.
• ec (str, optional): edge color. Defaults to 'k'.
• ax (plt.Axes, optional): subplot. Defaults to None.
• test (bool, optional): test-mode. Defaults to False.

Returns:

• plt.Axes: subplot

---

function plot_chrom

python plot_chrom( data: DataFrame, arc: bool = False, col_start: str = 'start', col_end: str = 'end', col_arm: str = 'arm', pi_span: float = 1, pi_start: int = 0, pi_end: int = None, ax: Axes = None, figsize: list = None, **kws_plot_arm ) → Axes

Plot a chromosome

Args:

• data (pd.DataFrame): cytobands
• arc (bool, optional): arc/polar mode. Defaults to False.
• col_start (str, optional): column with start positions. Defaults to 'start'.
• col_end (str, optional): column with end positions. Defaults to 'end'.
• col_arm (str, optional): column with arm names. Defaults to 'arm'.
• pi_span (float, optional): pi span. Defaults to 1.
• pi_start (int, optional): pi start. Defaults to 0.
• pi_end (int, optional): pi end. Defaults to None.
• ax (plt.Axes, optional): subplot. Defaults to None.
• figsize (list, optional): sigure size. Defaults to None.

Returns:

• plt.Axes: subplot

---

function plot_chroms

python plot_chroms( data: DataFrame, arc=True, chromosomes: list = None, col_start='start', col_end='end', col_arm='arm', span_color: str = '#dcdcdc', span_color_alpha_scale: float = 1, pi_span: float = 1, pi_start: int = 0, pi_end: int = None, show_labels: bool = True, show_vline: bool = True, label_y: str = None, test: bool = False, ax: Axes = None, figsize: list = None, out_data: bool = False, **kws_plot_arm )

Plot chromosomes joined.

Args:

• data (pd.DataFrame): cytonbands
• arc (bool, optional): arc/polar mode. Defaults to True.
• chromosomes (list, optional): chromosomes. Defaults to None.
• col_start (str, optional): column with start position. Defaults to 'start'.
• col_end (str, optional): column with end position. Defaults to 'end'.
• col_arm (str, optional): column with chromosome arm names. Defaults to 'arm'.
• span_color (str, optional): span color. Defaults to 'whitesmoke'.
• span_color_alpha_scale (float, optional): span color transparency scale. Defaults to 1.
• pi_span (float, optional): pi span. Defaults to 1.
• pi_start (int, optional): pi start angle. Defaults to 0.
• pi_end (int, optional): pi end angle. Defaults to None.
• show_labels (bool, optional): show labels. Defaults to True.
• show_vline (bool, optional): show vertical line. Defaults to True.
• label_y (str, optional): label y. Defaults to None.
• test (bool, optional): test-mode. Defaults to False.
• ax (plt.Axes, optional): subplot. Defaults to None.
• figsize (list, optional): figure size. Defaults to None.
• out_data (bool, optional): output data. Defaults to False.

---

function annot_chroms

python annot_chroms( data: DataFrame, chromosomes: list, ax_chrom: Axes = None, chrom_y: float = 0, kws_add_ax: dict = {}, test: bool = False, **kws_plot ) → Axes

Add a subplot with the chromosome.

Args:

• data (pd.DataFrame): table with cytobands
• chromosomes (list): chromosomes
• ax_chrom (plt.Axes, optional): subplot with chromosome plot. Defaults to None.
• chrom_y (float, optional): chromosome y-position. Defaults to 0.
• kws_add_ax (dict, optional): keyword parameters provided to _add_ax. Defaults to {}.
• test (bool, optional): test mode. Defaults to False.

Returns:

• plt.Axes: subplot

module chrov.viz.figure

---

function plot_with_chroms

python plot_with_chroms( data: DataFrame, cytobands: DataFrame, kind: str, colx: str, coly: str, col_label: str, va: str, col_start: str = None, xkind: str = 'loci', coffy: str = None, off: float = None, offy: float = None, chrom_y: float = 0, arc: bool = True, pi_span: float = 1, pi_start: int = 0, pi_end: int = None, fig: Figure = None, figsize: list = None, ax_data: Axes = None, kws_seaborn: dict = {}, kws_annot_chroms: dict = {}, kws_annot_labels: dict = {}, test: bool = False ) → Figure

Plot with chromosomes.

Args:

• data (pd.DataFrame): input table
• cytobands (pd.DataFrame): cytobands
• kind (str): kind of plot
• colx (str): column with x values
• coly (str): column with y values
• col_label (str): column with labels
• va (str): vertical alignment
• col_start (str, optional): column with start positions. Defaults to None.
• xkind (str, optional): kind of x values. Defaults to 'loci'.
• off (float, optional): offset scale of the chromosome plot. Defaults to None.
• offy (float, optional): offset y of the chromosome plot. Defaults to None.
• chrom_y (float, optional): chromosome y-position. Defaults to 0.
• arc (bool, optional): arc/polar plot or linear/rectangular one. Defaults to True.
• pi_span (float, optional): pi span. Defaults to 1.
• pi_start (int, optional): pi start. Defaults to 0.
• pi_end (int, optional): pi end. Defaults to None.
• fig (plt.Figure, optional): figure. Defaults to None.
• figsize (list, optional): figure size. Defaults to None.
• ax_data (plt.Axes, optional): subplot with the data plot. Defaults to None.
• kws_seaborn (dict, optional): keyword parameters to seaborn plot. Defaults to {}.
• kws_annot_chroms (dict, optional): keyword parameters to the chromosome plot. Defaults to {}.
• kws_annot_labels (dict, optional): keyword parameters to the annotations of the labels. Defaults to {}.
• test (bool, optional): test mode. Defaults to False.

Returns:

• plt.Figure: figure

module chrov.viz

module chrov.viz.plot

---

function plot_seaborn

python plot_seaborn( data: DataFrame, kind: str, colx: str, coly: str, range1_chroms: list, arc: bool = True, pi_span: float = 1, pi_start: int = 0, pi_end: int = None, figsize: list = None, ax: Axes = None, fig: Figure = None, **kws_plot ) → tuple

plotseaborn _summary

Args:

• data (pd.DataFrame): input data
• kind (str): kind of plot, seaborn function name
• coly (str): column with y values
• range1_chroms (list): input range of chromosomes
• arc (bool, optional): arc/polar or linear/rectangular plots. Defaults to True.
• pi_span (float, optional): pi span. Defaults to 1.
• pi_start (int, optional): pi start position. Defaults to 0.
• pi_end (int, optional): pi end position. Defaults to None.
• figsize (list, optional): figure size. Defaults to None.
• ax (plt.Axes, optional): subplot. Defaults to None.
• fig (plt.Figure, optional): figure. Defaults to None.

Returns:

• tuple: subplot and data

TODOs: 1. set rlabel position.

---

function heatmaps_strips

python heatmaps_strips( data: DataFrame, strips_kws: dict, fig: Figure = None, axs: list = None, kws_subplots: list = {} ) → tuple

Plot heatmap strips

Args:

• data (pd.DataFrame): input data
• strips_kws (dict): keyword arguments provided to strips
• fig (plt.Figure, optional): figure. Defaults to None.
• axs (list, optional): subplots. Defaults to None.
• kws_subplots (list, optional): keyword arguments provided to subplots. Defaults to {}.

Returns:

• tuple: figure and subplots

module chrov.viz.ranges

---

function plot_ranges

python plot_ranges( data: DataFrame, col_id: str, col_start: str, col_end: str, end: int, start: int = 0, hue: str = None, y=None, kind=None, cytobands: dict = None, cytobands_y: float = None, col_groupby: str = None, col_label: str = None, colors: dict = None, lw: int = 10, zorders: dict = None, show_segments: bool = False, xtick_interval: float = None, test: bool = False, ax: Axes = None ) → Axes

Plot ranges.

Args:

• data (pd.DataFrame): input data.
• col_id (str): column with ids.
• col_start (str): column with start co-ordinates.
• col_end (str): column with end co-ordinates.
• end (int): end position for the plot
• start (int, optional): start position for the plot. Defaults to 0.
• hue (str, optional): column with color. Defaults to None.
• y (type, optional): column with y positions. Defaults to None.
• cytobands (dict, optional): cytobands to plot the chromosomes. Defaults to None.
• cytobands_y (float, optional): cytobands y-position. Defaults to None.
• col_groupby (str, optional): column to group by. Defaults to None.
• col_label (str, optional): column with labels. Defaults to None.
• colors (dict, optional): colors. Defaults to None.
• lw (int, optional): line width. Defaults to 10.
• zorders (dict, optional): z-orders. Defaults to None.
• show_segments (bool, optional): show segments. Defaults to False.
• xtick_interval (float, optional): x tick intervals. Defaults to None.
• test (bool, optional): test-mode. Defaults to False.
• ax (plt.Axes, optional): subplot. Defaults to None.

Raises:

• ValueError: if kind is not 'split','separate' or 'joined'

Returns:

• plt.Axes: subplot