Skip to content

Track Class

pycirclizely.track.Track 

Track(
    name: str,
    r_lim: tuple[float, float],
    r_pad_ratio: float,
    parent_sector: Sector,
)

Circos Track Class

Parameters:

Name Type Description Default
name str

Track name.

 required
r_lim tuple[float, float]

Track radius limit region.

 required
r_pad_ratio float

Track padding ratio for plot data.

 required
parent_sector Sector

Parent sector of track.

 required

Methods:

Name Description
arrow

Plot arrow using SVG path.
axis

Args:
bar

Args:
fill_between

Fill the area between two curves with SVG paths.
genomic_features

Args:
grid

Args:
heatmap

Args:
line

Args:
rect

Plot a rectangle within a track, respecting padding settings.
scatter

Args:
stacked_bar

Args:
stacked_barh

Args:
text

Plot text within a track. Uses genomic coordinates (x) mapped to radians.
tree

Args:
x_to_rad

Convert x coordinate to radian in track start-end range.
xticks

Plot xticks & labels on user-specified position.
xticks_by_interval

Plot xticks & position labels by user-specified interval.
yticks

Plot yticks & labels on user-specified position.

Attributes

annotations property 

annotations: list[Annotation]

Layout annotations

center property 

center: float

Track center position (x coordinate)

clockwise property 

clockwise: bool

Track coordinate direction

deg_lim property 

deg_lim: tuple[float, float]

Track degree limit

deg_size property 

deg_size: float

Track degree size

end property 

end: float

Track end position (x coordinate)

name property 

name: str

Track name

parent_sector property 

parent_sector: Sector

Parent sector

precision_position property 

precision_position: int

Track precision position

r_center property 

r_center: float

Track center radius

r_lim property 

r_lim: tuple[float, float]

Track radius limit

r_plot_lim property 

r_plot_lim: tuple[float, float]

Track radius limit for plot data (r_lim with padding)

r_plot_size property 

r_plot_size: float

Track radius size for plot data (r_size with padding)

r_size property 

r_size: float

Track radius size

rad_lim property 

rad_lim: tuple[float, float]

Track radian limit

rad_size property 

rad_size: float

Track radian size

shapes property 

shapes: list[Shape]

Layout shapes

size property 

size: float

Track size (x coordinate)

start property 

start: float

Track start position (x coordinate)

traces property 

traces: list[BaseTraceType]

Data traces

Functions

arrow 

arrow(
    start: float,
    end: float,
    *,
    r_lim: tuple[float, float] | None = None,
    head_length: float = 2,
    shaft_ratio: float = 0.5,
    **kwargs: Any
) -> None

Plot arrow using SVG path.

Parameters:

Name Type Description Default
start float

Start position (x coordinate).

 required
end float

End position (x coordinate).

 required
r_lim tuple[float, float] | None

Radius limit range. If None, track.r_lim is set.

 None
head_length float

Arrow head length (Degree unit).

 2
shaft_ratio float

Arrow shaft ratio (0 - 1.0).

 0.5
**kwargs Any

Patch properties.

 {}

axis 

axis(**kwargs: Any) -> None

Parameters:

Name Type Description Default
**kwargs Any

Shape properties. https://plotly.com/python/reference/layout/shapes/

 {}

bar 

bar(
    x: NumericSequence,
    height: NumericSequence,
    width: NumericComponent = 0.8,
    bottom: NumericComponent = 0,
    align: str = "center",
    *,
    vmin: Numeric = 0,
    vmax: Numeric | None = None,
    hover_text: HoverText = "default",
    **kwargs: Any
) -> None

Parameters:

Name Type Description Default
x NumericSequence

Bar x coordinates (genomic positions).

 required
height NumericSequence

Bar heights.

 required
width NumericComponent

Bar widths in genomic coordinates.

 0.8
bottom NumericComponent

Bar bottom y-value(s).

 0
align str

Bar alignment ("center" or "edge").

 'center'
vmin Numeric

Minimum value for radial scaling.

 0
vmax Numeric | None

Maximum value for radial scaling. If None, uses max(height + bottom).

 None
hover_text HoverText

Hover text for the plot.

 'default'
**kwargs Any

Properties for both shapes and hover text.

 {}

fill_between 

fill_between(
    x: NumericSequence,
    y1: NumericSequence,
    y2: NumericComponent = 0,
    *,
    vmin: Numeric = 0,
    vmax: Numeric | None = None,
    arc: bool = True,
    hover_text: HoverText = "default",
    **kwargs: Any
) -> None

