ldetect-lite 0.1.0__py3-none-any.whl

ldetect_lite/__init__.py

@@ -0,0 +1,8 @@
+"""ldetect-lite: approximately independent LD blocks in the human genome."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("ldetect-lite")
+except PackageNotFoundError:
+    __version__ = "unknown"

ldetect_lite/_cli/cmd_covariance.py

@@ -0,0 +1,75 @@
+"""CLI: calc-covariance subcommand."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:  # type: ignore[type-arg]
+    p = subparsers.add_parser(
+        "calc-covariance",
+        help="Compute Wen/Stephens shrinkage LD from a VCF stream (reads stdin).",
+    )
+    p.add_argument(
+        "--genetic-map",
+        required=True,
+        type=Path,
+        metavar="PATH",
+        help="Gzipped genetic map (chr, position, cM).",
+    )
+    p.add_argument(
+        "--individuals",
+        required=True,
+        type=Path,
+        metavar="PATH",
+        help="Plain-text file; one individual ID per line.",
+    )
+    p.add_argument(
+        "--output",
+        required=True,
+        type=Path,
+        metavar="PATH",
+        help="Gzipped 8-column covariance output file.",
+    )
+    p.add_argument(
+        "--ne",
+        type=float,
+        default=11418.0,
+        metavar="FLOAT",
+        help="Effective population size (default: 11418.0).",
+    )
+    p.add_argument(
+        "--cutoff",
+        type=float,
+        default=1e-7,
+        metavar="FLOAT",
+        help="LD cutoff; pairs below this are not written (default: 1e-7).",
+    )
+    p.add_argument(
+        "--covariance-compression",
+        choices=("lzf", "zstd"),
+        default="zstd",
+        help=(
+            "HDF5 compression codec for the covariance partition. 'zstd' is "
+            "smaller and faster to read/write than 'lzf' at equal precision "
+            "(default: zstd)."
+        ),
+    )
+    p.set_defaults(func=_run)
+
+
+def _run(args: argparse.Namespace) -> int:
+    from ldetect_lite.shrinkage import calc_covariance
+
+    calc_covariance(
+        vcf_stream=sys.stdin,
+        genetic_map_path=args.genetic_map,
+        individuals_path=args.individuals,
+        output_path=args.output,
+        ne=args.ne,
+        cutoff=args.cutoff,
+        compression=args.covariance_compression,
+    )
+    return 0

ldetect_lite/_cli/cmd_covariance_summary.py

@@ -0,0 +1,95 @@
+"""CLI: covariance-summary subcommand."""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+from io import StringIO
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:  # type: ignore[type-arg]
+    p = subparsers.add_parser(
+        "covariance-summary",
+        help="Estimate covariance array memory from partition row counts.",
+    )
+    p.add_argument(
+        "--dataset-path",
+        required=True,
+        type=Path,
+        metavar="PATH",
+        help="Root directory of the covariance matrix dataset.",
+    )
+    p.add_argument(
+        "--name",
+        required=True,
+        metavar="TEXT",
+        help="Chromosome name (e.g. chr2).",
+    )
+    p.add_argument(
+        "--snp-first",
+        type=int,
+        default=-1,
+        metavar="INT",
+        help="First SNP position (auto-detected if omitted).",
+    )
+    p.add_argument(
+        "--snp-last",
+        type=int,
+        default=-1,
+        metavar="INT",
+        help="Last SNP position (auto-detected if omitted).",
+    )
+    p.add_argument(
+        "--output",
+        type=Path,
+        default=None,
+        metavar="PATH",
+        help="Write summary to a file instead of stdout.",
+    )
+    p.add_argument(
+        "--format",
+        choices=["tsv", "json"],
+        default="tsv",
+        help="Output format (default: tsv).",
+    )
+    p.set_defaults(func=_run)
+
+
+def _run(args: argparse.Namespace) -> int:
+    from ldetect_lite._util.covariance_summary import (
+        SUMMARY_COLUMNS,
+        summarize_covariance,
+    )
+    from ldetect_lite.io.partitions import CovarianceStore
+
+    store = CovarianceStore(root=args.dataset_path)
+    partitions, total = summarize_covariance(
+        args.name,
+        store,
+        snp_first=args.snp_first,
+        snp_last=args.snp_last,
+    )
+    rows = [summary.as_dict() for summary in partitions]
+    rows.append(total.as_dict())
+
+    if args.format == "json":
+        text = json.dumps({"partitions": rows[:-1], "total": rows[-1]}, indent=2)
+    else:
+        text = _format_tsv(rows, SUMMARY_COLUMNS)
+
+    if args.output is None:
+        print(text)
+    else:
+        args.output.parent.mkdir(parents=True, exist_ok=True)
+        args.output.write_text(text + "\n")
+    return 0
+
+
+def _format_tsv(rows: list[dict[str, str | int | float]], columns: list[str]) -> str:
+    buffer = StringIO()
+    writer = csv.DictWriter(buffer, fieldnames=columns, delimiter="\t")
+    writer.writeheader()
+    writer.writerows(rows)
+    return buffer.getvalue().rstrip("\n")

