ISCN Authenticator

ISCN 2024 karyotype validation — parser, rule engine, and AST types. Pure Python, zero runtime dependencies.

v0.2.0 MIT Python 3.10 – 3.13 Zero deps

What it does

Parses karyotype strings against the 2024 edition of the International System for Human Cytogenomic Nomenclature and returns a structured AST alongside any rule violations. Built for clinical cytogenetics workflows where every chromosome string needs to round-trip through the same nomenclature rules.

Coverage spans the bulk of ISCN 2024 grammar — numerical aberrations, structural rearrangements, specialized rearrangements, marker chromosomes, uncertainty markers, inheritance suffixes, and mosaicism via cell lines.

+/-delduptinvinsi / idicder / dicrrobtrpmar?mat / pat / dnmosaicism

Quick start

from iscn_authenticator import is_valid_karyotype, validate_karyotype

is_valid_karyotype("46,XX")                              # True
is_valid_karyotype("47,XY,+21")                          # True
is_valid_karyotype("46,XX,t(9;22)(q34;q11.2)")           # True
is_valid_karyotype("47,XY,+21[8]/46,XY[12]")             # True (mosaic)
is_valid_karyotype("garbage")                            # False

result = validate_karyotype("46,XX,del(5)(q13q33)")
# result.valid   -> True
# result.errors  -> []
# result.parsed  -> KaryotypeAST(...)

Karyotype gallery

Progressively harder real karyotypes — and what the library returns for each.

01 47,XY,+21

Trisomy 21 (Down syndrome) — simplest aneuploidy.

is_valid_karyotype("47,XY,+21")
# True

02 46,XX,t(9;22)(q34;q11.2)

Philadelphia chromosome (CML) — reciprocal translocation with band-level breakpoints.

result = validate_karyotype("46,XX,t(9;22)(q34;q11.2)")
# result.valid   -> True
# result.parsed.abnormalities[0].kind -> "t"

03 47,XY,+21[8]/46,XY[12]

Mosaic Down syndrome — cell-line splitting on /, clone counts in [ ].

result = validate_karyotype("47,XY,+21[8]/46,XY[12]")
# result.parsed.cell_lines  -> 2
# result.parsed.cell_lines[0].count -> 8

04 46,XX,del(5)(q13q33)

5q deletion syndrome — interstitial deletion with two breakpoints.

is_valid_karyotype("46,XX,del(5)(q13q33)")
# True

05 46,XY,inv(16)(p13.1q22)

Pericentric inversion (AML M4Eo) — inversion straddling the centromere.

is_valid_karyotype("46,XY,inv(16)(p13.1q22)")
# True

06 45,XX,rob(13;14)(q10;q10)

Robertsonian translocation — specialized rearrangement, hypoploid count.

is_valid_karyotype("45,XX,rob(13;14)(q10;q10)")
# True

07 46,XX,+mar[3]/45,XX,-22[12]/46,XX[5]

Three-cell-line mosaic with a marker chromosome — flexes triple /, marker, and minus-count together.

result = validate_karyotype("46,XX,+mar[3]/45,XX,-22[12]/46,XX[5]")
# result.valid              -> True
# len(result.parsed.cell_lines) -> 3

Architecture

A three-stage pipeline: KaryotypeParser → KaryotypeAST → RuleEngine. The rule engine splits checks into chromosome-level (sex chromosomes, total counts) and abnormality-level (per-rearrangement constraints) lists, which keeps each rule small and individually testable.

A curated explanation lookup mapping karyotype signatures to authoritative clinical summaries is deferred to a later release — see the changelog for current status.

MIT licensed Python 3.10, 3.11, 3.12, 3.13

← back to projects