Fill the area between two curves with SVG paths.

Parameters:

Name Type Description Default
x NumericSequence

Genomic positions along the track.

 required
y1 NumericSequence

Upper boundary values to plot.

 required
y2 NumericComponent

Lower boundary values or constant baseline.

 0
vmin Numeric

Minimum value for radial scaling.

 0
vmax Numeric | None

Maximum value for radial scaling. If None, uses max(y1 + y2).

 None
arc bool

If True, creates curved arc fills. If False, creates straight chord fills.

 True
hover_text HoverText

Hover text for the plot.

 'default'
**kwargs Any

Shape properties. https://plotly.com/python/reference/layout/shapes/

 {}

genomic_features 

genomic_features(
    features: SeqFeature | list[SeqFeature],
    *,
    plotstyle: str = "box",
    r_lim: tuple[float, float] | None = None,
    hover_text_formatter: (
        Callable[[SeqFeature], str] | None
    ) = None,
    **kwargs: Any
) -> None

Parameters:

Name Type Description Default
features SeqFeature | list[SeqFeature]

Biopython's SeqFeature or SeqFeature list.

 required
plotstyle str

Plot style (box or arrow).

 'box'
r_lim tuple[float, float] | None

Radius limit range. If None, track.r_plot_lim is set.

 None
hover_text_formatter Callable[[SeqFeature], str] | None

User-defined function for hover text format.

 None
**kwargs Any

Shape properties. https://plotly.com/python/reference/layout/shapes/

 {}

grid 

grid(
    y_grid_num: int | None = 6,
    x_grid_interval: float | None = None,
    **kwargs: Any
) -> None

Parameters:

Name Type Description Default
y_grid_num int | None

Y-axis grid line number. If None, y-axis grid line is not shown.

 6
x_grid_interval float | None

X-axis grid line interval. If None, x-axis grid line is not shown.

 None
**kwargs Any

Shape properties. https://plotly.com/python/reference/layout/shapes/

 {}

heatmap 

heatmap(
    data: list | ndarray,
    *,
    vmin: Numeric | None = None,
    vmax: Numeric | None = None,
    start: Numeric | None = None,
    end: Numeric | None = None,
    width: Numeric | None = None,
    cmap: str | list[tuple[float, str]] = "RdBu_r",
    show_value: bool = False,
    hover_text: HoverText = "default",
    coloraxis: str | None = None,
    rect_kws: dict[str, Any] | None = None,
    text_kws: dict[str, Any] | None = None
) -> None

Parameters:

Name Type Description Default
data list | ndarray

Numerical list, numpy 1d or 2d array.

 required
vmin Numeric | None

Min value for heatmap plot. If None, np.min(data) is set.

 None
vmax Numeric | None

Max value for heatmap plot. If None, np.max(data) is set.

 None
start Numeric | None

Start position for heatmap plot (x coordinate).

 None
end Numeric | None

End position for heatmap plot (x coordinate).

 None
width Numeric | None

Heatmap rectangle x width size.

 None
cmap str | list[tuple[float, str]]

Colormap specification.

 'RdBu_r'
show_value bool

If True, show data value on heatmap rectangle.

 False
hover_text HoverText

Hover text for the plot.

 'default'
coloraxis str | None

Color axis identifier.

 None
rect_kws dict[str, Any] | None

Shape properties. https://plotly.com/python/reference/layout/shapes/

 None
text_kws dict[str, Any] | None

Text properties. https://plotly.com/python/reference/layout/annotations/

 None

line 

line(
    x: NumericSequence,
    y: NumericSequence,
    *,
    vmin: Numeric = 0,
    vmax: Numeric | None = None,
    arc: bool = True,
    hover_text: HoverText = "default",
    **kwargs: Any
) -> None

Parameters:

Name Type Description Default
x NumericSequence

Genomic positions along the track.

 required
y NumericSequence

Data values to plot.

 required
vmin Numeric

Minimum value for radial scaling.

 0
vmax Numeric | None

Maximum value for radial scaling. If None, uses max(y).

 None
arc bool

If True, creates curved arc lines. If False, creates straight chord lines.

 True
hover_text HoverText

Hover text for the plot.

 'default'
**kwargs Any

Shape properties. https://plotly.com/python/reference/layout/shapes/

 {}

rect 

