Circos Class

pycirclizely.circos.Circos

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

Circos Visualization Class

Parameters:

Name	Type	Description	Default
`sectors`	`Mapping[str, int \| float \| tuple[float, float]]`	Sector name & size (or range) dict.	required
`start`	`float`	Plot start degree (`-360 <= start < end <= 360`).	`0`
`end`	`float`	Plot end degree (`-360 <= start < end <= 360`).	`360`
`space`	`float \| list[float]`	Space degree(s) between sectors.	`0`
`endspace`	`bool`	If True, insert space after the end sector.	`True`
`sector2clockwise`	`dict[str, bool] \| None`	Sector name & clockwise bool dict. By default, `clockwise=True`.	`None`
`show_axis_for_debug`	`bool`	Show axis for position check debugging (Dev option).	`False`

Methods:

Name	Description
`add_cytoband_tracks`	Args:
`axis`	Args:
`chord_diagram`	Plot chord diagram from matrix data.
`colorbar`	Plot colorbar using Plotly's coloraxis system.
`get_group_sectors_deg_lim`	Get degree min-max limit in target group sectors.
`get_sector`	Get sector by name
`initialize_from_bed`	Circos sectors are auto-defined by BED chromosomes.
`initialize_from_tree`	Circos sector and track are auto-defined by phylogenetic tree.
`line`	Args:
`link`	Plot curved link between two regions within or between sectors.
`link_line`	Plot link line to specified position within or between sectors
`plotfig`	Create Plotly figure with all shapes, annotations, and traces.
`radar_chart`	Args:
`rect`	Plot a rectangle spanning angular and radial ranges.
`text`	Plot text using angular positioning (0-360°).

Attributes

deg_lim `property`

deg_lim: tuple[float, float]

Circos degree limit

deg_size `property`

deg_size: float

Circos degree size

rad_lim `property`

rad_lim: tuple[float, float]

Circos radian limit

rad_size `property`

rad_size: float

Circos radian size

sectors `property`

sectors: list[Sector]

Sectors

tracks `property`

tracks: list[Track]

Tracks (from sectors)

Functions

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,
    show_hovertext: bool = False
) -> None

Parameters:

Name	Type	Description	Default
`r_lim`	`tuple[float, float]`	Radius limit region (0 - 100).	required
`cytoband_file`	`str \| Path`	Cytoband tsv file (UCSC format).	required
`track_name`	`str`	Cytoband track name. By default, `cytoband`.	`'cytoband'`
`cytoband_cmap`	`dict[str, str] \| None`	User-defined cytoband colormap. If None, use Circos style colormap.	`None`
`show_hovertext`	`bool`	If True, shows hovertext with band information.	`False`

axis

axis(**kwargs: Any) -> None

Parameters:

Name	Type	Description	Default
`**kwargs`	`Any`	Shape properties (e.g. `fillcolor="red", line=dict(color="green", width=2, dash="dash")`) https://plotly.com/python/reference/layout/shapes/	`{}`

chord_diagram `staticmethod`

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

Plot chord diagram from matrix data.

Parameters:

Name	Type	Description	Default
`matrix`	`Union[str, Path, DataFrame, Matrix]`	Matrix file or Matrix dataframe or Matrix instance.	required
`start`	`float`	Plot start degree (-360 <= start < end <= 360).	`0`
`end`	`float`	Plot end degree (-360 <= start < end <= 360).	`360`
`space`	`Union[float, list[float]]`	Space degree(s) between sectors.	`0`
`endspace`	`bool`	If True, insert space after the end sector.	`True`
`r_lim`	`tuple[float, float]`	Outer track radius limit region (0 - 100).	`(97, 100)`
`cmap`	`Union[str, dict[str, str]]`	Colormap assigned to each outer track and link.	`'Viridis'`
`link_cmap`	`Optional[list[tuple[str, str, str]]]`	Link colormap to overwrite link colors automatically set by cmap.	`None`
`ticks_interval`	`Optional[int]`	Ticks interval. If None, ticks are not plotted.	`None`
`order`	`Union[str, list[str], None]`	Sort order of matrix for plotting Chord Diagram.	`None`
`label_kws`	`Optional[dict[str, Any]]`	Keyword arguments passed to `sector.text()` method.	`None`
`ticks_kws`	`Optional[dict[str, Any]]`	Keyword arguments passed to `track.xticks_by_interval()` method.	`None`
`link_kws`	`Optional[dict[str, Any]]`	Keyword arguments passed to `circos.link()` method.	`None`
`link_kws_handler`	`Optional[Callable[[str, str], Optional[dict[str, Any]]]]`	User-defined function to handle keyword arguments for each link.	`None`

