pedview 1.0.0__py3-none-any.whl

pedview/__init__.py

@@ -0,0 +1,5 @@
+"""pedview package."""
+
+__all__ = ["__version__"]
+
+__version__ = "1.0.0"

pedview/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

pedview/cli.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .layout import build_family_layout
+from .parser import PedigreeFormatError, parse_pedigree
+from .render import render_report
+from .validate import summarize_pedigree, validate_pedigree
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pedview",
+        description="Build interactive pedigree reports from pedigree-style family files.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    validate_parser = subparsers.add_parser(
+        "validate", help="Validate a pedigree file."
+    )
+    validate_parser.add_argument(
+        "input_path", help="Path to a pedigree file (.ped, .fam)."
+    )
+
+    preview_parser = subparsers.add_parser(
+        "preview", help="Summarize pedigree contents."
+    )
+    preview_parser.add_argument(
+        "input_path", help="Path to a pedigree file (.ped, .fam)."
+    )
+
+    build_parser_ = subparsers.add_parser(
+        "build", help="Generate a standalone HTML report."
+    )
+    build_parser_.add_argument(
+        "input_path", help="Path to a pedigree file (.ped, .fam)."
+    )
+    build_parser_.add_argument(
+        "-o",
+        "--output",
+        help="Path to the output HTML file. Defaults to <input>.html.",
+    )
+    build_parser_.add_argument(
+        "--family",
+        help="Optional family ID filter. Only render the requested family.",
+    )
+    build_parser_.add_argument(
+        "--title",
+        help="Optional report title. Defaults to a title derived from the input filename.",
+    )
+    build_parser_.add_argument(
+        "--ancestor-inbreeding",
+        type=float,
+        help="Global Wright ancestor inbreeding coefficient (f_a). Defaults to 0.0 when omitted.",
+    )
+    build_parser_.add_argument(
+        "--variant-name",
+        help="Optional label or name of the candidate variant being analyzed (e.g. SCN1A:c.1234G>A).",
+    )
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "validate":
+        return run_validate(args.input_path)
+    if args.command == "preview":
+        return run_preview(args.input_path)
+    if args.command == "build":
+        return run_build(
+            args.input_path,
+            args.output,
+            args.family,
+            args.title,
+            args.ancestor_inbreeding,
+            args.variant_name,
+        )
+    parser.error("Unknown command.")
+    return 2
+
+
+def run_validate(input_path: str) -> int:
+    pedigree, messages = load_with_messages(input_path)
+    print_validation_result(pedigree.source_path, messages)
+    return 1 if any(message.severity == "error" for message in messages) else 0
+
+
+def run_preview(input_path: str) -> int:
+    pedigree, messages = load_with_messages(input_path)
+    summaries = summarize_pedigree(pedigree)
+    print(f"Source: {pedigree.source_path}")
+    print(f"Families: {len(summaries)}")
+    print(f"Individuals: {pedigree.people_count()}")
+    for summary in summaries:
+        print(
+            f"- {summary.family_id}: {summary.people_count} individuals, "
+            f"{summary.founders_count} founders, "
+            f"{summary.relationship_count} parent references, "
+            f"{summary.generation_count} generations"
+        )
+    if messages:
+        print()
+        print_validation_messages(messages)
+    return 1 if any(message.severity == "error" for message in messages) else 0
+
+
+def run_build(
+    input_path: str,
+    output_path: str | None,
+    family_filter: str | None,
+    title: str | None,
+    ancestor_inbreeding: float | None,
+    variant_name: str | None = None,
+) -> int:
+    pedigree, messages = load_with_messages(input_path)
+    if family_filter:
+        if family_filter not in pedigree.families:
+            print(
+                f"Family '{family_filter}' was not found in the input.", file=sys.stderr
+            )
+            return 1
+        pedigree.families = {family_filter: pedigree.families[family_filter]}
+    if any(message.severity == "error" for message in messages):
+        print_validation_result(pedigree.source_path, messages)
+        return 1
+
+    summaries = summarize_pedigree(pedigree)
+    family_layouts = {
+        summary.family_id: build_family_layout(pedigree.families[summary.family_id])
+        for summary in summaries
+    }
+    ancestor_inbreeding_value = (
+        ancestor_inbreeding if ancestor_inbreeding is not None else 0.0
+    )
+    output = (
+        Path(output_path)
+        if output_path
+        else default_output_path(input_path, family_filter)
+    )
+    report_title = title or f"pedview report: {Path(input_path).stem}"
+    html = render_report(
+        pedigree=pedigree,
+        family_layouts=family_layouts,
+        family_summaries=summaries,
+        messages=[message for message in messages if message.severity == "warning"],
+        title=report_title,
+        ancestor_inbreeding=ancestor_inbreeding_value,
+        used_default_ancestor_inbreeding=ancestor_inbreeding is None,
+        variant_name=variant_name,
+    )
+    output.write_text(html, encoding="utf-8")
+    if ancestor_inbreeding is None:
+        print(
+            "Using Wright ancestor inbreeding coefficient f_a = 0.0 (default). "
+            "Pass --ancestor-inbreeding to override."
+        )
+    else:
+        print(
+            f"Using Wright ancestor inbreeding coefficient f_a = {ancestor_inbreeding_value:.4f}."
+        )
+    print(f"Wrote {output}")
+    return 0
+
+
+def load_with_messages(input_path: str):
+    try:
+        pedigree = parse_pedigree(input_path)
+    except PedigreeFormatError as exc:
+        print(f"[ERROR] {exc}", file=sys.stderr)
+        raise SystemExit(1) from exc
+    messages = [*pedigree.messages, *validate_pedigree(pedigree)]
+    return pedigree, messages
+
+
+def default_output_path(input_path: str, family_filter: str | None) -> Path:
+    input_file = Path(input_path)
+    suffix = f".{family_filter}" if family_filter else ""
+    return input_file.with_suffix(f"{suffix}.html")
+
+
+def print_validation_result(source_path: str, messages) -> None:
+    print(f"Validation result for {source_path}")
+    if not messages:
+        print("No validation issues found.")
+        return
+    print_validation_messages(messages)
+    error_count = sum(message.severity == "error" for message in messages)
+    warning_count = sum(message.severity == "warning" for message in messages)
+    print(f"{error_count} error(s), {warning_count} warning(s)")
+
+
+def print_validation_messages(messages) -> None:
+    for message in messages:
+        print(message.format_for_cli())

