pygapit-ng 1.2.1__py3-none-any.whl

pygapit/__init__.py

@@ -0,0 +1,108 @@
+"""GAPIT-style genomic association and prediction tools for Python."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("pygapit-ng")
+except PackageNotFoundError:  # source tree imported without installation
+    __version__ = "0+unknown"
+__author__ = "pyGAPIT contributors (based on GAPIT by Jiabo Wang & Zhiwu Zhang)"
+__license__ = "GPL-3.0"
+
+from .gapit import GAPIT, GAPITOutputFiles, GAPITResult, ModelRunResult
+from .gs.blup import (
+    GBLUPResult,
+    SUPERSelectionResult,
+    cblup,
+    gblup,
+    predict_new,
+    sblup,
+    select_super_qtns,
+)
+from .gwas.blink import BLINKResult, blink_gwas
+from .gwas.farmcpu import FarmCPUResult, farmcpu_gwas
+from .gwas.glm import GLMResult, glm_gwas
+from .gwas.mlm import MLMResult, cmlm_gwas, mlm_gwas
+from .gwas.mlmm import MLMMResult, mlmm_gwas
+from .io.formats import (
+    AlignedData,
+    GenotypeData,
+    PhenotypeData,
+    align_inputs,
+    align_taxa,
+    maf_filter,
+    read_hapmap,
+    read_numeric,
+    read_phenotype,
+)
+from .stats.emma import emma_remle, emmax_p3d
+from .stats.kinship import vanraden_kinship, zhang_kinship
+from .stats.pca import build_covariate_matrix, compute_pca
+from .stats.testing import (
+    benjamini_hochberg,
+    bonferroni_threshold,
+    genomic_inflation_factor,
+    get_significant_snps,
+)
+from .visualization.plots import (
+    gs_scatter,
+    kinship_heatmap,
+    manhattan_interactive,
+    manhattan_plot,
+    pca_plot_2d,
+    pca_plot_3d_interactive,
+    phenotype_distribution,
+    qq_plot,
+)
+
+__all__ = [
+    "GAPIT",
+    "AlignedData",
+    "BLINKResult",
+    "FarmCPUResult",
+    "GAPITOutputFiles",
+    "GAPITResult",
+    "GBLUPResult",
+    "GLMResult",
+    "GenotypeData",
+    "MLMMResult",
+    "MLMResult",
+    "ModelRunResult",
+    "PhenotypeData",
+    "SUPERSelectionResult",
+    "align_inputs",
+    "align_taxa",
+    "benjamini_hochberg",
+    "blink_gwas",
+    "bonferroni_threshold",
+    "build_covariate_matrix",
+    "cblup",
+    "cmlm_gwas",
+    "compute_pca",
+    "emma_remle",
+    "emmax_p3d",
+    "farmcpu_gwas",
+    "gblup",
+    "genomic_inflation_factor",
+    "get_significant_snps",
+    "glm_gwas",
+    "gs_scatter",
+    "kinship_heatmap",
+    "maf_filter",
+    "manhattan_interactive",
+    "manhattan_plot",
+    "mlm_gwas",
+    "mlmm_gwas",
+    "pca_plot_2d",
+    "pca_plot_3d_interactive",
+    "phenotype_distribution",
+    "predict_new",
+    "qq_plot",
+    "read_hapmap",
+    "read_numeric",
+    "read_phenotype",
+    "sblup",
+    "select_super_qtns",
+    "vanraden_kinship",
+    "zhang_kinship",
+]

pygapit/_typing.py

@@ -0,0 +1,81 @@
+"""Shared NumPy array types used across PyGAPIT."""
+
+from __future__ import annotations
+
+import typing as t
+
+import numpy as np
+
+Array: t.TypeAlias = np.ndarray[tuple[int, ...], np.dtype[np.generic]]
+Vector: t.TypeAlias = np.ndarray[tuple[int], np.dtype[np.generic]]
+Matrix: t.TypeAlias = np.ndarray[tuple[int, int], np.dtype[np.generic]]
+
+NumericVector: t.TypeAlias = np.ndarray[tuple[int], np.dtype[np.number]]
+
+FloatVector: t.TypeAlias = np.ndarray[tuple[int], np.dtype[np.float64]]
+FloatMatrix: t.TypeAlias = np.ndarray[tuple[int, int], np.dtype[np.float64]]
+
+IntVector: t.TypeAlias = np.ndarray[tuple[int], np.dtype[np.int_]]
+BoolVector: t.TypeAlias = np.ndarray[tuple[int], np.dtype[np.bool_]]
+StrVector: t.TypeAlias = np.ndarray[tuple[int], np.dtype[np.str_]]
+
+LabelVector: t.TypeAlias = StrVector | NumericVector
+ArrayT = t.TypeVar("ArrayT", bound=Array)
+
+
+def readonly_copy(values: ArrayT) -> ArrayT:
+    """Return an independent NumPy array whose contents cannot be mutated."""
+    result = values.copy()
+    result.setflags(write=False)
+    return result
+
+
+def as_float_vector(values: object, *, name: str = "array") -> FloatVector:
+    """Convert values to a one-dimensional float64 array."""
+    try:
+        result = np.asarray(values, dtype=np.float64)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"{name} must contain numeric values") from exc
+    if result.ndim != 1:
+        raise ValueError(f"{name} must be one-dimensional; got {result.ndim}D")
+    return result
+
+
+def as_float_matrix(values: object, *, name: str = "array") -> FloatMatrix:
+    """Convert values to a two-dimensional float64 array."""
+    try:
+        result = np.asarray(values, dtype=np.float64)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"{name} must contain numeric values") from exc
+    if result.ndim != 2:
+        raise ValueError(f"{name} must be two-dimensional; got {result.ndim}D")
+    return result
+
+
+def as_str_vector(values: object, *, name: str = "array") -> StrVector:
+    """Convert values to a one-dimensional Unicode array."""
+    result = np.asarray(values, dtype=str)
+    if result.ndim != 1:
+        raise ValueError(f"{name} must be one-dimensional; got {result.ndim}D")
+    return result
+
+
+def require_length(values: Vector, expected: int, *, name: str) -> None:
+    """Require a vector to have the expected number of elements."""
+    if len(values) != expected:
+        raise ValueError(f"{name} must have length {expected}; got {len(values)}")
+
+
+def require_row_count(values: Matrix, expected: int, *, name: str) -> None:
+    """Require a matrix to have the expected number of rows."""
+    if values.shape[0] != expected:
+        raise ValueError(f"{name} must have {expected} rows; got {values.shape[0]}")
+
+
+def require_square(values: Matrix, *, name: str, size: int | None = None) -> None:
+    """Require a square matrix, optionally with an exact side length."""
+    rows, columns = values.shape
+    if rows != columns:
+        raise ValueError(f"{name} must be square; got shape {values.shape}")
+    if size is not None and rows != size:
+        raise ValueError(f"{name} must have shape ({size}, {size}); got {values.shape}")

pygapit/cli.py

@@ -0,0 +1,299 @@
+"""
+Command-line interface for pyGAPIT.
+
+Usage
+-----
+    pygapit --Y pheno.txt --GD geno.txt --GM map.txt --model BLINK
+    pygapit --Y pheno.txt --GD geno.txt --GM map.txt --model MLM FarmCPU BLINK
+    pygapit --Y pheno.txt --G hapmap.hmp.txt --model BLINK --PCA_total 5
+    pygapit --Y pheno.txt --GD geno.txt --GM map.txt --model gBLUP
+"""
+
+import argparse
+from pathlib import Path
+
+from pygapit.gapit import GAPITResult
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="pygapit",
+        description="pyGAPIT: Genome Association and Prediction Integrated Tool (Python)",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # BLINK GWAS (default, highest power):
+  pygapit --Y traits.txt --GD geno.txt --GM map.txt --model BLINK
+
+  # Multiple models:
+  pygapit --Y traits.txt --GD geno.txt --GM map.txt --model GLM MLM BLINK FarmCPU
+
+  # Genomic prediction:
+  pygapit --Y traits.txt --GD geno.txt --GM map.txt --model gBLUP
+
+  # HapMap format:
+  pygapit --Y traits.txt --G genotype.hmp.txt --model BLINK
+
+  # Custom settings:
+  pygapit --Y traits.txt --GD geno.txt --GM map.txt \\
+          --model BLINK --PCA_total 5 --maf_threshold 0.01 --output_dir results/
+        """,
+    )
+
+    # Input files
+    io_group = parser.add_argument_group("Input data")
+    io_group.add_argument(
+        "--Y", required=True, help="Phenotype file (tab-delimited, col1=Taxa)"
+    )
+    io_group.add_argument(
+        "--GD", help="Numeric genotype file (col1=taxa, col2+=SNPs 0/1/2)"
+    )
+    io_group.add_argument(
+        "--GM", help="SNP map file (3 cols: SNP, Chromosome, Position)"
+    )
+    io_group.add_argument(
+        "--G", help="HapMap genotype file (alternative to --GD + --GM)"
+    )
+    io_group.add_argument(
+        "--KI", help="Kinship matrix file (optional; computed from GD if absent)"
+    )
+    io_group.add_argument("--CV", help="Covariate file (optional)")
+
+    # Model selection
+    model_group = parser.add_argument_group("Model")
+    model_group.add_argument(
+        "--model",
+        nargs="+",
+        default=["BLINK"],
+        choices=[
+            "GLM",
+            "MLM",
+            "CMLM",
+            "MLMM",
+            "FarmCPU",
+            "BLINK",
+            "gBLUP",
+            "cBLUP",
+            "sBLUP",
+        ],
+        help="GWAS/GS model(s) to run (default: BLINK)",
+    )
+    model_group.add_argument(
+        "--trait", help="Trait name or column index to analyze (default: all traits)"
+    )
+
+    # PCA / QC
+    qc_group = parser.add_argument_group("Quality control & PCA")
+    qc_group.add_argument(
+        "--PCA_total",
+        type=int,
+        default=3,
+        help="Number of PCs for population structure control (default: 3)",
+    )
+    qc_group.add_argument(
+        "--maf_threshold",
+        type=float,
+        default=0.05,
+        help="Minimum minor allele frequency (default: 0.05)",
+    )
+    qc_group.add_argument(
+        "--SNP_impute",
+        default="middle",
+        choices=["middle", "major", "minor", "mean", "none"],
+        help="Missing genotype imputation method (default: middle)",
+    )
+
+    # GWAS thresholds
+    thresh_group = parser.add_argument_group("Significance thresholds")
+    thresh_group.add_argument(
+        "--cutOff",
+        type=float,
+        default=None,
+        help="P-value threshold (default: Bonferroni 0.05/m)",
+    )
+    thresh_group.add_argument(
+        "--LD",
+        type=float,
+        default=0.7,
+        help="LD threshold for BLINK pruning (default: 0.7)",
+    )
+    thresh_group.add_argument(
+        "--maxLoop",
+        type=int,
+        default=10,
+        help="Max iterations for BLINK/FarmCPU (default: 10)",
+    )
+
+    # CMLM parameters
+    cmlm_group = parser.add_argument_group("CMLM parameters")
+    cmlm_group.add_argument(
+        "--group_from", type=int, default=1, help="Min groups for CMLM (default: 1)"
+    )
+    cmlm_group.add_argument(
+        "--group_to",
+        type=int,
+        default=None,
+        help="Max groups for CMLM (default: n individuals)",
+    )
+
+    # FarmCPU parameters
+    farm_group = parser.add_argument_group("FarmCPU parameters")
+    farm_group.add_argument(
+        "--bin_size",
+        type=int,
+        default=5_000_000,
+        help="Bin size in bp for FarmCPU (default: 5000000)",
+    )
+
+    super_group = parser.add_argument_group("SUPER/sBLUP parameters")
+    super_group.add_argument(
+        "--super_bin_size",
+        type=int,
+        default=10_000,
+        help="Genomic bin size in bp for SUPER selection (default: 10000)",
+    )
+    super_group.add_argument(
+        "--super_qtn_counts",
+        type=int,
+        nargs="+",
+        default=None,
+        help="Pseudo-QTN counts evaluated by SUPER (default: 10,20,...,100)",
+    )
+
+    # Simulation
+    sim_group = parser.add_argument_group("Phenotype simulation")
+    sim_group.add_argument(
+        "--h2",
+        type=float,
+        default=None,
+        help="Heritability for phenotype simulation (e.g. 0.7)",
+    )
+    sim_group.add_argument(
+        "--NQTN", type=int, default=None, help="Number of QTNs for simulation (e.g. 20)"
+    )
+
+    # Output
+    out_group = parser.add_argument_group("Output")
+    out_group.add_argument(
+        "--output_dir",
+        default=".",
+        help="Output directory for results (default: current dir)",
+    )
+    out_group.add_argument(
+        "--no_file_output",
+        action="store_true",
+        help="Suppress file output (only return object)",
+    )
+    out_group.add_argument(
+        "--buspred", action="store_true", help="Run genomic prediction after GWAS"
+    )
+
+    args = parser.parse_args()
+
+    # Validate inputs
+    if args.G is None and (args.GD is None or args.GM is None):
+        parser.error(
+            "Provide either --G (HapMap) or both --GD and --GM (numeric format)."
+        )
+
+    if args.h2 is not None and args.NQTN is None:
+        parser.error("--NQTN is required when --h2 is provided for simulation.")
+
+    print("=" * 60)
+    print("  pyGAPIT — Genome Association & Prediction Tool (Python)")
+    print("=" * 60)
+
+    import warnings
+
+    warnings.filterwarnings("ignore")
+
+    import pandas as pd
+
+    from pygapit import GAPIT
+
+    # Load data
+    print(f"\n[CLI] Loading phenotype: {args.Y}")
+    Y = pd.read_csv(args.Y, sep="\t")
+
+    GD = GM = G = None
+    if args.G:
+        print(f"[CLI] Loading HapMap: {args.G}")
+        G = pd.read_csv(args.G, sep="\t", header=None)
+    else:
+        print(f"[CLI] Loading genotype: {args.GD}")
+        print(f"[CLI] Loading map:      {args.GM}")
+        GD = pd.read_csv(args.GD, sep="\t")
+        GM = pd.read_csv(args.GM, sep="\t")
+
+    KI = pd.read_csv(args.KI, sep="\t", header=None) if args.KI else None
+    CV = pd.read_csv(args.CV, sep="\t") if args.CV else None
+
+    print(f"[CLI] Model(s): {args.model}")
+    print(f"[CLI] Output directory: {Path(args.output_dir).resolve()}")
+
+    # Run GAPIT
+    result = GAPIT(
+        Y=Y,
+        G=G,
+        GD=GD,
+        GM=GM,
+        KI=KI,
+        CV=CV,
+        model=args.model,
+        trait=args.trait,
+        PCA_total=args.PCA_total,
+        maf_threshold=args.maf_threshold,
+        SNP_impute=args.SNP_impute,
+        cutOff=args.cutOff,
+        LD=args.LD,
+        maxLoop=args.maxLoop,
+        group_from=args.group_from,
+        group_to=args.group_to,
+        bin_size=args.bin_size,
+        super_bin_size=args.super_bin_size,
+        super_qtn_counts=args.super_qtn_counts,
+        h2=args.h2,
+        NQTN=args.NQTN,
+        file_output=not args.no_file_output,
+        output_dir=args.output_dir,
+        buspred=args.buspred,
+    )
+
+    # Summary
+    print("\n" + "=" * 60)
+    print("  Results Summary")
+    print("=" * 60)
+
+    if isinstance(result, dict):
+        for key, r in result.items():
+            _print_summary(key, r)
+    else:
+        _print_summary(f"{result.trait} / {result.model}", result)
+
+    print("\n[CLI] Done.")
+
+
+def _print_summary(label: str, result: GAPITResult) -> None:
+    print(f"\n  {label}")
+    print(f"    h^2     = {result.h2:.4f}")
+    print(f"    lambda (GC) = {result.lambda_gc:.4f}")
+    if result.GWAS is not None:
+        print(f"    SNPs    = {len(result.GWAS):,}")
+    if result.significant is not None and len(result.significant) > 0:
+        print(f"    Sig SNPs = {len(result.significant)} (Bonferroni)")
+        top = result.significant.nsmallest(3, "P.value")
+        for _, row in top.iterrows():
+            print(
+                f"      {row['SNP']}  chr{row['Chr']}:{int(float(str(row['Pos']))):,}  "
+                f"p={row['P.value']:.2e}  effect={row['effect']:.4f}"
+            )
+    else:
+        print("    Sig SNPs = 0 (no Bonferroni-significant hits)")
+    if result.QTNs is not None and len(result.QTNs) > 0:
+        print(f"    QTNs selected = {len(result.QTNs)}")
+    if result.runtime_seconds > 0:
+        print(f"    Runtime = {result.runtime_seconds:.1f}s")
+
+
+if __name__ == "__main__":
+    main()