ldetect_lite/_cli/cmd_extract_bpoints.py

@@ -0,0 +1,70 @@
+"""CLI: extract-bpoints subcommand."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+_VALID_SUBSETS = ("fourier", "fourier_ls", "uniform", "uniform_ls")
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:  # type: ignore[type-arg]
+    p = subparsers.add_parser(
+        "extract-bpoints",
+        help="Extract breakpoints from a find-minima JSON file and write a BED file.",
+    )
+    p.add_argument(
+        "--name", required=True, metavar="TEXT", help="Chromosome name (e.g. chr2)."
+    )
+    p.add_argument(
+        "--dataset-path",
+        required=True,
+        type=Path,
+        metavar="PATH",
+        help="Root directory of the covariance matrix dataset.",
+    )
+    p.add_argument(
+        "--breakpoints",
+        required=True,
+        type=Path,
+        metavar="PATH",
+        help="JSON file from find-minima.",
+    )
+    p.add_argument(
+        "--subset",
+        required=True,
+        choices=_VALID_SUBSETS,
+        metavar="SUBSET",
+        help=f"Breakpoint set to extract: {{{', '.join(_VALID_SUBSETS)}}}.",
+    )
+    p.add_argument(
+        "--output",
+        type=Path,
+        default=None,
+        metavar="PATH",
+        help="Output BED file (default: stdout).",
+    )
+    p.set_defaults(func=_run)
+
+
+def _run(args: argparse.Namespace) -> int:
+    from ldetect_lite.io.bed import write_bed
+    from ldetect_lite.io.partitions import CovarianceStore, read_partitions
+
+    store = CovarianceStore(root=args.dataset_path)
+    partitions = read_partitions(args.name, store)
+    snp_first = partitions[0][0]
+    snp_last = partitions[-1][1]
+
+    data = json.loads(args.breakpoints.read_text())
+    loci: list[int] = data[args.subset]["loci"]
+
+    write_bed(
+        name=args.name,
+        loci=loci,
+        snp_first=snp_first,
+        snp_last=snp_last,
+        output=args.output,
+    )
+    return 0

ldetect_lite/_cli/cmd_find_minima.py

@@ -0,0 +1,150 @@
+"""CLI: find-minima subcommand."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+_VALID_SUBSETS = ("fourier", "fourier_ls", "uniform", "uniform_ls")
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:  # type: ignore[type-arg]
+    p = subparsers.add_parser(
+        "find-minima",
+        help="Detect LD block breakpoints via Hanning filter + local search.",
+    )
+    p.add_argument(
+        "--input",
+        required=True,
+        type=Path,
+        metavar="PATH",
+        help="Gzipped vector file from matrix-to-vector.",
+    )
+    p.add_argument(
+        "--chr-name", required=True, metavar="TEXT", help="Chromosome name (e.g. chr2)."
+    )
+    p.add_argument(
+        "--dataset-path",
+        required=True,
+        type=Path,
+        metavar="PATH",
+        help="Root directory of the covariance matrix dataset.",
+    )
+    p.add_argument(
+        "--n-snps-bw-bpoints",
+        required=True,
+        type=int,
+        metavar="N",
+        help="Target mean SNPs between breakpoints (default: 10000).",
+    )
+    p.add_argument(
+        "--output", required=True, type=Path, metavar="PATH", help="JSON output file."
+    )
+    p.add_argument(
+        "--snp-first",
+        type=int,
+        default=-1,
+        metavar="INT",
+        help="First SNP position (auto-detected if omitted).",
+    )
+    p.add_argument(
+        "--snp-last",
+        type=int,
+        default=-1,
+        metavar="INT",
+        help="Last SNP position (auto-detected if omitted).",
+    )
+    p.add_argument(
+        "--trackback-delta",
+        type=int,
+        default=200,
+        metavar="INT",
+        help="Coarse trackback search range (default: 200).",
+    )
+    p.add_argument(
+        "--trackback-step",
+        type=int,
+        default=20,
+        metavar="INT",
+        help="Coarse trackback step size (default: 20).",
+    )
+    p.add_argument(
+        "--init-search-loc",
+        type=int,
+        default=1000,
+        metavar="INT",
+        help="Starting width for exponential search (default: 1000).",
+    )
+    p.add_argument(
+        "--workers",
+        type=int,
+        default=1,
+        metavar="N",
+        help=(
+            "Parallel workers for local search. Higher values may multiply "
+            "memory use because each worker loads its own covariance window "
+            "(default: 1)."
+        ),
+    )
+    p.add_argument(
+        "--metric-workers",
+        type=int,
+        default=None,
+        metavar="N",
+        help=(
+            "Parallel workers for streaming metric row passes "
+            "(default: inherit --workers)."
+        ),
+    )
+    p.add_argument(
+        "--high-precision",
+        action="store_true",
+        help="Use 50-digit Decimal arithmetic for local search (slower).",
+    )
+    p.add_argument(
+        "--n-bpoints",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Direct target breakpoint count (overrides --n-snps-bw-bpoints).",
+    )
+    p.add_argument(
+        "--subset",
+        choices=_VALID_SUBSETS,
+        action="append",
+        default=None,
+        metavar="SUBSET",
+        help=(
+            "Breakpoint subset to compute. Repeat to compute multiple subsets. "
+            "By default, all subsets are computed for backward compatibility."
+        ),
+    )
+    p.set_defaults(func=_run)
+
+
+def _run(args: argparse.Namespace) -> int:
+    from ldetect_lite._cli.cmd_run import _resolve_workers
+    from ldetect_lite.io.partitions import CovarianceStore
+    from ldetect_lite.pipeline import find_breakpoints
+
+    metric_workers = _resolve_workers(args.metric_workers, args.workers)
+
+    store = CovarianceStore(root=args.dataset_path)
+    find_breakpoints(
+        input_path=args.input,
+        chr_name=args.chr_name,
+        store=store,
+        n_snps_bw_bpoints=args.n_snps_bw_bpoints,
+        output_path=args.output,
+        snp_first=args.snp_first,
+        snp_last=args.snp_last,
+        trackback_delta=args.trackback_delta,
+        trackback_step=args.trackback_step,
+        init_search_location=args.init_search_loc,
+        workers=args.workers,
+        metric_workers=metric_workers,
+        use_decimal=args.high_precision,
+        n_bpoints=args.n_bpoints,
+        subsets=set(args.subset) if args.subset else None,
+    )
+    return 0