rect(
    start: float,
    end: float,
    *,
    r_lim: tuple[float, float] | None = None,
    ignore_pad: bool = False,
    **kwargs: Any
) -> None

Plot a rectangle within a track, respecting padding settings.

Parameters:

Name Type Description Default
start float

Genomic start position (x coordinate).

 required
end float

Genomic end position (x coordinate).

 required
r_lim tuple[float, float] | None

Radial limits (min, max). If None, uses track defaults.

 None
ignore_pad bool

If True, ignores track padding when auto-setting r_lim.

 False
**kwargs Any

Shape properties. https://plotly.com/python/reference/layout/shapes/

 {}

scatter 

scatter(
    x: NumericSequence,
    y: NumericSequence,
    *,
    vmin: Numeric = 0,
    vmax: Numeric | None = None,
    hover_text: HoverText = "default",
    **kwargs: Any
) -> None

Parameters:

Name Type Description Default
x NumericSequence

X (genomic) positions.

 required
y NumericSequence

Data values.

 required
vmin Numeric

Minimum value for radial scaling.

 0
vmax Numeric | None

Maximum value for radial scaling. If None, uses max(y).

 None
hover_text HoverText

Hover text for the plot.

 'default'
**kwargs Any

Scatter trace properties.

 {}

stacked_bar 

stacked_bar(
    table_data: str | Path | DataFrame | StackedBarTable,
    *,
    delimiter: str = "\t",
    width: float = 0.6,
    cmap: str | dict[str, str] = "T10",
    vmax: float | None = None,
    hover_text: HoverText = "default",
    **kwargs: Any
) -> StackedBarTable

Parameters:

Name Type Description Default
table_data str | Path | DataFrame | StackedBarTable

Table file or Table DataFrame or StackedBarTable.

 required
delimiter str

Table file delimiter.

 '\t'
width float

Bar width ratio (0.0 - 1.0).

 0.6
cmap str | dict[str, str]

Colormap assigned to each stacked bar.

 'T10'
vmax float | None

Stacked bar max value. If None, max value in each row values sum is set.

 None
hover_text HoverText

Hover text for the plot.

 'default'
**kwargs Any

Shape properties. https://plotly.com/python/reference/layout/shapes/

 {}

stacked_barh 

stacked_barh(
    table_data: str | Path | DataFrame | StackedBarTable,
    *,
    delimiter: str = "\t",
    width: float = 0.6,
    cmap: str | dict[str, str] = "T10",
    vmax: float | None = None,
    hover_text: HoverText = "default",
    **kwargs: Any
) -> StackedBarTable

Parameters:

Name Type Description Default
table_data str | Path | DataFrame | StackedBarTable

Table file or Table DataFrame or StackedBarTable.

 required
delimiter str

Table file delimiter.

 '\t'
width float

Bar width ratio (0.0 - 1.0).

 0.6
cmap str | dict[str, str]

Colormap assigned to each stacked bar.

 'T10'
vmax float | None

Stacked bar max value. If None, max row sum is used.

 None
hover_text HoverText

Hover text for the plot.

 'default'
**kwargs Any

Shape properties. https://plotly.com/python/reference/layout/shapes/

 {}

text 

text(
    text: str,
    x: float | None = None,
    r: float | None = None,
    *,
    adjust_rotation: bool = True,
    orientation: str = "horizontal",
    ignore_range_error: bool = False,
    outer: bool = True,
    axis: str | bool = False,
    **kwargs: Any
) -> None

Plot text within a track. Uses genomic coordinates (x) mapped to radians.

Parameters:

Name Type Description Default
text str

Text content.

 required
x float | None

Genomic position. If None, track center is used.

 None
r float | None

Radius position. If None, track midpoint (r_center) is used.

 None
adjust_rotation bool

If True, text rotation auto based on x and orientation.

 True
orientation str

Text orientation (horizontal or vertical).

 'horizontal'
ignore_range_error bool

If True, ignores x position outside track bounds.

 False
outer bool

If True, text aligns outward from center, in horizontal orientation.

 True
axis str | bool

Axis type (x, y, or False).

 False
**kwargs Any

Annotation properties. https://plotly.com/python/reference/layout/annotations/

 {}

tree 

tree(
    tree_data: str | Path | Tree,
    *,
    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,
    align_line_kws: dict[str, Any] | None = None,
    label_formatter: TextFormatter = None
) -> TreeViz

Parameters:

Name Type Description Default
tree_data str | Path | Tree

