tpixel 0.1.1.dev0__py3-none-any.whl

tpixel/__init__.py

@@ -0,0 +1,24 @@
+"""tpixel — Pixel-block alignment viewer for hundreds of sequences."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from tpixel.fasta import fasta_panel, read_fasta
+from tpixel.hiv import hiv_panel
+from tpixel.models import Marker, Panel, Region, SeqGroup
+from tpixel.renderer import render_panels
+
+try:
+    __version__ = version("tpixel")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "Marker",
+    "Panel",
+    "Region",
+    "SeqGroup",
+    "fasta_panel",
+    "hiv_panel",
+    "read_fasta",
+    "render_panels",
+]

tpixel/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.1.1.dev0'
+__version_tuple__ = version_tuple = (0, 1, 1, 'dev0')
+
+__commit_id__ = commit_id = None

tpixel/cli.py

@@ -0,0 +1,137 @@
+"""Click CLI for tpixel."""
+
+import sys
+
+import click
+
+from tpixel.fasta import fasta_panel, read_fasta
+from tpixel.renderer import render_panels
+
+
+def _expand_stdin(paths: list[str]) -> list[str]:
+    """If paths is ``['-']``, read file paths from stdin (one per line).
+
+    Args:
+        paths: List of file path strings. A single ``'-'`` triggers stdin reading.
+
+    Returns:
+        Expanded list of file paths.
+
+    Examples:
+        >>> _expand_stdin(["file1.fasta", "file2.fasta"])
+        ['file1.fasta', 'file2.fasta']
+        >>> _expand_stdin([])
+        []
+    """
+    if paths and len(paths) == 1 and paths[0] == "-":
+        return [line.strip() for line in sys.stdin if line.strip()]
+    return list(paths)
+
+
+def _auto_detect_hiv(fasta_path: str) -> bool:
+    """Check if alignment contains HxB2 and a ``*_ref`` sequence.
+
+    Args:
+        fasta_path: Path to the aligned FASTA file.
+
+    Returns:
+        ``True`` if both HxB2 and a ``*_ref`` sequence are present.
+    """
+    seqs = read_fasta(fasta_path)
+    names = {n.split()[0] for n, _ in seqs}
+    has_hxb2 = "HxB2" in names
+    has_ref = any(n.endswith("_ref") for n in names)
+    return has_hxb2 and has_ref
+
+
+@click.command(
+    context_settings={"help_option_names": ["-h", "--help"]},
+    epilog="Use '-' to read file paths from stdin, e.g.:\n\n"
+    "  find . -name '*.fasta' | tpixel --fasta - -o out.png",
+)
+@click.option(
+    "--fasta",
+    multiple=True,
+    help="Aligned FASTA file(s) — each becomes a panel. Use '-' for stdin.",
+)
+@click.option(
+    "--columns", help="Column range for FASTA, 1-based inclusive (e.g. 1-120)."
+)
+@click.option(
+    "-o",
+    "--output",
+    default="pixel.png",
+    show_default=True,
+    help="Output image path.",
+)
+@click.option(
+    "--dpi", type=int, default=300, show_default=True, help="Image resolution."
+)
+@click.option(
+    "--cell", type=float, default=None, help="Cell size in inches (default: 0.03)."
+)
+@click.option(
+    "--hiv/--no-hiv",
+    default=None,
+    help="Force HIV mode (HxB2 regions, PNGS, animal grouping). Auto-detected if omitted.",
+)
+@click.option(
+    "--nt/--aa",
+    default=None,
+    help="Force nucleotide or amino-acid mode. Auto-detected if omitted.",
+)
+@click.option(
+    "--ref-pos",
+    default="1,2",
+    show_default=True,
+    help="Comma-separated 1-based positions of reference sequences. "
+    "Last position is the primary reference; earlier ones are extra reference rows.",
+)
+@click.option(
+    "--title",
+    default=None,
+    help="Title displayed above the plot.",
+)
+def main(fasta, columns, output, dpi, cell, hiv, nt, ref_pos, title):
+    """Pixel-block alignment viewer for hundreds of sequences.
+
+    Renders Roark-style PIXEL plots: grey=match, red=substitution, black=gap.
+    Each sequence is a thin row of colored blocks — no text in cells.
+
+    HIV mode is auto-detected when the alignment contains HxB2 and a *_ref
+    sequence. Force with --hiv or --no-hiv.
+    """
+    fasta_paths = _expand_stdin(list(fasta))
+
+    if not fasta_paths:
+        raise click.UsageError("Provide --fasta")
+
+    ref_positions = [int(x) for x in ref_pos.split(",")]
+
+    panels = []
+    col_start, col_end = None, None
+    if columns:
+        parts = columns.replace(",", "").split("-")
+        col_start = int(parts[0])
+        col_end = int(parts[1]) if len(parts) > 1 else None
+
+    for fasta_path in fasta_paths:
+        use_hiv = hiv if hiv is not None else _auto_detect_hiv(fasta_path)
+
+        if use_hiv:
+            from tpixel.hiv import hiv_panel
+
+            seq_type = None
+            if nt is True:
+                seq_type = "NT"
+            elif nt is False:
+                seq_type = "AA"
+            panel = hiv_panel(fasta_path, ref_positions=ref_positions, seq_type=seq_type)
+        else:
+            panel = fasta_panel(fasta_path, col_start, col_end, ref_positions=ref_positions)
+
+        if title:
+            panel.title = title
+        panels.append(panel)
+
+    render_panels(panels, output, dpi=dpi, cell=cell)

tpixel/fasta.py

@@ -0,0 +1,109 @@
+"""FASTA parsing and panel construction."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from tpixel.models import Panel
+
+
+def read_fasta(path: str | Path) -> list[tuple[str, str]]:
+    """Parse a FASTA file into a list of (name, sequence) tuples.
+
+    Args:
+        path: Path to the FASTA file.
+
+    Returns:
+        List of (header_name, concatenated_sequence) tuples.
+    """
+    seqs: list[tuple[str, str]] = []
+    name: str | None = None
+    buf: list[str] = []
+    with open(path, encoding="utf-8") as fh:
+        for line in fh:
+            if line.startswith(">"):
+                if name is not None:
+                    seqs.append((name, "".join(buf)))
+                name = line[1:].strip()
+                buf = []
+            else:
+                buf.append(line.strip())
+    if name is not None:
+        seqs.append((name, "".join(buf)))
+    return seqs
+
+
+def fasta_panel(
+    path: str | Path,
+    col_start: int | None = None,
+    col_end: int | None = None,
+    ref_positions: list[int] | None = None,
+) -> Panel:
+    """Build a Panel from an aligned FASTA.
+
+    Args:
+        path: Path to the aligned FASTA file.
+        col_start: 1-based inclusive start column for slicing the alignment.
+        col_end: 1-based inclusive end column for slicing the alignment.
+        ref_positions: 1-based positions of reference sequences. Last is
+            the primary reference; earlier ones become extra reference rows.
+            Defaults to [1].
+
+    Returns:
+        A Panel with reference row, sequence rows, and column labels.
+
+    Raises:
+        ValueError: If the FASTA file contains no sequences.
+    """
+    if ref_positions is None:
+        ref_positions = [1]
+
+    seqs = read_fasta(path)
+    if not seqs:
+        raise ValueError(f"No sequences in {path}")
+
+    # Primary reference is the last position in ref_positions
+    primary_idx = ref_positions[-1] - 1
+    _ref_name, ref_seq = seqs[primary_idx]
+
+    # Slice columns if requested (1-based inclusive)
+    if col_start is not None or col_end is not None:
+        cs = (col_start or 1) - 1
+        ce = col_end or len(ref_seq)
+        ref_seq = ref_seq[cs:ce]
+        seqs = [(n, s[cs:ce]) for n, s in seqs]
+
+    aln_len = len(ref_seq)
+    ref_row = list(ref_seq.upper())
+
+    # Extra reference rows (all ref positions except the last)
+    extra_ref_rows: list[tuple[str, list[str]]] = []
+    for pos in ref_positions[:-1]:
+        idx = pos - 1
+        name, seq = seqs[idx]
+        row = list(seq.upper()[:aln_len])
+        row += ["-"] * (aln_len - len(row))
+        extra_ref_rows.append((name, row))
+
+    # Sample sequences: everything not in ref_positions
+    ref_indices = {pos - 1 for pos in ref_positions}
+    seq_rows: list[tuple[str, list[str]]] = []
+    for i, (name, seq) in enumerate(seqs):
+        if i in ref_indices:
+            continue
+        row = list(seq.upper()[:aln_len])
+        row += ["-"] * (aln_len - len(row))
+        seq_rows.append((name, row))
+
+    # Column labels: 1-based position in the reference (skip gap columns)
+    col_labels: list[tuple[int, str]] = []
+    ref_pos = 0
+    for i, base in enumerate(ref_row):
+        if base != "-":
+            ref_pos += 1
+            if ref_pos == 1 or ref_pos % 10 == 0:
+                col_labels.append((i, str(ref_pos)))
+
+    label = Path(path).stem
+    return Panel(label, ref_row, seq_rows, aln_len, col_labels,
+                 extra_ref_rows=extra_ref_rows or None)