ldetect_lite/_cli/cmd_interpolate_maps.py

@@ -0,0 +1,61 @@
+"""CLI: interpolate-maps subcommand."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:  # type: ignore[type-arg]
+    p = subparsers.add_parser(
+        "interpolate-maps",
+        help="Interpolate genetic map positions onto SNP physical positions.",
+    )
+    p.add_argument(
+        "--snp-file",
+        required=True,
+        type=Path,
+        metavar="PATH",
+        help="BED file of SNP positions (columns: chrom start end rs_id).",
+    )
+    p.add_argument(
+        "--genetic-map",
+        required=True,
+        type=Path,
+        metavar="PATH",
+        help="Gzipped recombination map (position, rate, cM).",
+    )
+    p.add_argument(
+        "--output",
+        required=True,
+        type=Path,
+        metavar="PATH",
+        help="Gzipped output file (rs_id, position, genetic_position).",
+    )
+    p.add_argument(
+        "--mode",
+        choices=("point", "interval"),
+        default="point",
+        help=(
+            "Interpolation algorithm. 'point' (default) treats the map as "
+            "discrete points and interpolates between the two bracketing "
+            "points. 'interval' treats each map row as the start of a "
+            "genomic interval with its own recombination rate, matching "
+            "MacDonald et al.'s R interpolation scripts — use this for "
+            "interval-rate maps such as the deCODE map converted by "
+            "convert_decode_map.py."
+        ),
+    )
+    p.set_defaults(func=_run)
+
+
+def _run(args: argparse.Namespace) -> int:
+    from ldetect_lite.interpolate_maps import interpolate, interpolate_intervals
+
+    fn = interpolate if args.mode == "point" else interpolate_intervals
+    fn(
+        snp_file=args.snp_file,
+        genetic_map=args.genetic_map,
+        output=args.output,
+    )
+    return 0

ldetect_lite/_cli/cmd_matrix_to_vector.py

@@ -0,0 +1,95 @@
+"""CLI: matrix-to-vector subcommand."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:  # type: ignore[type-arg]
+    p = subparsers.add_parser(
+        "matrix-to-vector",
+        help="Convert covariance matrix partitions to a correlation-sum vector.",
+    )
+    p.add_argument(
+        "--dataset-path",
+        required=True,
+        type=Path,
+        metavar="PATH",
+        help="Root directory of the covariance matrix dataset.",
+    )
+    p.add_argument(
+        "--name", required=True, metavar="TEXT", help="Chromosome name (e.g. chr2)."
+    )
+    p.add_argument(
+        "--output",
+        required=True,
+        type=Path,
+        metavar="PATH",
+        help="Gzipped output vector file (position, corr_sum).",
+    )
+    p.add_argument(
+        "--snp-first",
+        type=int,
+        default=-1,
+        metavar="INT",
+        help="First SNP position (auto-detected if omitted).",
+    )
+    p.add_argument(
+        "--snp-last",
+        type=int,
+        default=-1,
+        metavar="INT",
+        help="Last SNP position (auto-detected if omitted).",
+    )
+    p.add_argument(
+        "--mode",
+        choices=["diag", "vert"],
+        default="diag",
+        help="Calculation mode (default: diag).",
+    )
+    p.add_argument(
+        "--generate-heatmap",
+        action="store_true",
+        help="Write a PNG heatmap alongside the output file.",
+    )
+    p.add_argument(
+        "--workers",
+        type=int,
+        default=1,
+        metavar="N",
+        help=(
+            "Parallel workers for HDF5 matrix-to-vector partition computation "
+            "(default: 1)."
+        ),
+    )
+    p.set_defaults(func=_run)
+
+
+def _run(args: argparse.Namespace) -> int:
+    from ldetect_lite.io.partitions import CovarianceStore
+    from ldetect_lite.matrix_analysis import MatrixAnalysis
+
+    store = CovarianceStore(root=args.dataset_path)
+    analysis = MatrixAnalysis(
+        name=args.name,
+        store=store,
+        snp_first=args.snp_first,
+        snp_last=args.snp_last,
+    )
+
+    if args.mode == "diag":
+        if args.generate_heatmap:
+            # Full matrix needed for heatmap — use non-lean path
+            analysis.calc_diag()
+            analysis.write_output_to_file(args.output)
+        else:
+            analysis.calc_diag_lean(args.output, matrix_workers=args.workers)
+    else:
+        raise NotImplementedError("vert mode is deprecated; use diag")
+
+    if args.generate_heatmap:
+        img_path = args.output.with_suffix(".png")
+        analysis.generate_img(img_path)
+
+    return 0