pedview/insights.py

@@ -0,0 +1,301 @@
+from __future__ import annotations
+
+from functools import cache
+
+from .layout import assign_generations
+from .models import Family
+from .phenotypes import affected_status_from_metadata
+from .segregation import analyze_family_segregation
+
+
+def build_family_insights(
+    family: Family, variant_name: str | None = None
+) -> dict[str, object]:
+    family.ensure_relationships()
+    generations = assign_generations(family)
+    order_index = family.order_index()
+    people = family.members
+    person_ids = list(family.order)
+    founder_ids = [
+        person_id
+        for person_id, person in people.items()
+        if person.father_id not in people and person.mother_id not in people
+    ]
+    founder_id_set = set(founder_ids)
+    affected_status = {
+        person_id: affected_status_from_metadata(person.metadata)
+        for person_id, person in people.items()
+    }
+    parent_map = {
+        person_id: (
+            person.father_id if person.father_id in people else None,
+            person.mother_id if person.mother_id in people else None,
+        )
+        for person_id, person in people.items()
+    }
+    children_by_parent = {person_id: [] for person_id in person_ids}
+    partners_by_person = {person_id: set() for person_id in person_ids}
+    for relationship in family.relationships:
+        if relationship.father_id in people and relationship.mother_id in people:
+            partners_by_person[relationship.father_id].add(relationship.mother_id)
+            partners_by_person[relationship.mother_id].add(relationship.father_id)
+        for parent_id in relationship.parent_ids:
+            if parent_id in people:
+                children_by_parent[parent_id].extend(relationship.child_ids)
+
+    for parent_id, child_ids in children_by_parent.items():
+        children_by_parent[parent_id] = sorted(
+            set(child_ids),
+            key=lambda child_id: order_index.get(child_id, 0),
+        )
+
+    @cache
+    def descendants(person_id: str) -> tuple[str, ...]:
+        found: set[str] = set()
+        for child_id in children_by_parent.get(person_id, ()):
+            if child_id in found:
+                continue
+            found.add(child_id)
+            found.update(descendants(child_id))
+        return tuple(sorted(found, key=lambda child_id: order_index.get(child_id, 0)))
+
+    def summarize_people(
+        target_ids: list[str] | tuple[str, ...] | set[str],
+    ) -> dict[str, int]:
+        ids = list(target_ids)
+        return {
+            "total": len(ids),
+            "affected": sum(
+                affected_status.get(person_id) == "affected" for person_id in ids
+            ),
+            "unaffected": sum(
+                affected_status.get(person_id) == "unaffected" for person_id in ids
+            ),
+            "unknown_status": sum(
+                affected_status.get(person_id) == "unknown" for person_id in ids
+            ),
+            "male": sum(people[person_id].sex == "male" for person_id in ids),
+            "female": sum(people[person_id].sex == "female" for person_id in ids),
+            "unknown_sex": sum(
+                people[person_id].sex not in {"male", "female"} for person_id in ids
+            ),
+        }
+
+    generation_stats: list[dict[str, int]] = []
+    for generation in sorted(set(generations.values())):
+        ids = [
+            person_id
+            for person_id in person_ids
+            if generations.get(person_id) == generation
+        ]
+        stats = summarize_people(ids)
+        stats["generation"] = generation
+        generation_stats.append(stats)
+
+    founder_stats = summarize_people(founder_ids)
+
+    def sibling_ids_for(person_id: str) -> list[str]:
+        father_id, mother_id = parent_map[person_id]
+        sibling_ids: set[str] = set()
+        for parent_id in (father_id, mother_id):
+            if parent_id is None:
+                continue
+            sibling_ids.update(children_by_parent.get(parent_id, ()))
+        sibling_ids.discard(person_id)
+        return sorted(
+            sibling_ids, key=lambda sibling_id: order_index.get(sibling_id, 0)
+        )
+
+    person_summaries: dict[str, dict[str, object]] = {}
+    family_flags: list[dict[str, object]] = []
+    flags_by_person = {person_id: [] for person_id in person_ids}
+
+    def add_flag(
+        *,
+        code: str,
+        severity: str,
+        message: str,
+        person_id: str,
+        related_ids: list[str] | None = None,
+    ) -> None:
+        flag = {
+            "code": code,
+            "severity": severity,
+            "message": message,
+            "person_id": person_id,
+            "related_ids": related_ids or [],
+        }
+        flags_by_person[person_id].append(flag)
+        family_flags.append(flag)
+
+    for person_id in person_ids:
+        father_id, mother_id = parent_map[person_id]
+        parent_ids = [parent_id for parent_id in (father_id, mother_id) if parent_id]
+        sibling_ids = sibling_ids_for(person_id)
+        child_ids = children_by_parent.get(person_id, [])
+        descendant_ids = list(descendants(person_id))
+        partner_ids = sorted(
+            partners_by_person.get(person_id, set()),
+            key=lambda partner_id: order_index.get(partner_id, 0),
+        )
+        first_degree_ids = sorted(
+            set(parent_ids) | set(sibling_ids) | set(child_ids),
+            key=lambda relative_id: order_index.get(relative_id, 0),
+        )
+
+        person_summaries[person_id] = {
+            "partners": partner_ids,
+            "parents": {
+                "ids": parent_ids,
+                **summarize_people(parent_ids),
+            },
+            "siblings": {
+                "ids": sibling_ids,
+                **summarize_people(sibling_ids),
+            },
+            "children": {
+                "ids": child_ids,
+                **summarize_people(child_ids),
+            },
+            "descendants": {
+                "ids": descendant_ids,
+                **summarize_people(descendant_ids),
+            },
+            "first_degree": {
+                "ids": first_degree_ids,
+                **summarize_people(first_degree_ids),
+            },
+        }
+
+        person_status = affected_status.get(person_id)
+        explicit_parent_statuses = [
+            affected_status[parent_id]
+            for parent_id in parent_ids
+            if affected_status.get(parent_id) in {"affected", "unaffected"}
+        ]
+        if (
+            person_status == "affected"
+            and len(parent_ids) == 2
+            and explicit_parent_statuses == ["unaffected", "unaffected"]
+        ):
+            add_flag(
+                code="affected_with_unaffected_parents",
+                severity="warning",
+                message="Affected individual has two recorded unaffected parents.",
+                person_id=person_id,
+                related_ids=parent_ids,
+            )
+        if (
+            person_status == "unaffected"
+            and len(parent_ids) == 2
+            and explicit_parent_statuses == ["affected", "affected"]
+        ):
+            add_flag(
+                code="unaffected_with_affected_parents",
+                severity="warning",
+                message="Unaffected individual has two recorded affected parents.",
+                person_id=person_id,
+                related_ids=parent_ids,
+            )
+        if (
+            person_status == "affected"
+            and parent_ids
+            and not any(
+                affected_status.get(relative_id) == "affected"
+                for relative_id in first_degree_ids
+            )
+        ):
+            add_flag(
+                code="isolated_affected_case",
+                severity="notice",
+                message="Affected individual has no affected first-degree relatives recorded.",
+                person_id=person_id,
+            )
+
+    branch_summaries: list[dict[str, object]] = []
+    for relationship in family.relationships:
+        if relationship.parent_ids and not all(
+            parent_id in founder_id_set for parent_id in relationship.parent_ids
+        ):
+            continue
+        branch_member_ids = set(relationship.parent_ids)
+        branch_descendant_ids: set[str] = set()
+        for child_id in relationship.child_ids:
+            branch_descendant_ids.add(child_id)
+            branch_descendant_ids.update(descendants(child_id))
+        branch_member_ids.update(branch_descendant_ids)
+        member_ids = sorted(
+            branch_member_ids, key=lambda person_id: order_index.get(person_id, 0)
+        )
+        descendant_ids = sorted(
+            branch_descendant_ids,
+            key=lambda person_id: order_index.get(person_id, 0),
+        )
+        label = (
+            " + ".join(relationship.parent_ids)
+            if relationship.parent_ids
+            else relationship.relationship_id
+        )
+        branch_summaries.append(
+            {
+                "label": label,
+                "root_ids": list(relationship.parent_ids),
+                "member_count": len(member_ids),
+                "descendant_count": len(descendant_ids),
+                "affected_count": sum(
+                    affected_status.get(member_id) == "affected"
+                    for member_id in member_ids
+                ),
+                "affected_descendant_count": sum(
+                    affected_status.get(descendant_id) == "affected"
+                    for descendant_id in descendant_ids
+                ),
+            }
+        )
+
+    branch_summaries.sort(
+        key=lambda item: (
+            -int(item["affected_descendant_count"]),
+            -int(item["descendant_count"]),
+            str(item["label"]),
+        )
+    )
+
+    segregation = analyze_family_segregation(family, variant_name=variant_name)
+    if segregation:
+        for err in segregation.get("mendelian_errors", []):
+            flag = {
+                "severity": "warning",
+                "person_id": err["person_id"],
+                "message": f"Mendelian Inconsistency: {err['message']}",
+            }
+            family_flags.append(flag)
+            flags_by_person[err["person_id"]].append(flag)
+        for dn_id in segregation.get("de_novo_ids", []):
+            flag = {
+                "severity": "notice",
+                "person_id": dn_id,
+                "message": "Candidate De Novo variant: mutation observed in child but neither biological parent.",
+            }
+            family_flags.append(flag)
+            flags_by_person[dn_id].append(flag)
+
+    family_flags.sort(
+        key=lambda flag: (
+            {"warning": 0, "notice": 1}.get(str(flag["severity"]), 2),
+            order_index.get(str(flag["person_id"]), 0),
+            str(flag["message"]),
+        )
+    )
+
+    for person_id in person_ids:
+        person_summaries[person_id]["flags"] = flags_by_person[person_id]
+
+    return {
+        "generation_stats": generation_stats,
+        "founder_stats": founder_stats,
+        "branch_summaries": branch_summaries,
+        "family_flags": family_flags,
+        "person_summaries": person_summaries,
+        "segregation": segregation,
+    }