Utility Functions and Classes

Dataset utilities

pycirclizely.utils.fetch_genbank_by_accid

fetch_genbank_by_accid(
    accid: str,
    gbk_outfile: Union[str, Path, None] = None,
    email: Union[str, None] = None,
) -> TextIO

Fetch genbank text by Accession ID.

Parameters:

Name	Type	Description	Default
accid	str	Accession ID.	required
gbk_outfile	Union[str, Path, None]	If file path is set, write fetch data to file.	None
email	Union[str, None]	Email address to notify download limitation (Required for bulk download).	None

pycirclizely.utils.load_eukaryote_example_dataset

load_eukaryote_example_dataset(
    name: str = "hg38",
    cache_dir: str | Path | None = None,
    overwrite_cache: bool = False,
) -> tuple[Path, Path, list[ChrLink]]

Load pycirclize eukaryote example dataset.

Load example file from https://github.com/moshi4/pycirclize-data/ and cache file in local directory (Default: ~/.cache/pycirclize/).

List of dataset contents (download from UCSC):

1. Chromosome BED file (e.g. chr1 0 248956422)
2. Cytoband file (e.g. chr1 0 2300000 p36.33 gneg)
3. Chromosome links (e.g. chr1 1000 4321 chr3 8000 5600)

Parameters:

Name	Type	Description	Default
name	str	Dataset name (hg38|hs1|mm10|mm39).	'hg38'
cache_dir	str | Path | None	Output cache directory (Default: ~/.cache/pycirclize/).	None
overwrite_cache	bool	If True, overwrite cache dataset. Assumed to be used when cache dataset is corrupt.	False

pycirclizely.utils.load_prokaryote_example_file

load_prokaryote_example_file(
    filename: str,
    cache_dir: str | Path | None = None,
    overwrite_cache: bool = False,
) -> Path

Load pycirclize example Genbank or GFF file.

Load example file from https://github.com/moshi4/pycirclize-data/ and cache file in local directory (Default: ~/.cache/pycirclize/).

List of example Genbank or GFF filename:

• enterobacteria_phage.[gbk|gff]
• mycoplasma_alvi.[gbk|gff]
• escherichia_coli.[gbk|gff].gz

Parameters:

Name	Type	Description	Default
filename	str	Genbank or GFF filename (e.g. enterobacteria_phage.gff).	required
cache_dir	str | Path | None	Output cache directory (Default: ~/.cache/pycirclize/).	None
overwrite_cache	bool	If True, overwrite cache file. Assumed to be used when cache file is corrupt.	False

pycirclizely.utils.load_example_tree_file

load_example_tree_file(filename: str) -> Path

Load example phylogenetic tree file.

List of example tree filename:

• small_example.nwk (7 species)
• medium_example.nwk (21 species)
• large_example.nwk (190 species)
• alphabet.nwk (26 species)

Parameters:

Name	Type	Description	Default
filename	str	Target filename.	required

Color utilities

pycirclizely.utils.ColorCycler

ColorCycler(
    palette: Union[str, list[str]] = "Plotly",
    palette_type: Optional[Type] = None,
)

Color cycler that manages color selection from palettes.

The cycler can work in two modes: 1. Automatic cycling: When no index is provided, it remembers the last position in the palette and returns the next color each time (reset with reset_cycle()) 2. Indexed access: When an index is provided, it returns the color at that position (modulo the palette length) without affecting the cycle position.

For sequential palettes, colors are distributed evenly across the available range.

Parameters:

Name	Type	Description	Default
palette	Union[str, list[str]]	Name of the palette to use or list of color strings.	'Plotly'
palette_type	Optional[Type]	Either QUALITATIVE or SEQUENTIAL. Required for custom color lists, optional for built-in palettes.	None

Methods:

Name	Description
get_color	Get a color from the palette.
get_colors	Get multiple colors from the palette.
reset_cycle	Reset the automatic color cycle to the beginning of the palette.
set_palette	Change the current color palette.

Attributes

palette_name property

palette_name: str

Get the name of the current palette.

palette_type property

palette_type: Type

Get the type of the current palette.

Functions

get_color

get_color(index: Optional[int] = None) -> str

Get a color from the palette.

Parameters:

Name	Type	Description	Default
index	Optional[int]	Optional position in the palette. If None, returns the next color in the automatic cycle sequence.	None

get_colors

get_colors(count: int) -> list[str]

Get multiple colors from the palette.

Parameters:

Name	Type	Description	Default
count	int	Number of colors to return. Must be positive.	required

reset_cycle

reset_cycle() -> None

Reset the automatic color cycle to the beginning of the palette.

set_palette

set_palette(
    palette: Union[str, list[str]],
    palette_type: Optional[Type] = None,
) -> None

Change the current color palette.

Parameters:

Name	Type	Description	Default
palette	Union[str, list[str]]	Either a palette name or list of color strings.	required
palette_type	Optional[Type]	Either QUALITATIVE or SEQUENTIAL. Required for custom color lists, optional for built-in palettes.	None

pycirclizely.utils.parse_color

parse_color(color: str) -> str

Convert css, hex (including 8-digit with alpha), or named colors into an rgb/rgba string.

Parameters:

Name	Type	Description	Default
color	str	A string representing the color in CSS, hex, or named format.	required

Helper functions

pycirclizely.utils.calc_group_spaces

calc_group_spaces(
    groups: list[int],
    *,
    space_bw_group: float = 15,
    space_in_group: float = 2,
    endspace: bool = True
) -> list[float]

Calculate spaces between/within groups.

Parameters:

Name	Type	Description	Default
groups	list[int]	List of each group number (e.g., [4, 3, 3]).	required
space_bw_group	float	Space size between groups.	15
space_in_group	float	Space size within groups.	2
endspace	bool	If True, insert space after the end group.	True

pycirclizely.utils.is_pseudo_feature

is_pseudo_feature(feature: SeqFeature) -> bool

Check target feature is pseudo or not from qualifiers tag.

Parameters:

Name	Type	Description	Default
feature	SeqFeature	Target feature.	required