Genome Utilities¶

class finaletoolkit.genome.GenomeGaps(gaps_bed=None)[source]¶

Telomere/centromere/short-arm intervals for a reference genome.

Construct from a BED4 gap file, or use the ucsc_hg19()/b37()/ hg38() classmethods for the bundled UCSC tracks.

Parameters:: gaps_bed (Union[PathLike, str, None])

classmethod ucsc_hg19()[source]¶

GenomeGaps for UCSC hg19 (chr-prefixed, GRCh37-based).

Return type:: GenomeGaps

classmethod b37()[source]¶

GenomeGaps for Broad b37 (UCSC hg19 track with chr stripped).

An ad-hoc approximation; other hg19/b37 differences are not accounted for.

Return type:: GenomeGaps

classmethod hg38()[source]¶

GenomeGaps for UCSC hg38 (chr-prefixed, == GRCh38).

Return type:: GenomeGaps

in_tcmere(contig, start, stop)[source]¶

Return whether an interval overlaps a centromere or telomere.

Returns None if the contig has no centromere annotation.

Parameters:

contig (str) – Chromosome name.
start (int) – Interval bounds.
stop (int) – Interval bounds.

Return type:

bool | None

overlaps_gap(contig, start, stop)[source]¶

Return whether an interval overlaps any gap (None if none).

Parameters:

contig (str)
start (int)
stop (int)

Return type:

bool | None

get_arm(contig, start, stop)[source]¶

Return the chromosome arm (e.g. "1p") or "NOARM".

Raises:

ValueError – If stop < start.

Parameters:

contig (str)
start (int)
stop (int)

Return type:

str

get_contig_gaps(contig)[source]¶

Return a ContigGaps for contig (None if no centromere).

Parameters:: contig (str)
Return type:: ContigGaps | None

to_bed(output_file)[source]¶

Write all gaps as a sorted BED4 (name = gap type).

output_file may be a path, a .gz path, or "-" for stdout.

Parameters:: output_file (str | PathLike)
Return type:: None

class finaletoolkit.genome.ContigGaps(contig, centromere, telomeres, has_short_arm=False)[source]¶

Centromere/telomere intervals for a single contig.

Parameters:

contig (str)
centromere (tuple[int, int])
telomeres (Iterable[tuple[int, int]])
has_short_arm (bool)

in_tcmere(start, stop)[source]¶

Return whether an interval overlaps the centromere or a telomere.

Notes

The telomere test uses all() (an interval must overlap every telomere). This matches the original implementation and is preserved deliberately: the bundled DELFI reference outputs were generated with this behavior, so changing it to any() would alter DELFI results.

Parameters:

start (int)
stop (int)

Return type:

bool

in_gap(start, stop)[source]¶

Alias of in_tcmere() (preserved for compatibility).

Parameters:

start (int)
stop (int)

Return type:

bool

get_arm(start, stop)[source]¶

Return the chromosome arm or "NOARM".

Raises:

ValueError – If stop < start.

Parameters:

start (int)
stop (int)

Return type:

str

finaletoolkit.genome.ucsc_hg19_gap_bed(output_file)[source]¶

Write a BED4 of UCSC hg19 centromeres/telomeres/short arms.

Parameters:: output_file (str | PathLike)
Return type:: None

finaletoolkit.genome.b37_gap_bed(output_file)[source]¶

Write a BED4 of Broad b37 centromeres/telomeres/short arms.

Also useful for human_g1k_v37 (1000 Genomes) alignments.

Parameters:: output_file (str | PathLike)
Return type:: None

finaletoolkit.genome.ucsc_hg38_gap_bed(output_file)[source]¶

Write a BED4 of UCSC hg38 centromeres/telomeres/short arms.

Parameters:: output_file (str | PathLike)
Return type:: None