colorbar

colorbar(
    *,
    vmin: Numeric = 0,
    vmax: Numeric = 1,
    cmap: str = "RdBu_r",
    **kwargs: Any
) -> str

Plot colorbar using Plotly's coloraxis system.

Parameters:

Name	Type	Description	Default
`vmin`	`Numeric`	Colorbar min value.	`0`
`vmax`	`Numeric`	Colorbar max value.	`1`
`cmap`	`str`	Colormap name.	`'RdBu_r'`
`**kwargs`	`Any`	Colorbar properties (e.g., `orientation="v", tickfont=dict(size=12)`). See: https://plotly.com/python/reference/layout/coloraxis/.	`{}`

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.

get_sector

get_sector(name: str) -> Sector

Get sector by name

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

Circos sectors are auto-defined by BED chromosomes.

Parameters:

Name	Type	Description	Default
`bed_file`	`str \| Path`	Chromosome BED format file (zero-based coordinate).	required
`start`	`float`	Plot start degree (-360 <= start < end <= 360).	`0`
`end`	`float`	Plot end degree (-360 <= start < end <= 360).	`360`
`space`	`float \| list[float]`	Space degree(s) between sectors.	`0`
`endspace`	`bool`	If True, insert space after the end sector.	`True`
`sector2clockwise`	`dict[str, bool] \| None`	Sector name & clockwise bool dict.	`None`

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 = 14,
    leaf_label_rmargin: float = 2.0,
    reverse: bool = False,
    ladderize: bool = False,
    line_kws: dict[str, Any] | None = None,
    label_formatter: TextFormatter = None,
    align_line_kws: dict[str, Any] | None = None
) -> tuple[Circos, TreeViz]

Circos sector and track are auto-defined by phylogenetic tree.

Parameters:

Name	Type	Description	Default
`tree_data`	`str \| Path \| Tree`	Tree data (file, file URL, tree object, or tree string).	required
`start`	`float`	Plot start degree (-360 <= start < end <= 360).	`0`
`end`	`float`	Plot end degree (-360 <= start < end <= 360).	`360`
`r_lim`	`tuple[float, float]`	Tree track radius limit region (0 - 100).	`(50, 100)`
`format`	`str`	Tree format (newick, phyloxml, nexus, nexml, or cdao).	`'newick'`
`outer`	`bool`	If True, plot tree on outer side. If False, plot tree on inner side.	`True`
`align_leaf_label`	`bool`	If True, align leaf label.	`True`
`ignore_branch_length`	`bool`	If True, ignore branch length for plotting tree.	`False`
`leaf_label_size`	`float`	Leaf label size.	`14`
`leaf_label_rmargin`	`float`	Leaf label radius margin.	`2.0`
`reverse`	`bool`	If True, reverse tree.	`False`
`ladderize`	`bool`	If True, ladderize tree.	`False`
`line_kws`	`dict[str, Any] \| None`	Shape properties (e.g., dict(line=dict(color="red", width=1, dash="dash"))). https://plotly.com/python/reference/layout/shapes/	`None`
`align_line_kws`	`dict[str, Any] \| None`	Shape properties (e.g., dict(line=dict(color="black", dash="dot"), opacity=0.5)). https://plotly.com/python/reference/layout/shapes/	`None`
`label_formatter`	`TextFormatter`	User-defined label text format function to change plot label text content. For example, if you want to change underscores in the label to spaces, set `lambda t: t.replace("_", " ")`.	`None`

