allelix 1.8.1__py3-none-any.whl

allelix/parsers/_helpers.py

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 dial481
+"""Shared helpers for parsers with CSV or concatenated-genotype formats.
+
+Used by FTDNA, MyHeritage, and Living DNA parsers. Extracted here to avoid
+duplicating the genotype-splitting and CSV-line-splitting logic across
+structurally similar formats.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from allelix.models import NO_CALL_MARKER
+
+logger = logging.getLogger(__name__)
+
+
+def split_csv_line(line: str) -> list[str]:
+    """Split a comma-delimited line and strip double-quotes from each field.
+
+    Handles single-quoted, double-quoted, and double-double-quoted fields
+    (the MyHeritage "extra quotes" variant).
+    """
+    return [field.strip().strip('"') for field in line.split(",")]
+
+
+def split_genotype(genotype: str) -> tuple[str, str]:
+    """Split a concatenated genotype field into two alleles.
+
+    ``"AG"`` -> ``("A", "G")``, ``"--"`` -> ``("-", "-")``,
+    ``"A"`` -> ``("A", "A")`` (haploid MT/Y).
+    """
+    if genotype == "--":
+        return NO_CALL_MARKER, NO_CALL_MARKER
+    if len(genotype) == 2:
+        return genotype[0], genotype[1]
+    if len(genotype) == 1:
+        return genotype, genotype
+    logger.warning("Unexpected genotype format %r — treating as no-call", genotype)
+    return NO_CALL_MARKER, NO_CALL_MARKER

allelix/parsers/ancestrydna.py

@@ -0,0 +1,130 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 dial481
+"""Parser for AncestryDNA raw genotype export files.
+
+Format reference (from real sample files and snps package):
+
+    #AncestryDNA raw data download
+    #This file was generated by AncestryDNA ...
+    #Data was collected using AncestryDNA array version: V2.0
+    #
+    rsid    chromosome    position    allele1    allele2
+    rs4477212    1    82154    A    C
+    rs9001001    1    100000    0    0
+
+Specifics:
+    - Comment lines start with ``#``.
+    - Tab-delimited, 5 columns of data (alleles in separate columns).
+    - Detection key: ``#AncestryDNA`` in the first comment line.
+    - Chromosome codes: 23 = X, 24 = Y, 25 = PAR (pseudo-autosomal,
+      mapped to X), 26 = MT.
+    - No-calls represented as ``0`` for each allele.
+    - Build 37 (GRCh37).
+    - V1 chip (pre-May 2016, ~682K SNPs) and V2 chip (May 2016+,
+      ~664K SNPs) share the same column layout.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, ClassVar
+
+from allelix.models import DEFAULT_BUILD, NO_CALL_MARKER, Variant
+from allelix.parsers.base import GenotypeMetadata, GenotypeParser
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+SIGNATURE = "#AncestryDNA"
+EXPECTED_HEADER = "rsid\tchromosome\tposition\tallele1\tallele2"
+EXPECTED_COLUMNS = 5
+SNIFF_LINE_LIMIT = 50
+
+_CHROM_MAP: dict[str, str] = {
+    "23": "X",
+    "24": "Y",
+    "25": "X",
+    "26": "MT",
+}
+
+
+class AncestryDNAParser(GenotypeParser):
+    """Parser for AncestryDNA consumer DNA genotype files."""
+
+    name: ClassVar[str] = "ancestrydna"
+    display_name: ClassVar[str] = "AncestryDNA"
+    file_extensions: ClassVar[list[str]] = [".txt"]
+    url: ClassVar[str] = "https://www.ancestry.com/dna"
+
+    def can_parse(self, file_path: Path) -> bool:
+        """Recognize the file by its ``#AncestryDNA`` signature on the first line."""
+        try:
+            with file_path.open("r", encoding="utf-8") as fh:
+                first_line = fh.readline()
+                return first_line.startswith(SIGNATURE)
+        except (OSError, UnicodeDecodeError):
+            return False
+
+    def parse(self, file_path: Path) -> Iterator[Variant]:
+        """Stream Variant objects, skipping comments and malformed lines."""
+        with file_path.open("r", encoding="utf-8") as fh:
+            header_seen = False
+            for lineno, raw in enumerate(fh, start=1):
+                line = raw.rstrip("\r\n")
+                if not line or line.startswith("#"):
+                    continue
+                if not header_seen:
+                    if line == EXPECTED_HEADER:
+                        header_seen = True
+                        continue
+                    logger.warning(
+                        "Line %d: expected header %r, got %r — skipping",
+                        lineno,
+                        EXPECTED_HEADER,
+                        line,
+                    )
+                    continue
+
+                parts = line.split("\t")
+                if len(parts) != EXPECTED_COLUMNS:
+                    logger.warning(
+                        "Line %d: expected %d columns, got %d — skipping",
+                        lineno,
+                        EXPECTED_COLUMNS,
+                        len(parts),
+                    )
+                    continue
+
+                rsid, chrom_raw, pos_str, allele1, allele2 = parts
+                try:
+                    position = int(pos_str)
+                except ValueError:
+                    logger.warning("Line %d: invalid position %r — skipping", lineno, pos_str)
+                    continue
+
+                chrom = _CHROM_MAP.get(chrom_raw, chrom_raw)
+
+                if allele1 == "0":
+                    allele1 = NO_CALL_MARKER
+                if allele2 == "0":
+                    allele2 = NO_CALL_MARKER
+
+                yield Variant(
+                    rsid=rsid,
+                    chromosome=chrom,
+                    position=position,
+                    allele1=allele1,
+                    allele2=allele2,
+                    build=DEFAULT_BUILD,
+                )
+
+    def get_metadata(self, file_path: Path) -> GenotypeMetadata:
+        """Extract metadata from header comments. AncestryDNA has no sample ID field."""
+        return GenotypeMetadata(
+            format=self.name,
+            sample_id="",
+            build=DEFAULT_BUILD,
+        )

