kinship-vis 0.1.2

Kinship graph visualizer for PLINK .genome and KING .kin0 with PNG/TIFF and interactive HTML outputs

kinship-vis

Visualize pairwise kinship from PLINK .genome or KING .kin0 as connected components, with

• Static images (PNG/TIFF/JPEG, Matplotlib): edges colored by relationship class, nodes filled by MT haplogroup and outlined by Y haplogroup.
• Interactive HTML (Plotly): the same color scheme with hover tooltips and an optional legend.

Designed for quick QC and teaching. Works with projects like 1000 Genomes and your own pipelines (PLINK/KING).

---

Installation

1) PyPI (recommended)

pip install kinship-vis

2) From GitHub (latest main)

pip install "git+https://github.com/YOUR_GITHUB_USERNAME/kinship-vis.git"

Python/NumPy note: until the scientific Python stack fully supports NumPy 2, this package pins numpy<2 to avoid ABI issues.

---

Command-line usage

Basic help:

kinship-vis -h

Key inputs:

• Pairs table: PLINK .genome (IID1 IID2 PI_HAT [Z1]) or KING .kin0 (ID1 ID2 Kinship).
• Haplogroups (optional): two-column text files without header: <sample><tab><haplogroup>
  • --haplogroup-Y — Y haplogroups (node border color)
  • --haplogroup-MT — MT haplogroups (node fill color)
• Samplesheet (optional): TSV/CSV/whitespace-delimited, must contain sample_id; you can select a label column via --label-col.

Important thresholds (defaults):

• --threshold1 0.75 (close relatives)
• --threshold2 0.40 (distant relatives)
• --z1-threshold 0.75
• --drop-below-threshold2 — drop edges with PI_HAT<threshold2 to reduce noise.

Outputs:

• Static PNG/TIFF/JPEG: <prefix>_component_<N>.<ext>
• Interactive HTML: <prefix>_component_<N>.html

---

Examples (using the files in examples/)

KING .kin0 → separate output folder:

kinship-vis G1000_31S.kin0   --haplogroup-Y  G1000_31S_chrY.hapresult.hg   --haplogroup-MT G1000_31S_chrMT_haplogrep.txt   --output kin0/kinship --legend --drop-below-threshold2

PLINK .genome → separate output folder:

kinship-vis G1000_31S.genome   --haplogroup-Y  G1000_31S_chrY.hapresult.hg   --haplogroup-MT G1000_31S_chrMT_haplogrep.txt   --output genome/kinship --legend --drop-below-threshold2

Tip: pre-create the output directories if needed:

mkdir -p kin0 genome

---

Minimal, reproducible example

# Create a tiny demo of two related pairs
cat > demo.genome <<EOF
IID1 IID2 PI_HAT Z1
A    B    0.90   0.95
A    C    0.45   0.80
D    E    0.10   0.00
EOF

echo -e "A	R1a" > y.tsv
echo -e "B	R1a" >> y.tsv
echo -e "A	H"   > mt.tsv
echo -e "B	H"   >> mt.tsv

kinship-vis demo.genome --haplogroup-Y y.tsv --haplogroup-MT mt.tsv --output demo/out --legend

---

API (Python)

import pandas as pd
from kinship_vis.io import read_pairs_table
from kinship_vis.graph import build_graph

df = read_pairs_table("your.genome")        # or .kin0
G = build_graph(df, threshold1=0.75)

---

Citation

• PLINK: Purcell et al. (2007) Am J Hum Genet.
• KING: Manichaikul et al. (2010) Bioinformatics.

License

MIT