line

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

Parameters:

Name	Type	Description	Default
`r`	`float \| tuple[float, float]`	Line radius position (0 - 100). If r is float, (r, r) is set.	required
`deg_lim`	`tuple[float, float] \| None`	Degree limit region (-360 - 360). If None, `circos.deg_lim` is set.	`None`
`arc`	`bool`	If True, plot arc style line for polar projection. If False, simply plot linear style line.	`True`
`**kwargs`	`Any`	Line properties (e.g. `line=dict(color="red", width=2, dash="dash")`) See: https://plotly.com/python/reference/layout/shapes/	`{}`

link

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

Plot curved link between two regions within or between sectors.

Parameters:

Name	Type	Description	Default
`sector_region1`	`tuple[str, float, float]`	First region (sector_name, start, end).	required
`sector_region2`	`tuple[str, float, float]`	Second region (sector_name, start, end).	required
`r1`	`float \| None`	Radius for first region (None uses track bottom).	`None`
`r2`	`float \| None`	Radius for second region (None uses track bottom).	`None`
`height_ratio`	`float`	Controls curve height (default: 0.5).	`0.5`
`direction`	`int`	0=no arrow, 1=forward, -1=reverse, 2=bidirectional.	`0`
`arrow_length_ratio`	`float`	Arrow size relative to link length.	`0.05`
`allow_twist`	`bool`	Whether to allow twisted ribbons.	`True`
`hover_text`	`HoverText`	Custom hover text or default.	`'default'`
`**kwargs`	`Any`	Shape properties (e.g. `fillcolor="red", line=dict(color="blue", width=2)`). https://plotly.com/python/reference/layout/shapes/	`{}`

link_line

link_line(
    sector_pos1: tuple[str, float],
    sector_pos2: tuple[str, float],
    r1: float | None = None,
    r2: float | None = None,
    *,
    height_ratio: float = 0.5,
    direction: int = 0,
    arrow_height: float = 3.0,
    arrow_width: float = 0.05,
    hover_text: HoverText = "default",
    **kwargs: Any
) -> None

Plot link line to specified position within or between sectors

Parameters:

Name	Type	Description	Default
`sector_pos1`	`tuple[str, float]`	Link line sector position1 (name, position).	required
`sector_pos2`	`tuple[str, float]`	Link line sector position2 (name, position).	required
`r1`	`float \| None`	Link line radius end position for sector_pos1. If None, lowest radius position of track in target sector is set.	`None`
`r2`	`float \| None`	Link line radius end position for sector_pos2. If None, lowest radius position of track in target sector is set.	`None`
`height_ratio`	`float`	Bezier curve height ratio.	`0.5`
`direction`	`int`	Direction of arrow edge shape. 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).	`0`
`arrow_height`	`float`	Arrow height size (Radius unit).	`3.0`
`arrow_width`	`float`	Arrow width size (Degree unit).	`0.05`
`hover_text`	`HoverText`	Custom hover text or default.	`'default'`
`**kwargs`	`Any`	Shape properties (e.g. `fillcolor="red", line=dict(color="blue", width=2)`). See: https://plotly.com/python/reference/layout/shapes/	`{}`

plotfig

plotfig(
    dpi: int = 100,
    figsize: tuple[float, float] = (7, 7),
    **kwargs: Any
) -> Figure

Create Plotly figure with all shapes, annotations, and traces.

Parameters:

Name	Type	Description	Default
`dpi`	`int`	Dots per inch (used to scale figsize).	`100`
`figsize`	`tuple[float, float]`	Size of figure in inches (width, height).	`(7, 7)`
`**kwargs`	`Any`	Additional layout settings to override defaults.	`{}`

radar_chart `staticmethod`

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