allelix/parsers/base.py

@@ -0,0 +1,97 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 dial481
+"""Abstract base class for genotype file parsers."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, ClassVar, TypedDict
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+    from allelix.models import Variant
+
+
+class GenotypeMetadata(TypedDict):
+    """File-level metadata extracted by `GenotypeParser.get_metadata`.
+
+    Header-derivable fields only. SNP count is intentionally NOT here — the
+    only reliable source for it is `parse()`, since lines that look like data
+    in a header scan may fail validation. Callers that need a count should
+    use `sum(1 for _ in parser.parse(file_path))`.
+
+    Keys:
+        format: Parser name (matches `GenotypeParser.name`).
+        sample_id: Vendor sample identifier, or "" if not present in the file.
+        build: Reference genome build (e.g., "GRCh37").
+    """
+
+    format: str
+    sample_id: str
+    build: str
+
+
+class GenotypeParser(ABC):
+    """Base class for all genotype file parsers.
+
+    Subclasses define metadata as class attributes and implement the three
+    abstract methods. Parsers are stateless — `can_parse` and `parse` may be
+    called repeatedly on different files.
+
+    Attributes:
+        name: Lowercase identifier used by the registry and CLI (e.g., "myhappygenes").
+        display_name: Human-readable name for reports ("MyHappyGenes (Tempus)").
+        file_extensions: Common file extensions (e.g., [".txt"]). Informational only;
+            auto-detection uses `can_parse`, not extension matching.
+        url: Vendor URL.
+    """
+
+    name: ClassVar[str]
+    display_name: ClassVar[str]
+    file_extensions: ClassVar[list[str]]
+    url: ClassVar[str]
+
+    @abstractmethod
+    def can_parse(self, file_path: Path) -> bool:
+        """Sniff the file to determine if this parser handles it.
+
+        Must be fast — examines header/structural lines only, not the full file.
+        Used by the auto-detection registry.
+
+        Args:
+            file_path: Path to the candidate genotype file.
+
+        Returns:
+            True if this parser recognizes the format.
+        """
+        ...
+
+    @abstractmethod
+    def parse(self, file_path: Path) -> Iterator[Variant]:
+        """Yield normalized Variant objects from the file.
+
+        Streaming: yields one variant at a time. Never loads the whole file.
+        Malformed individual lines log a warning and are skipped — they do not
+        abort the whole parse.
+
+        Args:
+            file_path: Path to the genotype file.
+
+        Yields:
+            One Variant per data row in the file.
+        """
+        ...
+
+    @abstractmethod
+    def get_metadata(self, file_path: Path) -> GenotypeMetadata:
+        """Extract header-derivable file metadata. Must be cheap (no full parse).
+
+        Args:
+            file_path: Path to the genotype file.
+
+        Returns:
+            A `GenotypeMetadata` dict.
+        """
+        ...

allelix/parsers/ftdna.py

@@ -0,0 +1,129 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 dial481
+"""Parser for Family Tree DNA (FTDNA) raw genotype export files.
+
+Format reference (from real sample files and snps package):
+
+    # FTDNA raw data download
+    RSID,CHROMOSOME,POSITION,RESULT
+    "rs4477212","1","82154","AA"
+    "rs3094315","1","752566","AG"
+    "rs9001001","1","100000","--"
+
+Specifics:
+    - CSV format, comma-delimited.
+    - Optional comment lines starting with ``#``.
+    - Header line: ``RSID,CHROMOSOME,POSITION,RESULT`` (quoted or unquoted).
+    - Data fields are double-quoted; parser strips quotes.
+    - RESULT column is concatenated genotype (e.g., "AG" not "A","G").
+    - Haploid calls on MT/Y appear as single characters (e.g., "A").
+    - No-calls represented as ``--``.
+    - Build 37 (most files).
+    - Detection key: header line matching ``RSID,CHROMOSOME,POSITION,RESULT``
+      (case-insensitive, with or without quotes) within the first 50 lines.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, ClassVar
+
+from allelix.models import DEFAULT_BUILD, Variant
+from allelix.parsers._helpers import split_csv_line, split_genotype
+from allelix.parsers.base import GenotypeMetadata, GenotypeParser
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+SNIFF_LINE_LIMIT = 50
+EXPECTED_COLUMNS = 4
+HEADER_CANONICAL = "RSID,CHROMOSOME,POSITION,RESULT"
+
+
+def _is_header_line(line: str) -> bool:
+    """True if *line* is the FTDNA column header (quoted or unquoted)."""
+    stripped = line.replace('"', "").replace("'", "").strip()
+    return stripped.upper() == HEADER_CANONICAL
+
+
+class FTDNAParser(GenotypeParser):
+    """Parser for Family Tree DNA consumer DNA genotype files."""
+
+    name: ClassVar[str] = "ftdna"
+    display_name: ClassVar[str] = "Family Tree DNA"
+    file_extensions: ClassVar[list[str]] = [".csv"]
+    url: ClassVar[str] = "https://www.familytreedna.com"
+
+    def can_parse(self, file_path: Path) -> bool:
+        """Recognize the file by its ``RSID,CHROMOSOME,POSITION,RESULT`` header."""
+        try:
+            with file_path.open("r", encoding="utf-8") as fh:
+                for _ in range(SNIFF_LINE_LIMIT):
+                    line = fh.readline()
+                    if not line:
+                        return False
+                    line = line.rstrip("\r\n")
+                    if not line or line.startswith("#"):
+                        continue
+                    return _is_header_line(line)
+        except (OSError, UnicodeDecodeError):
+            return False
+        return False
+
+    def parse(self, file_path: Path) -> Iterator[Variant]:
+        """Stream Variant objects, skipping comments and malformed lines."""
+        with file_path.open("r", encoding="utf-8") as fh:
+            header_seen = False
+            for lineno, raw in enumerate(fh, start=1):
+                line = raw.rstrip("\r\n")
+                if not line or line.startswith("#"):
+                    continue
+                if not header_seen:
+                    if _is_header_line(line):
+                        header_seen = True
+                        continue
+                    logger.warning(
+                        "Line %d: expected FTDNA header, got %r — skipping",
+                        lineno,
+                        line,
+                    )
+                    continue
+
+                parts = split_csv_line(line)
+                if len(parts) != EXPECTED_COLUMNS:
+                    logger.warning(
+                        "Line %d: expected %d columns, got %d — skipping",
+                        lineno,
+                        EXPECTED_COLUMNS,
+                        len(parts),
+                    )
+                    continue
+
+                rsid, chrom, pos_str, genotype = parts
+                try:
+                    position = int(pos_str)
+                except ValueError:
+                    logger.warning("Line %d: invalid position %r — skipping", lineno, pos_str)
+                    continue
+
+                allele1, allele2 = split_genotype(genotype)
+
+                yield Variant(
+                    rsid=rsid,
+                    chromosome=chrom,
+                    position=position,
+                    allele1=allele1,
+                    allele2=allele2,
+                    build=DEFAULT_BUILD,
+                )
+
+    def get_metadata(self, file_path: Path) -> GenotypeMetadata:
+        """Extract metadata from header. FTDNA files have no sample ID field."""
+        return GenotypeMetadata(
+            format=self.name,
+            sample_id="",
+            build=DEFAULT_BUILD,
+        )

