telinker 0.1.0__tar.gz

telinker-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Sanborn, Jalees Rehman, Board of Trustees of the University of Illinois.
+
+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.

telinker-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include tests *.py

telinker-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: telinker
+Version: 0.1.0
+Summary: Genotype polymorphic transposable elements from VCF, PLINK, array, BED or BAM/CRAM files
+License-Expression: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Provides-Extra: reads
+Requires-Dist: pysam>=0.19; extra == "reads"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# teLinker
+
+Genotype polymorphic transposable elements in your own data.
+
+```
+pip install telinker                 # numpy is the only dependency
+pip install 'telinker[reads]'        # + pysam, only for BAM/CRAM input
+
+telinker genotype cohort.vcf.gz -o tes.tsv
+```
+
+## Report bugs
+
+https://github.com/jaleesr/teLinker
+
+## Inputs
+
+The input type and genome build are detected automatically. Pass `--build t2t|hg38|hg19`
+if the build information is not present in the file header.
+
+| Input | How TEs are called | `method` |
+|---|---|---|
+| SNP VCF (WGS, or imputed with `DS`) | Imputed from nearby SNPs | `ridge`, `tagN` |
+| PLINK `.bed/.bim/.fam` | Imputed | `ridge`, `tagN` |
+| 23andMe / AncestryDNA raw file (`.txt` or `.zip`) | Imputed (mostly single tags: arrays are sparse) | `tagN`, `ridge` |
+| SV VCF (Sniffles, SVAN, MELT, PAV, …) | Matched to the catalog | `sv` |
+| BED of TE insertion calls | Matched; presence only | `bed` |
+| Long-read BAM/CRAM on T2T-CHM13 | Read directly from indels in the alignments | `reads` |
+| Short-read BAM/CRAM | SNPs piled up, then imputed | `ridge`, `tagN` |
+
+BCF is not read directly; convert it with `bcftools view -Oz`.
+
+### Several samples
+
+**Multi-sample files.** VCF and PLINK inputs give one column per sample. A BAM/CRAM whose
+read groups carry several `SM` tags is split by read group into one column per `SM`
+
+**Several files.** These are merged into one table:
+
+```
+telinker genotype donor1.bam donor2.bam donor3.bam -o cohort.tsv
+telinker genotype cohort.chr*.vcf.gz -o cohort.tsv     # per-chromosome splits
+```
+
+- Every input must be on the same build. 
+- Sample names are matched across files.
+- If two files genotype the same TE in the same sample, the first file wins.
+- Single-sample files (a one-sample BAM, a 23andMe file, a BED) are named after the file,
+  up to the first dot. So `donor1.sorted.bam` becomes `donor1`.
+- If the same sample name comes from more than one file, telinker merges them and warns. That
+  is right for a cohort split by chromosome. If the files are different people rename them.
+
+In long-read mode, chrY pseudoautosomal loci are skipped. Their reads are shared with chrX,
+so a chrY call would just repeat the chrX genotype.
+
+## Output
+
+One TSV. Each row is a TE, and each sample column is a **TE-presence dosage** (0–2):
+
+```
+te_id                   chrom  pos        type  subfamily  method  r2    S1    S2
+10_102771350_INS_306_0  10     103646104  INS   AluYa5     tag1    1.00  0     1
+10_100722374_INS_226_0  10     .          INS   SVA_F      tag1    0.70  0.92  1.78
+```
+
+- **Dosage cells:** dosage always counts copies of the TE, for both INS and DEL loci.
+  Imputed calls are continuous. `.` means the TE could not be called in that sample.
+- **`r2`:** the panel's held-out accuracy for that TE's model. It is empty for direct calls.
+- **`pos`:** the position in your input's build. `.` means the locus does not lift to that build.
+- **`--vcf`:** writes the same calls as a VCF with `GT:DS`, ready for plink2, regenie
+  or tensorQTL. Its ALT allele is `<TE>` (TE present).
+
+
+## Layout
+
+```
+telinker/         the installed package (numpy only; pysam imported lazily for BAM/CRAM)
+  cli.py          argument parsing, input detection, dispatch, summary log
+  inputs.py       format sniffing + readers: VCF (SNPs and SVs), PLINK, 23andMe/Ancestry, BED
+  impute.py       allele matching and the linear-model prediction / fallback
+  match.py        SV and BED calls -> catalog loci
+  reads.py        BAM/CRAM: long-read CIGAR genotyper, short-read SNP pileup
+  output.py       TSV and VCF writers
+  panel.py        loads telinker/panel/ (loci.tsv.gz, models.tsv.gz, PANEL.md)
+tests/            pytest suite on a hand-built four-TE panel
+```
+
+## Tests
+
+```
+pip install '.[test,reads]'
+pytest tests
+```