Tree data (File|File URL|Tree Object|Tree String).

 required
format str

Tree format (newick|phyloxml|nexus|nexml|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.

 12
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. https://plotly.com/python/reference/layout/shapes/

 None
align_line_kws dict[str, Any] | None

Shape properties. https://plotly.com/python/reference/layout/shapes/

 None
label_formatter TextFormatter

User-defined label text format function to change label text content.

 None

x_to_rad 

x_to_rad(
    x: float, ignore_range_error: bool = False
) -> float

Convert x coordinate to radian in track start-end range.

Parameters:

Name Type Description Default
x float

X coordinate.

 required
ignore_range_error bool

Ignore x coordinate range error.

 False

xticks 

xticks(
    x: NumericSequence,
    labels: list[str] | None = None,
    *,
    tick_length: float = 2,
    outer: bool = True,
    show_bottom_line: bool = False,
    label_margin: float = 1,
    label_orientation: str = "horizontal",
    line_kws: dict[str, Any] | None = None,
    text_kws: dict[str, Any] | None = None
) -> None

Plot xticks & labels on user-specified position.

Parameters:

Name Type Description Default
x NumericSequence

X coordinates.

 required
labels list[str] | None

Labels on xticks. If None, only plot ticks line.

 None
tick_length float

Tick length (Radius unit).

 2
outer bool

If True, show ticks on outer. If False, show ticks on inner.

 True
show_bottom_line bool

If True, show bottom line.

 False
label_margin float

Label margin size.

 1
label_orientation str

Label orientation (horizontal or vertical).

 'horizontal'
line_kws dict[str, Any] | None

Shape properties for ticks/baseline. https://plotly.com/python/reference/layout/shapes/

 None
text_kws dict[str, Any] | None

Annotation properties for labels. https://plotly.com/python/reference/layout/annotations/

 None

xticks_by_interval 

xticks_by_interval(
    interval: Numeric,
    *,
    tick_length: float = 2,
    outer: bool = True,
    show_bottom_line: bool = False,
    show_label: bool = True,
    show_endlabel: bool = True,
    label_margin: float = 1.7,
    label_orientation: str = "horizontal",
    label_formatter: LabelFormatter = None,
    line_kws: dict[str, Any] | None = None,
    text_kws: dict[str, Any] | None = None
) -> None

Plot xticks & position labels by user-specified interval.

Parameters:

Name Type Description Default
interval Numeric

Xticks interval in genomic coordinates.

 required
tick_length float

Tick length in radius units.

 2
outer bool

If True, show ticks on outer radius.

 True
show_bottom_line bool

If True, show baseline at bottom of ticks.

 False
show_label bool

If True, show position labels.

 True
show_endlabel bool

If False, hides label at final position to prevent overlap.

 True
label_margin float

Additional radial margin for labels.

 1.7
label_orientation str

Label orientation ('horizontal' or 'vertical').

 'horizontal'
label_formatter LabelFormatter

Function to format tick labels.

 None
line_kws dict[str, Any] | None

Shape properties for ticks/baseline. https://plotly.com/python/reference/layout/shapes/

 None
text_kws dict[str, Any] | None

Annotation properties for labels. https://plotly.com/python/reference/layout/annotations/

 None

yticks 

yticks(
    y: NumericSequence,
    labels: list[str] | None = None,
    *,
    vmin: Numeric = 0,
    vmax: Numeric | None = None,
    side: str = "right",
    tick_length: Numeric = 2,
    label_margin: Numeric = 1,
    label_orientation: str = "horizontal",
    line_kws: dict[str, Any] | None = None,
    text_kws: dict[str, Any] | None = None
) -> None

Plot yticks & labels on user-specified position.

Parameters:

Name Type Description Default
y NumericSequence

Y coordinates.

 required
labels list[str] | None

Labels on yticks. If None, only plot ticks line.

 None
vmin Numeric

Y min value.

 0
vmax Numeric | None

Y max value. If None, max(y) is set.

 None
side str

Ticks side position (right or left).

 'right'
tick_length Numeric

Tick length (Degree unit).

 2
label_margin Numeric

Label margin size.

 1
label_orientation str

Label orientation (horizontal or vertical).

 'horizontal'
line_kws dict[str, Any] | None

Shape properties for ticks/baseline. https://plotly.com/python/reference/layout/shapes/

 None
text_kws dict[str, Any] | None

Annotation properties for labels. https://plotly.com/python/reference/layout/annotations/

 None