pedview 1.0.0__tar.gz

pedview-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dongkun Lee, and Mark Angier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pedview-1.0.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: pedview
+Version: 1.0.0
+Summary: Command-line pedigree visualization for genetics workflows
+Author: Dongkun Lee, Mark Angier
+License: MIT
+Project-URL: Homepage, https://github.com/DKunLee/Pedview
+Project-URL: Repository, https://github.com/DKunLee/Pedview
+Project-URL: Issues, https://github.com/DKunLee/Pedview/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# pedview
+
+[![PyPI version](https://img.shields.io/pypi/v/pedview.svg)](https://pypi.org/project/pedview/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pedview.svg)](https://pypi.org/project/pedview/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A lightweight command-line tool for visualizing family pedigrees in genetics and clinical research workflows.
+
+`pedview` reads standard pedigree files and generates self-contained, interactive HTML reports with publication-ready SVG diagrams. It has **zero external runtime dependencies** (built purely on Python standard library) and runs completely offline.
+
+---
+
+## Features
+
+- **Zero Runtime Dependencies**: Pure Python standard library (`math`, `html`, `dataclasses`, `pathlib`, `argparse`).
+- **Flexible Input**: Auto-detects standard 6-column PLINK `.fam`/`.ped` files and extended headered pedigree files.
+- **Clinical & Research Attributes**: Visualizes affected status, proband indicators, carriers, deceased status, age labels, and genotype calls.
+- **Layered Graph Engine**: Sugiyama-style layout with barycenter crossing reduction, twin handling, and consanguinity loop routing.
+- **Interactive Standalone HTML**: Produces a single offline HTML report with pan/zoom navigation, individual detail drawer, and search.
+- **Publication Exports**: One-click download for vector SVG, journal-styled SVG, and high-resolution PNG.
+- **Mendelian Quality Control**: Automated parent-child relationship validation and Wright's inbreeding coefficient calculations ($f_a$).
+
+---
+
+## Installation
+
+```bash
+pip install pedview
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/DKunLee/Pedview.git
+cd Pedview
+pip install .
+```
+
+---
+
+## Quickstart
+
+```bash
+# 1. Validate pedigree format, integrity, and relationships
+pedview validate <input.ped>
+
+# 2. Preview family and cohort summaries directly in the terminal
+pedview preview <input.ped>
+
+# 3. Build a standalone interactive HTML report
+pedview build <input.ped> -o <output_report.html>
+
+# 4. Render a single family from a multi-family cohort
+pedview build <input.ped> --family <family_id> -o <family_report.html>
+
+# 5. Highlight a candidate variant and set ancestor inbreeding coefficient
+pedview build <input.ped> --variant-name "<variant_name>" --ancestor-inbreeding 0.02 -o <output_report.html>
+```
+
+---
+
+## Supported Formats
+
+### 1. Standard Headerless PLINK `.fam` / `.ped` (6 Columns)
+```text
+FAM01 101 0   0   1 1
+FAM01 102 0   0   2 1
+FAM01 201 101 102 1 2
+FAM01 202 101 102 2 1
+```
+- **Sex**: `1` = Male, `2` = Female, `0` = Unknown.
+- **Phenotype**: `1` = Unaffected, `2` = Affected, `0` / `-9` = Unknown.
+- **Missing Parents**: `0`, `.`, `-9`, `NA`.
+
+### 2. Headered Extended Pedigree (Tab- or Space-delimited)
+```text
+famid  id   fid  mid  sex  affected    proband  deceased  age  genotype
+FAM01  101  0    0    1    unaffected  0        1         72y  0/0
+FAM01  102  0    0    2    unaffected  0        0         68y  0/1
+FAM01  201  101  102  1    affected    1        0         14y  0/1
+```
+
+Common column header aliases are resolved automatically:
+- **Family**: `famid`, `family_id`, `family`, `pedigree`, `fid`
+- **Individual**: `id`, `iid`, `individual_id`, `sample_id`
+- **Father**: `fid`, `pat`, `pid`, `father`, `father_id`
+- **Mother**: `mid`, `mat`, `mother`, `mother_id`
+- **Sex**: `sex`, `gender`
+- **Phenotype**: `affected`, `phenotype`, `affection`
+
+---
+
+## CLI Reference
+
+| Command | Description | Example |
+| :--- | :--- | :--- |
+| `validate` | Validates file format, parent references, sex codes, and loops | `pedview validate <input.ped>` |
+| `preview` | Prints terminal summary of families, founders, and generations | `pedview preview <input.ped>` |
+| `build` | Generates interactive HTML report | `pedview build <input.ped> -o <output_report.html>` |
+
+### Build Options
+
+- `-o, --output`: Output file path (defaults to `<input>.html`).
+- `--family`: Filter report to a specific family ID (`<family_id>`).
+- `--title`: Custom title for the HTML report (`"<title>"`).
+- `--variant-name`: Candidate variant annotation label (e.g. `"<variant_name>"`).
+- `--ancestor-inbreeding`: Global Wright ancestor inbreeding coefficient ($f_a$). Defaults to `0.0`.
+
+---
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

pedview-1.0.0/README.md

@@ -0,0 +1,113 @@
+# pedview
+
+[![PyPI version](https://img.shields.io/pypi/v/pedview.svg)](https://pypi.org/project/pedview/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pedview.svg)](https://pypi.org/project/pedview/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A lightweight command-line tool for visualizing family pedigrees in genetics and clinical research workflows.
+
+`pedview` reads standard pedigree files and generates self-contained, interactive HTML reports with publication-ready SVG diagrams. It has **zero external runtime dependencies** (built purely on Python standard library) and runs completely offline.
+
+---
+
+## Features
+
+- **Zero Runtime Dependencies**: Pure Python standard library (`math`, `html`, `dataclasses`, `pathlib`, `argparse`).
+- **Flexible Input**: Auto-detects standard 6-column PLINK `.fam`/`.ped` files and extended headered pedigree files.
+- **Clinical & Research Attributes**: Visualizes affected status, proband indicators, carriers, deceased status, age labels, and genotype calls.
+- **Layered Graph Engine**: Sugiyama-style layout with barycenter crossing reduction, twin handling, and consanguinity loop routing.
+- **Interactive Standalone HTML**: Produces a single offline HTML report with pan/zoom navigation, individual detail drawer, and search.
+- **Publication Exports**: One-click download for vector SVG, journal-styled SVG, and high-resolution PNG.
+- **Mendelian Quality Control**: Automated parent-child relationship validation and Wright's inbreeding coefficient calculations ($f_a$).
+
+---
+
+## Installation
+
+```bash
+pip install pedview
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/DKunLee/Pedview.git
+cd Pedview
+pip install .
+```
+
+---
+
+## Quickstart
+
+```bash
+# 1. Validate pedigree format, integrity, and relationships
+pedview validate <input.ped>
+
+# 2. Preview family and cohort summaries directly in the terminal
+pedview preview <input.ped>
+
+# 3. Build a standalone interactive HTML report
+pedview build <input.ped> -o <output_report.html>
+
+# 4. Render a single family from a multi-family cohort
+pedview build <input.ped> --family <family_id> -o <family_report.html>
+
+# 5. Highlight a candidate variant and set ancestor inbreeding coefficient
+pedview build <input.ped> --variant-name "<variant_name>" --ancestor-inbreeding 0.02 -o <output_report.html>
+```
+
+---
+
+## Supported Formats
+
+### 1. Standard Headerless PLINK `.fam` / `.ped` (6 Columns)
+```text
+FAM01 101 0   0   1 1
+FAM01 102 0   0   2 1
+FAM01 201 101 102 1 2
+FAM01 202 101 102 2 1
+```
+- **Sex**: `1` = Male, `2` = Female, `0` = Unknown.
+- **Phenotype**: `1` = Unaffected, `2` = Affected, `0` / `-9` = Unknown.
+- **Missing Parents**: `0`, `.`, `-9`, `NA`.
+
+### 2. Headered Extended Pedigree (Tab- or Space-delimited)
+```text
+famid  id   fid  mid  sex  affected    proband  deceased  age  genotype
+FAM01  101  0    0    1    unaffected  0        1         72y  0/0
+FAM01  102  0    0    2    unaffected  0        0         68y  0/1
+FAM01  201  101  102  1    affected    1        0         14y  0/1
+```
+
+Common column header aliases are resolved automatically:
+- **Family**: `famid`, `family_id`, `family`, `pedigree`, `fid`
+- **Individual**: `id`, `iid`, `individual_id`, `sample_id`
+- **Father**: `fid`, `pat`, `pid`, `father`, `father_id`
+- **Mother**: `mid`, `mat`, `mother`, `mother_id`
+- **Sex**: `sex`, `gender`
+- **Phenotype**: `affected`, `phenotype`, `affection`
+
+---
+
+## CLI Reference
+
+| Command | Description | Example |
+| :--- | :--- | :--- |
+| `validate` | Validates file format, parent references, sex codes, and loops | `pedview validate <input.ped>` |
+| `preview` | Prints terminal summary of families, founders, and generations | `pedview preview <input.ped>` |
+| `build` | Generates interactive HTML report | `pedview build <input.ped> -o <output_report.html>` |
+
+### Build Options
+
+- `-o, --output`: Output file path (defaults to `<input>.html`).
+- `--family`: Filter report to a specific family ID (`<family_id>`).
+- `--title`: Custom title for the HTML report (`"<title>"`).
+- `--variant-name`: Candidate variant annotation label (e.g. `"<variant_name>"`).
+- `--ancestor-inbreeding`: Global Wright ancestor inbreeding coefficient ($f_a$). Defaults to `0.0`.
+
+---
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

pedview-1.0.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pedview"
+version = "1.0.0"
+description = "Command-line pedigree visualization for genetics workflows"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Dongkun Lee" },
+    { name = "Mark Angier" }
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/DKunLee/Pedview"
+Repository = "https://github.com/DKunLee/Pedview"
+Issues = "https://github.com/DKunLee/Pedview/issues"
+
+[project.scripts]
+pedview = "pedview.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

pedview-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pedview-1.0.0/src/pedview/__init__.py

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

pedview-1.0.0/src/pedview/__main__.py

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

pedview-1.0.0/src/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())