tpixel/hiv.py

@@ -0,0 +1,190 @@
+"""HIV-aware panel builder for PIXEL plots.
+
+Handles HxB2 coordinate mapping, Env region annotations, PNGS markers,
+and animal-based sequence grouping from SHIV/HIV aligned FASTA files.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from pathlib import Path
+
+from tpixel.fasta import read_fasta
+from tpixel.hxb2 import _is_nucleotide, build_hxb2_map, hxb2_col_labels, hxb2_regions
+from tpixel.models import Marker, Panel, SeqGroup
+from tpixel.pngs import find_pngs_markers, find_pngs_markers_nt
+
+
+def _find_ref_id(names: list[str]) -> str | None:
+    """Find the parental reference (name ending with ``'_ref'``).
+
+    Args:
+        names: Sequence IDs from the alignment.
+
+    Returns:
+        First name ending with ``'_ref'``, or ``None``.
+
+    Examples:
+        >>> _find_ref_id(["HxB2", "animal1_ref", "animal1_s1"])
+        'animal1_ref'
+        >>> _find_ref_id(["HxB2", "s1", "s2"]) is None
+        True
+    """
+    for name in names:
+        if name.endswith("_ref"):
+            return name
+    return None
+
+
+def _extract_animal(seq_id: str) -> str:
+    """Extract animal name from sequence ID (prefix before first ``'_'``).
+
+    Args:
+        seq_id: Full sequence identifier string.
+
+    Returns:
+        The portion of *seq_id* before the first underscore.
+
+    Examples:
+        >>> _extract_animal("animal1_s1")
+        'animal1'
+        >>> _extract_animal("RM5695_env_s3")
+        'RM5695'
+        >>> _extract_animal("nounderscore")
+        'nounderscore'
+    """
+    parts = seq_id.split("_")
+    return parts[0]
+
+
+def _sort_animal_groups(animal_names: list[str], lineage: str) -> list[str]:
+    """Sort: lineage self first, recombinants, then alphabetical.
+
+    Args:
+        animal_names: Unique animal/group names to sort.
+        lineage: The lineage name to place first.
+
+    Returns:
+        Sorted list: lineage first, then recombinants, then others alphabetically.
+
+    Examples:
+        >>> _sort_animal_groups(["B", "rec1", "A", "lin1"], "lin1")
+        ['lin1', 'rec1', 'A', 'B']
+        >>> _sort_animal_groups(["X", "Y"], "Z")
+        ['X', 'Y']
+    """
+    self_group = []
+    rec_group = []
+    other_group = []
+    for name in animal_names:
+        if name == lineage:
+            self_group.append(name)
+        elif name.lower().startswith("rec"):
+            rec_group.append(name)
+        else:
+            other_group.append(name)
+    return self_group + sorted(rec_group) + sorted(other_group)
+
+
+def hiv_panel(
+    path: str | Path,
+    hxb2_id: str = "HxB2",
+    ref_id: str | None = None,
+    tick_step: int = 50,
+    ref_positions: list[int] | None = None,
+    seq_type: str | None = None,
+) -> Panel:
+    """Build a full Roark-style Panel from an HIV Env alignment.
+
+    Args:
+        path: Path to aligned FASTA containing HxB2 and a *_ref sequence.
+            Accepts both amino-acid and nucleotide alignments.
+        hxb2_id: ID of the HxB2 coordinate reference in the alignment.
+        ref_id: Parental reference ID. Auto-detected (*_ref) if None.
+            Ignored when ref_positions is provided.
+        tick_step: HxB2 AA position interval for x-axis ticks.
+        ref_positions: 1-based positions of reference sequences. Last is
+            the primary reference; earlier ones become extra reference rows.
+            Defaults to [1, 2].
+        seq_type: ``"NT"`` or ``"AA"``.  Auto-detected from the reference
+            sequence when *None*.
+
+    Returns:
+        Panel with regions, PNGS markers, grouped sequences, and HxB2 ticks.
+    """
+    seqs = read_fasta(path)
+    if not seqs:
+        raise ValueError(f"No sequences in {path}")
+
+    names = [n for n, _ in seqs]
+    seq_dict = {n: s for n, s in seqs}
+
+    if ref_positions is not None:
+        # Position-based: last position is primary reference
+        primary_idx = ref_positions[-1] - 1
+        ref_id = names[primary_idx]
+    else:
+        # Name-based auto-detection (original behavior)
+        ref_positions = [1, 2]
+        if ref_id is None:
+            ref_id = _find_ref_id(names)
+        if ref_id is None:
+            raise ValueError("No *_ref sequence found. Specify ref_id explicitly.")
+        if ref_id not in seq_dict:
+            raise ValueError(f"Reference '{ref_id}' not in alignment")
+
+    ref_seq = seq_dict[ref_id]
+    aln_len = len(ref_seq)
+    ref_row = list(ref_seq.upper())
+
+    # Auto-detect sequence type from reference when not specified
+    if seq_type is None:
+        seq_type = "NT" if _is_nucleotide(ref_seq) else "AA"
+
+    hxb2_map = build_hxb2_map(seqs, hxb2_id, seq_type=seq_type)
+    regions = hxb2_regions(hxb2_map)
+    col_labels = hxb2_col_labels(hxb2_map, step=tick_step)
+
+    if seq_type == "NT":
+        markers = find_pngs_markers_nt(ref_seq, hxb2_map)
+    else:
+        markers = find_pngs_markers(ref_seq, hxb2_map)
+
+    lineage = ref_id.replace("_ref", "") if ref_id.endswith("_ref") else ref_id
+
+    # Extra reference rows: all ref positions except the last
+    extra_ref_rows: list[tuple[str, list[str]]] = []
+    for pos in ref_positions[:-1]:
+        idx = pos - 1
+        name = names[idx]
+        seq = seq_dict[name]
+        row = list(seq.upper()[:aln_len])
+        row += ["-"] * (aln_len - len(row))
+        extra_ref_rows.append((name, row))
+
+    # Group sample sequences by animal
+    skip = {names[pos - 1] for pos in ref_positions}
+    animal_seqs: dict[str, list[tuple[str, list[str]]]] = defaultdict(list)
+    for name, seq in seqs:
+        if name in skip:
+            continue
+        animal = _extract_animal(name)
+        row = list(seq.upper()[:aln_len])
+        row += ["-"] * (aln_len - len(row))
+        animal_seqs[animal].append((name, row))
+
+    sorted_animals = _sort_animal_groups(list(animal_seqs.keys()), lineage)
+    groups = [SeqGroup(name=a, seqs=animal_seqs[a]) for a in sorted_animals]
+
+    return Panel(
+        label=ref_id,
+        ref_row=ref_row,
+        seq_rows=[],
+        total_cols=aln_len,
+        col_labels=col_labels,
+        regions=regions,
+        markers=markers,
+        marker_color="#4CAF50",
+        groups=groups,
+        extra_ref_rows=extra_ref_rows,
+    )

tpixel/hxb2.py

@@ -0,0 +1,187 @@
+"""HxB2 coordinate mapping for HIV Env gp160 protein alignments.
+
+Maps alignment columns to HxB2 amino acid positions and Env structural
+regions using the LANL convention boundaries.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from tpixel.models import Region
+
+ENV_REGIONS: list[tuple[str, int, int]] = [
+    ("SP",    1,  30),
+    ("C1",   31, 130),
+    ("V1",  131, 157),
+    ("V2",  158, 196),
+    ("C2",  197, 295),
+    ("V3",  296, 331),
+    ("C3",  332, 384),
+    ("V4",  385, 418),
+    ("C4",  419, 459),
+    ("V5",  460, 469),
+    ("C5",  470, 511),
+    ("gp41", 512, 856),
+]
+
+REGION_COLORS: dict[str, str] = {
+    "SP":   "#FFF9C4",
+    "C1":   "#EEEEEE",
+    "V1":   "#BBDEFB",
+    "V2":   "#BBDEFB",
+    "C2":   "#EEEEEE",
+    "V3":   "#BBDEFB",
+    "C3":   "#EEEEEE",
+    "V4":   "#BBDEFB",
+    "C4":   "#EEEEEE",
+    "V5":   "#BBDEFB",
+    "C5":   "#EEEEEE",
+    "gp41": "#F8BBD0",
+}
+
+_REGION_LOOKUP: dict[int, str] = {}
+for _name, _start, _end in ENV_REGIONS:
+    for _pos in range(_start, _end + 1):
+        _REGION_LOOKUP[_pos] = _name
+
+
+def get_env_region(hxb2_aa_pos: int) -> str | None:
+    """Return the Env region name for an HxB2 amino acid position.
+
+    Args:
+        hxb2_aa_pos: 1-based HxB2 amino acid position.
+
+    Returns:
+        Region name (e.g. ``'V3'``) or ``None`` if outside known boundaries.
+
+    Examples:
+        >>> get_env_region(1)
+        'SP'
+        >>> get_env_region(131)
+        'V1'
+        >>> get_env_region(296)
+        'V3'
+        >>> get_env_region(900) is None
+        True
+    """
+    return _REGION_LOOKUP.get(hxb2_aa_pos)
+
+
+@dataclass
+class HxB2Position:
+    """A single alignment column mapped to HxB2 coordinates.
+
+    Attributes:
+        alignment_col: 0-based alignment column index.
+        hxb2_aa_pos: 1-based HxB2 amino acid position, or ``None`` for gaps.
+        region: Env region name (e.g. ``'V3'``), or ``None``.
+        hxb2_residue: The residue character at this column in the HxB2 sequence.
+    """
+
+    alignment_col: int
+    hxb2_aa_pos: int | None
+    region: str | None
+    hxb2_residue: str
+
+
+def _is_nucleotide(seq: str) -> bool:
+    """Return True if *seq* looks like a nucleotide sequence.
+
+    Examples:
+        >>> _is_nucleotide("ACGTACGT")
+        True
+        >>> _is_nucleotide("MWLK")
+        False
+        >>> _is_nucleotide("ACG-T.NU")
+        True
+        >>> _is_nucleotide("")
+        True
+    """
+    nt_chars = set("ACGTUNacgtun-.")
+    return all(c in nt_chars for c in seq)
+
+
+def build_hxb2_map(
+    aligned_seqs: list[tuple[str, str]],
+    hxb2_id: str = "HxB2",
+    seq_type: str | None = None,
+) -> list[HxB2Position]:
+    """Walk the HxB2 row and map every alignment column to HxB2 coordinates.
+
+    Args:
+        aligned_seqs: List of (name, sequence) from read_fasta.
+        hxb2_id: Sequence ID of HxB2 in the alignment.
+        seq_type: ``"NT"`` or ``"AA"``.  Auto-detected from the HxB2
+            sequence when *None*.
+
+    Returns:
+        One HxB2Position per alignment column.
+    """
+    hxb2_seq = None
+    for name, seq in aligned_seqs:
+        if name == hxb2_id or name.split()[0] == hxb2_id:
+            hxb2_seq = seq
+            break
+
+    if hxb2_seq is None:
+        raise ValueError(f"HxB2 sequence '{hxb2_id}' not found in alignment")
+
+    if seq_type is None:
+        seq_type = "NT" if _is_nucleotide(hxb2_seq) else "AA"
+
+    is_nt = seq_type == "NT"
+
+    positions: list[HxB2Position] = []
+    nt_counter = 0
+    aa_counter = 0
+
+    for col_idx, residue in enumerate(hxb2_seq):
+        if residue in ("-", "."):
+            positions.append(HxB2Position(col_idx, None, None, residue))
+        else:
+            if is_nt:
+                nt_counter += 1
+                aa_pos = (nt_counter - 1) // 3 + 1
+            else:
+                aa_counter += 1
+                aa_pos = aa_counter
+            positions.append(HxB2Position(col_idx, aa_pos, get_env_region(aa_pos), residue))
+
+    return positions
+
+
+def hxb2_col_labels(hxb2_map: list[HxB2Position], step: int = 50) -> list[tuple[int, str]]:
+    """Build x-axis tick labels at regular HxB2 AA intervals."""
+    max_pos = max((p.hxb2_aa_pos for p in hxb2_map if p.hxb2_aa_pos is not None), default=0)
+    labels: list[tuple[int, str]] = []
+    for target in range(step, max_pos + 1, step):
+        for p in hxb2_map:
+            if p.hxb2_aa_pos == target:
+                labels.append((p.alignment_col, str(target)))
+                break
+    return labels
+
+
+def hxb2_regions(hxb2_map: list[HxB2Position]) -> list[Region]:
+    """Build Region annotations from HxB2 position map."""
+    region_spans: list[tuple[str, int, int]] = []
+    current: str | None = None
+    span_start = 0
+
+    for p in hxb2_map:
+        r = p.region
+        if r != current:
+            if current is not None:
+                region_spans.append((current, span_start, p.alignment_col))
+            current = r
+            span_start = p.alignment_col
+
+    if current is not None:
+        region_spans.append((current, span_start, len(hxb2_map)))
+
+    return [
+        Region(name, start, end, REGION_COLORS.get(name, "#EEEEEE"))
+        for name, start, end in region_spans
+        if name is not None
+    ]