Circos Class

Circos

Circos(
    sectors: Mapping[str, int | float],
    start: float = 0,
    end: float = 360,
    *,
    space: float | list[float] = 0,
    endspace: bool = True,
    sector2start_pos: Mapping[str, int | float] | None = None,
    sector2clockwise: dict[str, bool] | None = None,
    show_axis_for_debug: bool = False
)

Circos Visualization Class

PARAMETER	DESCRIPTION
sectors	Sector name & size dict TYPE: Mapping[str, int | float]
start	Plot start degree (-360 <= start < end <= 360) TYPE: float DEFAULT: 0
end	Plot end degree (-360 <= start < end <= 360) TYPE: float DEFAULT: 360
space	Space degree(s) between sector TYPE: float | list[float] DEFAULT: 0
endspace	If True, insert space after the end sector TYPE: bool DEFAULT: True
sector2start_pos	Sector name & start position dict. By default, start_pos=0. TYPE: Mapping[str, int | float] | None DEFAULT: None
sector2clockwise	Sector name & clockwise bool dict. By default, clockwise=True. TYPE: dict[str, bool] | None DEFAULT: None
show_axis_for_debug	Show axis for position check debugging (Developer option) TYPE: bool DEFAULT: False

rad_size property

rad_size: float

Circos radian size

rad_lim property

rad_lim: tuple[float, float]

Circos radian limit

deg_size property

deg_size: float

Circos degree size

deg_lim property

deg_lim: tuple[float, float]

Circos degree limit

sectors property

sectors: list[Sector]

Sectors

tracks property

tracks: list[Track]

Tracks (from sectors)

ax property

ax: PolarAxes

Plot polar axes

Can't access ax property before calling circos.plotfig() method

radar_chart staticmethod

radar_chart(
    table: str | Path | pd.DataFrame | RadarTable,
    *,
    r_lim: tuple[float, float] = (0, 100),
    vmax: float = 100,
    fill: bool = True,
    marker_size: int = 0,
    bg_color: str | None = "#eeeeee80",
    circular: bool = False,
    cmap: str | dict[str, str] = "Set2",
    show_grid_label: bool = True,
    grid_interval_ratio: float | None = 0.2,
    grid_line_kws: dict[str, Any] | None = None,
    grid_label_kws: dict[str, Any] | None = None,
    grid_label_formatter: Callable[[float], str] | None = None,
    label_kws_handler: Callable[[str], dict[str, Any]] | None = None,
    line_kws_handler: Callable[[str], dict[str, Any]] | None = None,
    marker_kws_handler: Callable[[str], dict[str, Any]] | None = None
) -> Circos

Plot radar chart

PARAMETER	DESCRIPTION
table	Table file or Table dataframe or RadarTable instance TYPE: str | Path | DataFrame | RadarTable
r_lim	Radar chart radius limit region (0 - 100) TYPE: tuple[float, float] DEFAULT: (0, 100)
vmax	Max value TYPE: float DEFAULT: 100
fill	If True, fill color of radar chart. TYPE: bool DEFAULT: True
marker_size	Marker size TYPE: int DEFAULT: 0
bg_color	Background color TYPE: str | None DEFAULT: '#eeeeee80'
circular	If True, plot with circular style. TYPE: bool DEFAULT: False
cmap	Colormap assigned to each target row(index) in table. User can set matplotlib's colormap (e.g. tab10, Set2) or target_name -> color dict (e.g. dict(A="red", B="blue", C="green", ...)) TYPE: str | dict[str, str] DEFAULT: 'Set2'
show_grid_label	If True, show grid label. TYPE: bool DEFAULT: True
grid_interval_ratio	Grid interval ratio (0.0 - 1.0) TYPE: float | None DEFAULT: 0.2
grid_line_kws	Keyword arguments passed to track.line() method (e.g. dict(color="black", ls="dotted", lw=1.0, ...)) TYPE: dict[str, Any] | None DEFAULT: None
grid_label_kws	Keyword arguments passed to track.text() method (e.g. dict(size=12, color="red", ...)) TYPE: dict[str, Any] | None DEFAULT: None
grid_label_formatter	User-defined function to format grid label (e.g. lambda v: f"{v:.1f}%"). TYPE: Callable[[float], str] | None DEFAULT: None
label_kws_handler	Handler function for keyword arguments passed to track.text() method. Handler function takes each column name of table as an argument. TYPE: Callable[[str], dict[str, Any]] | None DEFAULT: None
line_kws_handler	Handler function for keyword arguments passed to track.line() method. Handler function takes each row(index) name of table as an argument. TYPE: Callable[[str], dict[str, Any]] | None DEFAULT: None
marker_kws_handler	Handler function for keyword arguments passed to track.scatter() method. Handler function takes each row(index) name of table as an argument. TYPE: Callable[[str], dict[str, Any]] | None DEFAULT: None