telinker-0.1.0/README.md

@@ -0,0 +1,93 @@
+# teLinker
+
+Genotype polymorphic transposable elements in your own data.
+
+```
+pip install telinker                 # numpy is the only dependency
+pip install 'telinker[reads]'        # + pysam, only for BAM/CRAM input
+
+telinker genotype cohort.vcf.gz -o tes.tsv
+```
+
+## Report bugs
+
+https://github.com/jaleesr/teLinker
+
+## Inputs
+
+The input type and genome build are detected automatically. Pass `--build t2t|hg38|hg19`
+if the build information is not present in the file header.
+
+| Input | How TEs are called | `method` |
+|---|---|---|
+| SNP VCF (WGS, or imputed with `DS`) | Imputed from nearby SNPs | `ridge`, `tagN` |
+| PLINK `.bed/.bim/.fam` | Imputed | `ridge`, `tagN` |
+| 23andMe / AncestryDNA raw file (`.txt` or `.zip`) | Imputed (mostly single tags: arrays are sparse) | `tagN`, `ridge` |
+| SV VCF (Sniffles, SVAN, MELT, PAV, …) | Matched to the catalog | `sv` |
+| BED of TE insertion calls | Matched; presence only | `bed` |
+| Long-read BAM/CRAM on T2T-CHM13 | Read directly from indels in the alignments | `reads` |
+| Short-read BAM/CRAM | SNPs piled up, then imputed | `ridge`, `tagN` |
+
+BCF is not read directly; convert it with `bcftools view -Oz`.
+
+### Several samples
+
+**Multi-sample files.** VCF and PLINK inputs give one column per sample. A BAM/CRAM whose
+read groups carry several `SM` tags is split by read group into one column per `SM`
+
+**Several files.** These are merged into one table:
+
+```
+telinker genotype donor1.bam donor2.bam donor3.bam -o cohort.tsv
+telinker genotype cohort.chr*.vcf.gz -o cohort.tsv     # per-chromosome splits
+```
+
+- Every input must be on the same build. 
+- Sample names are matched across files.
+- If two files genotype the same TE in the same sample, the first file wins.
+- Single-sample files (a one-sample BAM, a 23andMe file, a BED) are named after the file,
+  up to the first dot. So `donor1.sorted.bam` becomes `donor1`.
+- If the same sample name comes from more than one file, telinker merges them and warns. That
+  is right for a cohort split by chromosome. If the files are different people rename them.
+
+In long-read mode, chrY pseudoautosomal loci are skipped. Their reads are shared with chrX,
+so a chrY call would just repeat the chrX genotype.
+
+## Output
+
+One TSV. Each row is a TE, and each sample column is a **TE-presence dosage** (0–2):
+
+```
+te_id                   chrom  pos        type  subfamily  method  r2    S1    S2
+10_102771350_INS_306_0  10     103646104  INS   AluYa5     tag1    1.00  0     1
+10_100722374_INS_226_0  10     .          INS   SVA_F      tag1    0.70  0.92  1.78
+```
+
+- **Dosage cells:** dosage always counts copies of the TE, for both INS and DEL loci.
+  Imputed calls are continuous. `.` means the TE could not be called in that sample.
+- **`r2`:** the panel's held-out accuracy for that TE's model. It is empty for direct calls.
+- **`pos`:** the position in your input's build. `.` means the locus does not lift to that build.
+- **`--vcf`:** writes the same calls as a VCF with `GT:DS`, ready for plink2, regenie
+  or tensorQTL. Its ALT allele is `<TE>` (TE present).
+
+
+## Layout
+
+```
+telinker/         the installed package (numpy only; pysam imported lazily for BAM/CRAM)
+  cli.py          argument parsing, input detection, dispatch, summary log
+  inputs.py       format sniffing + readers: VCF (SNPs and SVs), PLINK, 23andMe/Ancestry, BED
+  impute.py       allele matching and the linear-model prediction / fallback
+  match.py        SV and BED calls -> catalog loci
+  reads.py        BAM/CRAM: long-read CIGAR genotyper, short-read SNP pileup
+  output.py       TSV and VCF writers
+  panel.py        loads telinker/panel/ (loci.tsv.gz, models.tsv.gz, PANEL.md)
+tests/            pytest suite on a hand-built four-TE panel
+```
+
+## Tests
+
+```
+pip install '.[test,reads]'
+pytest tests
+```