Parameters:

Name	Type	Description	Default
`table`	`Union[str, Path, DataFrame, RadarTable]`	Table file or Table dataframe or RadarTable instance.	required
`r_lim`	`tuple[float, float]`	Radar chart radius limit region (0 - 100).	`(0, 100)`
`vmin`	`Numeric`	Min value.	`0`
`vmax`	`Numeric`	Max value.	`100`
`fill`	`bool`	If True, fill color of radar chart.	`True`
`marker_size`	`int`	Marker size.	`0`
`bg_color`	`Optional[str]`	Background color.	`'#eeeeee80'`
`circular`	`bool`	If True, plot with circular style.	`False`
`cmap`	`Union[str, dict[str, str]]`	Colormap assigned to each target row(index) in table.	`'Set2'`
`show_grid_label`	`bool`	If True, show grid label.	`True`
`grid_interval_ratio`	`Optional[float]`	Grid interval ratio (0.0 - 1.0).	`0.2`
`grid_line_kws`	`Optional[dict[str, Any]]`	Keyword arguments passed to `track.line()` method.	`None`
`grid_label_kws`	`Optional[dict[str, Any]]`	Keyword arguments passed to `track.text()` method.	`None`
`grid_label_formatter`	`LabelFormatter`	User-defined function to format grid label.	`None`
`label_kws_handler`	`Optional[Callable[[str], dict[str, Any]]]`	Handler function for keyword arguments passed to `track.text()` method.	`None`
`line_kws_handler`	`Optional[Callable[[str], dict[str, Any]]]`	Handler function for keyword arguments passed to `track.line()` method.	`None`
`marker_kws_handler`	`Optional[Callable[[str], dict[str, Any]]]`	Handler function for keyword arguments passed to `track.scatter()` method.	`None`

rect

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

Plot a rectangle spanning angular and radial ranges. Angle is adjusted to Plotly's coordinate system: - 0° points upward (Plotly's default) - Angles increase clockwise

Parameters:

Name	Type	Description	Default
`r_lim`	`tuple[float, float]`	Radial limits (min, max) between 0 (center) and 100 (outer edge).	`(0, 100)`
`deg_lim`	`tuple[float, float] \| None`	Angular limits in degrees (-360 to 360). If None, uses `circos.deg_lim`.	`None`
`**kwargs`	`Any`	Shape properties (e.g. `fillcolor="red", line=dict(color="blue", width=2)`) See: https://plotly.com/python/reference/layout/shapes/	`{}`

text

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

Plot text using angular positioning (0-360°). Angle is adjusted to Plotly's coordinate system: - 0° points upward (Plotly's default) - Angles increase clockwise

Parameters:

Name	Type	Description	Default
`text`	`str`	Text content.	required
`r`	`float`	Radius position (default: 0, centered).	`0`
`deg`	`float`	Degree position (0-360). 0° points upward.	`0`
`adjust_rotation`	`bool`	If True, text rotation is auto set based on `deg` and `orientation`.	`False`
`orientation`	`str`	Text orientation (`horizontal` or `vertical`).	`'horizontal'`
`**kwargs`	`Any`	Annotation properties (e.g. `font=dict(size=12, color='red')`). https://plotly.com/python/reference/layout/annotations/	`{}`

Circos Class

pycirclizely.circos.Circos

Attributes

deg_lim property

deg_size property

rad_lim property

rad_size property

sectors property

tracks property

Functions

add_cytoband_tracks

axis

chord_diagram staticmethod

colorbar

get_group_sectors_deg_lim

get_sector

initialize_from_bed staticmethod

initialize_from_tree staticmethod

line

link

link_line

plotfig

radar_chart staticmethod

rect

text

deg_lim `property`

deg_size `property`

rad_lim `property`

rad_size `property`

sectors `property`

tracks `property`

chord_diagram `staticmethod`

initialize_from_bed `staticmethod`

initialize_from_tree `staticmethod`

radar_chart `staticmethod`