allelix/parsers/livingdna.py

@@ -0,0 +1,121 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 dial481
+"""Parser for Living DNA raw genotype export files.
+
+Format reference (from snps package and H600 Project wiki):
+
+    # Living DNA customer genotype data download file version: 1.0.1
+    # This file contains raw genotype data ...
+    # Human Genome Reference Build 37 (GRCh37.p13).
+    # Genotypes are presented on the forward strand.
+    #
+    # rsid  chromosome  position  genotype
+    rs1801133   1   11856378    AG
+    AX-12345678 3   15000000    GG
+    1:726912    1   726912  AA
+
+Specifics:
+    - Tab-delimited despite ``.csv`` file extension.
+    - Detection key: ``Living DNA`` in the first line.
+    - Comment lines start with ``#``, including the column header line.
+    - Four columns: ``rsid``, ``chromosome``, ``position``, ``genotype``.
+    - Concatenated genotype in result column (e.g., "AA", "CT").
+    - No-calls represented as ``--``.
+    - Build 37 (GRCh37.p13), forward strand.
+    - SNP ID types: rs-numbers, ``AX-`` prefixed (Affymetrix),
+      ``AFFX-`` prefixed (Affymetrix control probes), and positional
+      notation (``CHR:POS``, e.g., ``1:726912``).
+    - Y and MT chromosomes delivered as separate files; main file
+      has chromosomes 1-22 and X.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, ClassVar
+
+from allelix.models import DEFAULT_BUILD, Variant
+from allelix.parsers._helpers import split_genotype
+from allelix.parsers.base import GenotypeMetadata, GenotypeParser
+from allelix.utils.build_detect import normalize_build_label
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+SIGNATURE = "Living DNA"
+SNIFF_LINE_LIMIT = 50
+EXPECTED_COLUMNS = 4
+
+
+class LivingDNAParser(GenotypeParser):
+    """Parser for Living DNA consumer genotype files."""
+
+    name: ClassVar[str] = "livingdna"
+    display_name: ClassVar[str] = "Living DNA"
+    file_extensions: ClassVar[list[str]] = [".csv"]
+    url: ClassVar[str] = "https://livingdna.com"
+
+    def can_parse(self, file_path: Path) -> bool:
+        """Recognize the file by ``Living DNA`` in the first line."""
+        try:
+            with file_path.open("r", encoding="utf-8") as fh:
+                first_line = fh.readline()
+                return SIGNATURE in first_line
+        except (OSError, UnicodeDecodeError):
+            return False
+
+    def parse(self, file_path: Path) -> Iterator[Variant]:
+        """Stream Variant objects, skipping comments and malformed lines."""
+        with file_path.open("r", encoding="utf-8") as fh:
+            for lineno, raw in enumerate(fh, start=1):
+                line = raw.rstrip("\r\n")
+                if not line or line.startswith("#"):
+                    continue
+
+                parts = line.split("\t")
+                if len(parts) != EXPECTED_COLUMNS:
+                    logger.warning(
+                        "Line %d: expected %d columns, got %d — skipping",
+                        lineno,
+                        EXPECTED_COLUMNS,
+                        len(parts),
+                    )
+                    continue
+
+                rsid, chrom, pos_str, genotype = parts
+                try:
+                    position = int(pos_str)
+                except ValueError:
+                    logger.warning("Line %d: invalid position %r — skipping", lineno, pos_str)
+                    continue
+
+                allele1, allele2 = split_genotype(genotype)
+
+                yield Variant(
+                    rsid=rsid,
+                    chromosome=chrom,
+                    position=position,
+                    allele1=allele1,
+                    allele2=allele2,
+                    build=DEFAULT_BUILD,
+                )
+
+    def get_metadata(self, file_path: Path) -> GenotypeMetadata:
+        """Extract build from header comments. Living DNA has no sample ID field."""
+        build = DEFAULT_BUILD
+        with file_path.open("r", encoding="utf-8") as fh:
+            for raw in fh:
+                line = raw.rstrip("\r\n")
+                if not line.startswith("#"):
+                    break
+                normalized = normalize_build_label(line)
+                if normalized:
+                    build = normalized
+        return GenotypeMetadata(
+            format=self.name,
+            sample_id="",
+            build=build,
+        )

allelix/parsers/myhappygenes.py

@@ -0,0 +1,135 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 dial481
+"""Parser for MyHappyGenes (Tempus) genotype export files.
+
+Format reference (from sample  file):
+
+    # MyHappyGenes [TEMPUS]
+    # This file was generated by MyHappyGenes, Inc.
+    # ... (additional comment lines)
+    # Sample ID    MHG000001
+    SNP Name    Chr    Position    Allele1 - Forward    Allele2 - Forward
+    rs9651229    1    632287    C    C
+    rs9701872    1    632828    T    T
+
+Specifics:
+    - Comment lines start with `#`.
+    - Tab-delimited, 5 columns of data.
+    - Header claims build 37.1, but real-world exports we've verified
+      contain GRCh38 positions. The analyze pipeline runs auto-
+      detection (ADR-0021) and overrides the parser-reported build
+      based on position data. The build value returned here reflects
+      the literal header claim; downstream code should not assume it.
+      Forward strand with respect to the reference.
+    - No-calls represented as `-`.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, ClassVar
+
+from allelix.models import DEFAULT_BUILD, Variant
+from allelix.parsers.base import GenotypeMetadata, GenotypeParser
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+SIGNATURE = "# MyHappyGenes"
+SAMPLE_ID_PREFIX = "# Sample ID"
+EXPECTED_HEADER = "SNP Name\tChr\tPosition\tAllele1 - Forward\tAllele2 - Forward"
+EXPECTED_COLUMNS = 5
+SNIFF_LINE_LIMIT = 50
+
+
+class MyHappyGenesParser(GenotypeParser):
+    """Parser for MyHappyGenes/Tempus consumer DNA genotype files."""
+
+    name: ClassVar[str] = "myhappygenes"
+    display_name: ClassVar[str] = "MyHappyGenes (Tempus)"
+    file_extensions: ClassVar[list[str]] = [".txt"]
+    url: ClassVar[str] = "https://myhappygenes.com"
+
+    def can_parse(self, file_path: Path) -> bool:
+        """Recognize the file by its `# MyHappyGenes` signature line."""
+        try:
+            with file_path.open("r", encoding="utf-8") as fh:
+                for _ in range(SNIFF_LINE_LIMIT):
+                    line = fh.readline()
+                    if not line:
+                        return False
+                    if SIGNATURE in line:
+                        return True
+        except (OSError, UnicodeDecodeError):
+            return False
+        return False
+
+    def parse(self, file_path: Path) -> Iterator[Variant]:
+        """Stream Variant objects, skipping comments and malformed lines."""
+        with file_path.open("r", encoding="utf-8") as fh:
+            header_seen = False
+            for lineno, raw in enumerate(fh, start=1):
+                line = raw.rstrip("\r\n")
+                if not line or line.startswith("#"):
+                    continue
+                if not header_seen:
+                    if line == EXPECTED_HEADER:
+                        header_seen = True
+                        continue
+                    logger.warning(
+                        "Line %d: expected header %r, got %r — skipping",
+                        lineno,
+                        EXPECTED_HEADER,
+                        line,
+                    )
+                    continue
+
+                parts = line.split("\t")
+                if len(parts) != EXPECTED_COLUMNS:
+                    logger.warning(
+                        "Line %d: expected %d columns, got %d — skipping",
+                        lineno,
+                        EXPECTED_COLUMNS,
+                        len(parts),
+                    )
+                    continue
+
+                rsid, chrom, pos_str, allele1, allele2 = parts
+                try:
+                    position = int(pos_str)
+                except ValueError:
+                    logger.warning("Line %d: invalid position %r — skipping", lineno, pos_str)
+                    continue
+
+                yield Variant(
+                    rsid=rsid,
+                    chromosome=chrom,
+                    position=position,
+                    allele1=allele1,
+                    allele2=allele2,
+                    build=DEFAULT_BUILD,
+                )
+
+    def get_metadata(self, file_path: Path) -> GenotypeMetadata:
+        """Extract sample ID from the file header. Cheap — no full parse."""
+        sample_id = ""
+        with file_path.open("r", encoding="utf-8") as fh:
+            for raw in fh:
+                line = raw.rstrip("\r\n")
+                if not line:
+                    continue
+                if line.startswith(SAMPLE_ID_PREFIX):
+                    parts = line.split("\t", 1)
+                    if len(parts) == 2:
+                        sample_id = parts[1].strip()
+                    break
+                if not line.startswith("#"):
+                    break
+        return GenotypeMetadata(
+            format=self.name,
+            sample_id=sample_id,
+            build=DEFAULT_BUILD,
+        )