telinker-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "telinker"
+version = "0.1.0"
+description = "Genotype polymorphic transposable elements from VCF, PLINK, array, BED or BAM/CRAM files"
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["numpy>=1.20"]
+
+[project.optional-dependencies]
+reads = ["pysam>=0.19"]
+test = ["pytest"]
+
+[project.scripts]
+telinker = "telinker.cli:main"
+
+[tool.setuptools]
+packages = ["telinker", "telinker.panel"]
+
+[tool.setuptools.package-data]
+"telinker.panel" = ["*.gz", "*.md"]

telinker-0.1.0/setup.cfg

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

telinker-0.1.0/telinker/__init__.py

@@ -0,0 +1,7 @@
+import sys
+
+__version__ = "0.1.0"
+
+
+def log(msg):
+    print(f"[telinker] {msg}", file=sys.stderr)

telinker-0.1.0/telinker/__main__.py

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

telinker-0.1.0/telinker/cli.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+import argparse
+import sys
+from collections import Counter
+
+import numpy as np
+
+from . import __version__, log
+from .impute import impute
+from .inputs import read_bed, read_plink, read_raw, read_vcf, sample_name, sniff
+from .match import match
+from .output import PRESENT, write_tsv, write_vcf
+from .panel import BUILDS, PANEL_DIR, load_panel
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        prog="telinker", description="Genotype polymorphic TEs from VCF, PLINK, array, BED "
+                                    "or BAM/CRAM files.")
+    ap.add_argument("--version", action="version", version=__version__)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    g = sub.add_parser("genotype", help="genotype catalog polyTEs")
+    g.add_argument("input", nargs="+",
+                   help="VCF, PLINK prefix, 23andMe/Ancestry file, BED of TE calls or BAM/CRAM; "
+                        "several inputs are merged by sample name")
+    g.add_argument("-o", "--out", help="output file (default: stdout)")
+    g.add_argument("--build", choices=("auto",) + BUILDS, default="auto",
+                   help="genome build of the inputs (default: from the header)")
+    g.add_argument("--min-r2", type=float, default=0.5,
+                   help="minimum model cv r2 for imputed TEs (default: 0.5)")
+    g.add_argument("--model", choices=("mixed", "ridge", "tag"), default="mixed",
+                   help="imputation model: best available (default), ridge only, or single tag SNP")
+    g.add_argument("--vcf", action="store_true", help="write VCF (GT:DS) instead of TSV")
+    g.add_argument("--reference", help="reference FASTA for CRAM")
+    g.add_argument("--include-del-contractions", action="store_true",
+                   help="also report DEL loci that are in-element contractions")
+
+    sub.add_parser("info", help="show the reference panel summary")
+    a = ap.parse_args(argv)
+
+    if a.cmd == "info":
+        print((PANEL_DIR / "PANEL.md").read_text(), end="")
+        return
+    genotype(a)
+
+
+def genotype(a):
+    jobs = [inspect(path, a.reference) for path in a.input]
+    build = pick_build(jobs, a.build)
+    for j in jobs:
+        j["direct"] = j["kind"] in ("vcf_sv", "bed") or \
+            (j["kind"] == "reads" and j["long"] and build == "t2t")
+    panel = load_panel(build, models=not all(j["direct"] for j in jobs))
+
+    results = []
+    for j in jobs:
+        if len(jobs) > 1:
+            log(f"--- {j['path']}")
+        results.append(run(j, panel, a))
+    samples, calls, clashes, disagree = merge(results)
+    shared = [s for s, n in Counter(s for names, _ in results for s in set(names)).items() if n > 1]
+    if shared:
+        log(f"merged {len(shared):,} sample name(s) found in more than one input "
+            f"(e.g. {', '.join(shared[:3])}); rename files that hold different people")
+    if clashes:
+        log(f"{clashes:,} genotypes called by more than one input ({disagree:,} disagreed); "
+            "kept the first")
+
+    stats = Counter()
+    if not a.include_del_contractions:
+        keep = [c for c in calls if panel.loci["del_ok"][c[0]]]
+        skipped = len(calls) - len(keep)
+        calls = keep
+    if a.vcf:
+        placed = [c for c in calls if panel.te_pos()[c[0]] > 0]
+        if len(placed) < len(calls):
+            log(f"{len(calls) - len(placed):,} TEs have no {build} position; left out of the VCF")
+        calls = placed
+    stats.update(m.rstrip("0123456789") for c in calls for m in c[1].split(","))
+
+    out = open(a.out, "w") if a.out else sys.stdout
+    (write_vcf if a.vcf else write_tsv)(out, panel, samples, calls)
+    if a.out:
+        out.close()
+    log(f"{len(calls):,} TEs written for {len(samples):,} sample(s) ("
+        + ", ".join(f"{k} {v:,}" for k, v in stats.most_common()) + ")")
+    if not a.include_del_contractions and skipped:
+        log(f"{skipped:,} DEL contractions skipped (--include-del-contractions to keep)")
+
+
+def inspect(path, reference):
+    kind, build = sniff(path)
+    job = dict(path=path, kind=kind, build=build, long=False)
+    if kind == "reads":
+        from . import reads
+        with reads.open_bam(path, reference) as bam:
+            job["samples"], job["rg"], job["build"], job["long"] = reads.describe(bam, path)
+    return job
+
+
+def pick_build(jobs, forced):
+    if forced != "auto":
+        clash = [j for j in jobs if j["build"] not in (None, forced)]
+        if clash:
+            sys.exit(f"--build {forced} conflicts with the header of " + ", ".join(
+                f"{j['path']} ({j['build']})" for j in clash))
+        log(f"build {forced}")
+        return forced
+    for j in jobs:
+        if j["build"] is None and j["kind"] == "raw":
+            j["build"] = "hg19"
+            log(f"{j['path']}: no build in header, assuming hg19")
+    unknown = [j["path"] for j in jobs if j["build"] is None]
+    if unknown:
+        sys.exit(f"Unknown genome build for {', '.join(unknown)}; pass --build t2t|hg38|hg19")
+    builds = {j["build"] for j in jobs}
+    if len(builds) > 1:
+        sys.exit("Inputs are on different builds: " + ", ".join(
+            f"{j['path']} ({j['build']})" for j in jobs))
+    build = builds.pop()
+    log(f"build {build}")
+    return build
+
+
+def run(j, panel, a):
+    log(f"input: {j['kind']}")
+    kind, path, calls = j["kind"], j["path"], []
+    if kind == "bed":
+        samples, svs = [sample_name(path)], read_bed(path)
+        calls = matched(panel, svs, np.full((len(svs), 1), PRESENT), "bed")
+    elif kind in ("vcf_snp", "vcf_sv"):
+        samples, G, svs, dose = read_vcf(path, panel)
+        if svs or j["direct"]:
+            calls = matched(panel, svs, dose, "sv")
+    elif kind == "reads":
+        from . import reads
+        samples = j["samples"]
+        with reads.open_bam(path, a.reference) as bam:
+            if j["direct"]:
+                log("long reads: genotyping from CIGAR indels")
+                rows = [i for i in range(len(panel))
+                        if not reads.in_chry_par(panel.loci["chrom"][i], panel.loci["pos"][i])]
+                log(f"{len(panel) - len(rows):,} chrY PAR loci skipped (called on chrX)")
+                res = reads.genotype_long(bam, panel, rows, samples, j["rg"])
+                calls = [(i, "reads", None, d) for i, d in res.items()]
+            else:
+                log("pileup at panel SNPs, then imputing")
+                G = reads.pileup_sites(bam, panel, samples, j["rg"])
+    else:
+        samples, G = {"plink": read_plink, "raw": read_raw}[kind](path, panel)
+    if not j["direct"]:
+        log(f"{len(G):,} of {len(panel.sites):,} panel SNPs found")
+        done = {c[0] for c in calls}
+        res = impute(panel, G, len(samples), a.min_r2, a.model)
+        calls += [(i, *r) for i, r in res.items() if i not in done]
+    return samples, calls
+
+
+def matched(panel, svs, dose, method):
+    pairs = match(panel, svs)
+    log(f"{len(pairs):,} of {len(svs):,} input calls matched a catalog TE")
+    return [(i, method, None, dose[k]) for k, i in pairs]
+
+
+def merge(results):
+    if len(results) == 1:
+        samples, calls = results[0]
+        return samples, sorted(calls, key=lambda c: c[0]), 0, 0
+    samples = list(dict.fromkeys(s for names, _ in results for s in names))
+    col = {s: k for k, s in enumerate(samples)}
+    rows, clashes, disagree = {}, 0, 0
+    for names, calls in results:
+        idx = np.array([col[s] for s in names])
+        for i, method, r2, doses in calls:
+            methods, r2s, d = rows.setdefault(i, ([], [], np.full(len(samples), np.nan)))
+            methods += [m for m in method.split(",") if m not in methods]
+            if r2 is not None:
+                r2s.append(r2)
+            have, new = ~np.isnan(d[idx]), ~np.isnan(doses)
+            both = have & new
+            clashes += both.sum()
+            disagree += (d[idx[both]] != doses[both]).sum()
+            d[idx[new & ~have]] = doses[new & ~have]
+    calls = [(i, ",".join(m), min(r) if r else None, d) for i, (m, r, d) in sorted(rows.items())]
+    return samples, calls, clashes, disagree
+
+
+if __name__ == "__main__":
+    main()