ldetect_lite/_cli/cmd_partition.py

@@ -0,0 +1,70 @@
+"""CLI: partition-chromosome subcommand."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:  # type: ignore[type-arg]
+    p = subparsers.add_parser(
+        "partition-chromosome",
+        help="Split a chromosome into overlapping windows using a genetic map.",
+    )
+    p.add_argument(
+        "--genetic-map",
+        required=True,
+        type=Path,
+        metavar="PATH",
+        help="Gzipped genetic map (chr, position, cM).",
+    )
+    p.add_argument(
+        "--n-individuals",
+        required=True,
+        type=int,
+        metavar="N",
+        help="Number of individuals in the reference panel.",
+    )
+    p.add_argument(
+        "--output",
+        required=True,
+        type=Path,
+        metavar="PATH",
+        help="Output partition file (space-delimited start/end pairs).",
+    )
+    p.add_argument(
+        "--window-size",
+        type=int,
+        default=5000,
+        metavar="N",
+        help="Target SNPs per partition window (default: 5000).",
+    )
+    p.add_argument(
+        "--ne",
+        type=float,
+        default=11418.0,
+        metavar="FLOAT",
+        help="Effective population size (default: 11418.0).",
+    )
+    p.add_argument(
+        "--cutoff",
+        type=float,
+        default=1.5e-8,
+        metavar="FLOAT",
+        help="Recombination fraction threshold for window extension (default: 1.5e-8).",
+    )
+    p.set_defaults(func=_run)
+
+
+def _run(args: argparse.Namespace) -> int:
+    from ldetect_lite.shrinkage import partition_chromosome
+
+    partition_chromosome(
+        genetic_map_path=args.genetic_map,
+        n_individuals=args.n_individuals,
+        output_path=args.output,
+        window_size=args.window_size,
+        ne=args.ne,
+        cutoff=args.cutoff,
+    )
+    return 0