RETURNS	DESCRIPTION
circos	Circos instance initialized for radar chart TYPE: Circos

initialize_from_matrix staticmethod

initialize_from_matrix(
    matrix: str | Path | pd.DataFrame | Matrix,
    *,
    start: float = 0,
    end: float = 360,
    space: float | list[float] = 0,
    endspace: bool = True,
    r_lim: tuple[float, float] = (97, 100),
    cmap: str | dict[str, str] = "viridis",
    link_cmap: list[tuple[str, str, str]] | None = None,
    ticks_interval: int | None = None,
    order: str | list[str] | None = None,
    label_kws: dict[str, Any] | None = None,
    ticks_kws: dict[str, Any] | None = None,
    link_kws: dict[str, Any] | None = None,
    link_kws_handler: Callable[[str, str], dict[str, Any] | None] | None = None
) -> Circos

Initialize Circos instance from Matrix

Circos tracks and links are auto-defined by Matrix (For plotting Chord Diagram)

PARAMETER	DESCRIPTION
matrix	Matrix file or Matrix dataframe or Matrix instance TYPE: str | Path | DataFrame | Matrix
start	Plot start degree (-360 <= start < end <= 360) TYPE: float DEFAULT: 0
end	Plot end degree (-360 <= start < end <= 360) TYPE: float DEFAULT: 360
space	Space degree(s) between sector TYPE: float | list[float] DEFAULT: 0
endspace	If True, insert space after the end sector TYPE: bool DEFAULT: True
r_lim	Outer track radius limit region (0 - 100) TYPE: tuple[float, float] DEFAULT: (97, 100)
cmap	Colormap assigned to each outer track and link. User can set matplotlib's colormap (e.g. viridis, jet, tab10) or label_name -> color dict (e.g. dict(A="red", B="blue", C="green", ...)) TYPE: str | dict[str, str] DEFAULT: 'viridis'
link_cmap	Link colormap to overwrite link colors automatically set by cmap. User can set list of from_label, to_label, color tuple (e.g. [("A", "B", "red"), ("A", "C", "#ffff00), ...]) TYPE: list[tuple[str, str, str]] | None DEFAULT: None
ticks_interval	Ticks interval. If None, ticks are not plotted. TYPE: int | None DEFAULT: None
order	Sort order of matrix for plotting Chord Diagram. If None, no sorting. If asc|desc, sort in ascending(or descending) order by node size. If node name list is set, sort in user specified node order. TYPE: str | list[str] | None DEFAULT: None
label_kws	Keyword arguments passed to sector.text() method (e.g. dict(r=110, orientation="vertical", size=15, ...)) TYPE: dict[str, Any] | None DEFAULT: None
ticks_kws	Keyword arguments passed to track.xticks_by_interval() method (e.g. dict(label_size=10, label_orientation="vertical", ...)) TYPE: dict[str, Any] | None DEFAULT: None
link_kws	Keyword arguments passed to circos.link() method (e.g. dict(direction=1, ec="black", lw=0.5, alpha=0.8, ...)) TYPE: dict[str, Any] | None DEFAULT: None
link_kws_handler	User-defined function to handle keyword arguments for each link. This option allows user to set or override properties such as fc, alpha, zorder, etc... on each link. Handler function arguments [str, str] means [from_label, to_label]. TYPE: Callable[[str, str], dict[str, Any] | None] | None DEFAULT: None

RETURNS	DESCRIPTION
circos	Circos instance initialized from Matrix TYPE: Circos

initialize_from_tree staticmethod

initialize_from_tree(
    tree_data: str | Path | Tree,
    *,
    start: float = 0,
    end: float = 360,
    r_lim: tuple[float, float] = (50, 100),
    format: str = "newick",
    outer: bool = True,
    align_leaf_label: bool = True,
    ignore_branch_length: bool = False,
    leaf_label_size: float = 12,
    leaf_label_rmargin: float = 2.0,
    reverse: bool = False,
    ladderize: bool = False,
    line_kws: dict[str, Any] | None = None,
    label_formatter: Callable[[str], str] | None = None,
    align_line_kws: dict[str, Any] | None = None
) -> tuple[Circos, TreeViz]

Initialize Circos instance from phylogenetic tree

Circos sector and track are auto-defined by phylogenetic tree

PARAMETER	DESCRIPTION
tree_data	Tree data (File|File URL|Tree Object|Tree String) TYPE: str | Path | Tree
start	Plot start degree (-360 <= start < end <= 360) TYPE: float DEFAULT: 0
end	Plot end degree (-360 <= start < end <= 360) TYPE: float DEFAULT: 360
r_lim	Tree track radius limit region (0 - 100) TYPE: tuple[float, float] DEFAULT: (50, 100)
format	Tree format (newick|phyloxml|nexus|nexml|cdao) TYPE: str DEFAULT: 'newick'
outer	If True, plot tree on outer side. If False, plot tree on inner side. TYPE: bool DEFAULT: True
align_leaf_label	If True, align leaf label. TYPE: bool DEFAULT: True
ignore_branch_length	If True, ignore branch length for plotting tree. TYPE: bool DEFAULT: False
leaf_label_size	Leaf label size TYPE: float DEFAULT: 12
leaf_label_rmargin	Leaf label radius margin TYPE: float DEFAULT: 2.0
reverse	If True, reverse tree TYPE: bool DEFAULT: False
ladderize	If True, ladderize tree TYPE: bool DEFAULT: False
line_kws	Patch properties (e.g. dict(color="red", lw=1, ls="dashed", ...)) https://matplotlib.org/stable/api/_as_gen/matplotlib.patches.Patch.html TYPE: dict[str, Any] | None DEFAULT: None
align_line_kws	Patch properties (e.g. dict(lw=1, ls="dotted", alpha=1.0, ...)) https://matplotlib.org/stable/api/_as_gen/matplotlib.patches.Patch.html TYPE: dict[str, Any] | None DEFAULT: None
label_formatter	User-defined label text format function to change plot label text content. For example, if you want to change underscore of the label to space, set lambda t: t.replace("_", " "). TYPE: Callable[[str], str] | None DEFAULT: None

RETURNS	DESCRIPTION
circos, tv : tuple[Circos, TreeViz]	Circos & TreeViz instances initialized from tree

initialize_from_bed staticmethod

initialize_from_bed(
    bed_file: str | Path,
    start: float = 0,
    end: float = 360,
    *,
    space: float | list[float] = 0,
    endspace: bool = True,
    sector2clockwise: dict[str, bool] | None = None
) -> Circos

Initialize Circos instance from BED file

Circos sectors are auto-defined by BED chromosomes

PARAMETER	DESCRIPTION
bed_file	Chromosome BED format file (zero-based coordinate) TYPE: str | Path
start	Plot start degree (-360 <= start < end <= 360) TYPE: float DEFAULT: 0
end	Plot end degree (-360 <= start < end <= 360) TYPE: float DEFAULT: 360
space	Space degree(s) between sector TYPE: float | list[float] DEFAULT: 0
endspace	If True, insert space after the end sector TYPE: bool DEFAULT: True
sector2clockwise	Sector name & clockwise bool dict. By default, clockwise=True. TYPE: dict[str, bool] | None DEFAULT: None

RETURNS	DESCRIPTION
circos	Circos instance initialized from BED file TYPE: Circos

add_cytoband_tracks

add_cytoband_tracks(
    r_lim: tuple[float, float],
    cytoband_file: str | Path,
    *,
    track_name: str = "cytoband",
    cytoband_cmap: dict[str, str] | None = None
) -> None

Add track & plot chromosome cytoband on each sector

PARAMETER	DESCRIPTION
r_lim	Radius limit region (0 - 100) TYPE: tuple[float, float]
cytoband_file	Cytoband tsv file (UCSC format) TYPE: str | Path
track_name	Cytoband track name. By default, cytoband. TYPE: str DEFAULT: 'cytoband'
cytoband_cmap	User-defined cytoband colormap. If None, use Circos style colormap. (e.g. {"gpos100": "#000000", "gneg": "#FFFFFF", ...}) TYPE: dict[str, str] | None DEFAULT: None

get_sector

get_sector(name: str) -> Sector

Get sector by name

PARAMETER	DESCRIPTION
name	Sector name TYPE: str

RETURNS	DESCRIPTION
sector	Sector TYPE: Sector

get_group_sectors_deg_lim

get_group_sectors_deg_lim(group_sector_names: list[str]) -> tuple[float, float]

Get degree min-max limit in target group sectors

PARAMETER	DESCRIPTION
group_sector_names	Group sector names TYPE: list[str]

RETURNS	DESCRIPTION
group_sectors_deg_lim	Degree limit in group sectors TYPE: tuple[float, float]

axis

axis(**kwargs) -> None

Plot axis

By default, simple black axis params(fc="none", ec="black", lw=0.5) are set.

PARAMETER	DESCRIPTION
**kwargs	Patch properties (e.g. fc="red", ec="blue", lw=0.5, ...) https://matplotlib.org/stable/api/_as_gen/matplotlib.patches.Patch.html TYPE: dict DEFAULT: {}

text

text(
    text: str,
    *,
    r: float = 0,
    deg: float = 0,
    adjust_rotation: bool = False,
    orientation: str = "horizontal",
    **kwargs
) -> None

Plot text

PARAMETER	DESCRIPTION
text	Text content TYPE: str
r	Radius position TYPE: float DEFAULT: 0
deg	Degree position (0 - 360) TYPE: float DEFAULT: 0
adjust_rotation	If True, text rotation is auto set based on deg param. TYPE: bool DEFAULT: False
orientation	Text orientation (horizontal or vertical) If adjust_rotation=True, orientation is used for rotation calculation. TYPE: str DEFAULT: 'horizontal'
**kwargs	Text properties (e.g. size=12, color="red", rotation=90, ...) https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.text.html TYPE: dict DEFAULT: {}

line

line(
    *,
    r: float | tuple[float, float],
    deg_lim: tuple[float, float] | None = None,
    arc: bool = True,
    **kwargs
) -> None

Plot line

PARAMETER	DESCRIPTION
r	Line radius position (0 - 100). If r is float, (r, r) is set. TYPE: float | tuple[float, float]
deg_lim	Degree limit region (-360 - 360). If None, circos.deg_lim is set. TYPE: tuple[float, float] | None DEFAULT: None
arc	If True, plot arc style line for polar projection. If False, simply plot linear style line. TYPE: bool DEFAULT: True
**kwargs	Patch properties (e.g. color="red", lw=3, ...) https://matplotlib.org/stable/api/_as_gen/matplotlib.patches.Patch.html TYPE: dict DEFAULT: {}

rect

rect(
    r_lim: tuple[float, float] = (0, 100),
    deg_lim: tuple[float, float] | None = None,
    **kwargs
) -> None

Plot rectangle

PARAMETER	DESCRIPTION
r_lim	Radius limit region (0 - 100) TYPE: tuple[float, float] DEFAULT: (0, 100)
deg_lim	Degree limit region (-360 - 360). If None, circos.deg_lim is set. TYPE: tuple[float, float] DEFAULT: None
**kwargs	Patch properties (e.g. fc="red", ec="black", lw=1, hatch="//", ...) https://matplotlib.org/stable/api/_as_gen/matplotlib.patches.Patch.html TYPE: dict DEFAULT: {}

link

link(
    sector_region1: tuple[str, float, float],
    sector_region2: tuple[str, float, float],
    r1: float | None = None,
    r2: float | None = None,
    *,
    color: str = "grey",
    alpha: float = 0.5,
    height_ratio: float = 0.5,
    direction: int = 0,
    arrow_length_ratio: float = 0.05,
    allow_twist: bool = True,
    **kwargs
) -> None

Plot link to specified region within or between sectors

PARAMETER	DESCRIPTION
sector_region1	Link sector region1 (name, start, end) TYPE: tuple[str, float, float]
sector_region2	Link sector region2 (name, start, end) TYPE: tuple[str, float, float]
r1	Link radius end position for sector_region1. If None, lowest radius position of track in target sector is set. TYPE: float | None DEFAULT: None
r2	Link radius end position for sector_region2. If None, lowest radius position of track in target sector is set. TYPE: float | None DEFAULT: None
color	Link color TYPE: str DEFAULT: 'grey'
alpha	Link color alpha (transparency) value TYPE: float DEFAULT: 0.5
height_ratio	Bezier curve height ratio TYPE: float DEFAULT: 0.5
direction	0: No direction edge shape (Default) 1: Forward direction arrow edge shape (region1 -> region2) -1: Reverse direction arrow edge shape (region1 <- region2) 2: Bidirectional arrow edge shape (region1 <-> region2) TYPE: int DEFAULT: 0
arrow_length_ratio	Direction arrow length ratio TYPE: float DEFAULT: 0.05
allow_twist	If False, twisted link is automatically resolved. http://circos.ca/documentation/tutorials/links/twists/images TYPE: bool DEFAULT: True
**kwargs	Patch properties (e.g. ec="red", lw=1.0, hatch="//", ...) https://matplotlib.org/stable/api/_as_gen/matplotlib.patches.Patch.html TYPE: dict DEFAULT: {}

link_line

link_line(
    sector_pos1: tuple[str, float],
    sector_pos2: tuple[str, float],
    r1: float | None = None,
    r2: float | None = None,
    *,
    color: str = "black",
    height_ratio: float = 0.5,
    direction: int = 0,
    arrow_height: float = 3.0,
    arrow_width: float = 2.0,
    **kwargs
) -> None

Plot link line to specified position within or between sectors

PARAMETER	DESCRIPTION
sector_pos1	Link line sector position1 (name, position) TYPE: tuple[str, float]
sector_pos2	Link line sector position2 (name, position) TYPE: tuple[str, float]
r1	Link line radius end position for sector_pos1. If None, lowest radius position of track in target sector is set. TYPE: float | None DEFAULT: None
r2	Link line radius end position for sector_pos2. If None, lowest radius position of track in target sector is set. TYPE: float | None DEFAULT: None
color	Link line color TYPE: str DEFAULT: 'black'
height_ratio	Bezier curve height ratio TYPE: float DEFAULT: 0.5
direction	0: No direction edge shape (Default) 1: Forward direction arrow edge shape (pos1 -> pos2) -1: Reverse direction arrow edge shape (pos1 <- pos2) 2: Bidirectional arrow edge shape (pos1 <-> pos2) TYPE: int DEFAULT: 0
arrow_height	Arrow height size (Radius unit) TYPE: float DEFAULT: 3.0
arrow_width	Arrow width size (Degree unit) TYPE: float DEFAULT: 2.0
**kwargs	Patch properties (e.g. lw=1.0, ls="dashed", ...) https://matplotlib.org/stable/api/_as_gen/matplotlib.patches.Patch.html TYPE: dict DEFAULT: {}

colorbar

colorbar(
    bounds: tuple[float, float, float, float] = (1.02, 0.3, 0.02, 0.4),
    *,
    vmin: float = 0,
    vmax: float = 1,
    cmap: str | Colormap = "bwr",
    orientation: str = "vertical",
    colorbar_kws: dict[str, Any] | None = None,
    tick_kws: dict[str, Any] | None = None
) -> None

Plot colorbar

PARAMETER	DESCRIPTION
bounds	Colorbar bounds tuple (x, y, width, height) TYPE: tuple[float, float, float, float] DEFAULT: (1.02, 0.3, 0.02, 0.4)
vmin	Colorbar min value TYPE: float DEFAULT: 0
vmax	Colorbar max value TYPE: float DEFAULT: 1
cmap	Colormap (e.g. viridis, Spectral, Reds, Greys) https://matplotlib.org/stable/tutorials/colors/colormaps.html TYPE: str | Colormap DEFAULT: 'bwr'
orientation	Colorbar orientation (vertical|horizontal) TYPE: str DEFAULT: 'vertical'
colorbar_kws	Colorbar properties (e.g. dict(label="name", format="%.1f", ...)) https://matplotlib.org/stable/api/colorbar_api.html TYPE: dict[str, Any] | None DEFAULT: None
tick_kws	Axes.tick_params properties (e.g. dict(labelsize=12, colors="red", ...)) https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.tick_params.html TYPE: dict[str, Any] | None DEFAULT: None

plotfig

plotfig(
    dpi: int = 100, *, ax: PolarAxes | None = None, figsize: tuple[float, float] = (8, 8)
) -> Figure

Plot figure

PARAMETER	DESCRIPTION
dpi	Figure DPI TYPE: int DEFAULT: 100
ax	If None, figure and axes are newly created. TYPE: PolarAxes | None DEFAULT: None
figsize	Figure size TYPE: tuple[float, float] DEFAULT: (8, 8)

RETURNS	DESCRIPTION
figure	Circos matplotlib figure TYPE: Figure

savefig

savefig(
    savefile: str | Path,
    *,
    dpi: int = 100,
    figsize: tuple[float, float] = (8, 8),
    pad_inches: float = 0.5
) -> None

Save figure to file

circos.savefig("result.png") is alias for circos.plotfig().savefig("result.png")

PARAMETER	DESCRIPTION
savefile	Save file (*.png|*.jpg|*.svg|*.pdf) TYPE: str | Path
dpi	DPI TYPE: int DEFAULT: 100
figsize	Figure size TYPE: tuple[float, float] DEFAULT: (8, 8)
pad_inches	Padding inches TYPE: float DEFAULT: 0.5