telinker-0.1.0/telinker/impute.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+from itertools import groupby
+
+import numpy as np
+
+COMPLEMENT = str.maketrans("ACGT", "TGCA")
+MIN_OBSERVED = 0.8
+
+
+def orient(ref, alt, panel_ref, panel_alt):
+    for r, a in ((ref, alt), (ref.translate(COMPLEMENT), alt.translate(COMPLEMENT))):
+        if (r, a) == (panel_ref, panel_alt):
+            return 1
+        if (r, a) == (panel_alt, panel_ref):
+            return -1
+        if is_palindromic(panel_ref, panel_alt):
+            return 0
+    return 0
+
+
+def is_palindromic(ref, alt):
+    return {ref, alt} in ({"A", "T"}, {"C", "G"})
+
+
+def impute(panel, G, n_samples, min_r2=0.5, kind="mixed"):
+    out = {}
+    for te, models in groupby(panel.models, key=lambda m: m.te):
+        dose, used = np.full(n_samples, np.nan), []
+        for m in models:
+            if m.cv_r2 < min_r2:
+                break
+            if kind != "mixed" and (m.name == "ridge") != (kind == "ridge"):
+                continue
+            ok = [s in G for s in m.sites]
+            need = MIN_OBSERVED if m.name == "ridge" else 1.0
+            if np.mean(ok) < need:
+                continue
+            X = np.full((len(m.sites), n_samples), np.nan)
+            for j in np.flatnonzero(ok):
+                X[j] = G[m.sites[j]]
+            fill = np.isnan(dose) & ((~np.isnan(X)).mean(0) >= need)
+            if not fill.any():
+                continue
+            X = np.where(np.isnan(X), m.means[:, None], X)
+            dose[fill] = np.clip(m.intercept + m.weights @ X[:, fill], 0, 2)
+            used.append(m)
+            if not np.isnan(dose).any():
+                break
+        if used:
+            out[te] = (",".join(m.name for m in used), min(m.cv_r2 for m in used), dose)
+    return out