allelign 0.1.0__py3-none-any.whl

allelign/__init__.py

@@ -0,0 +1,69 @@
+"""allelign: read, align and quality-control GWAS summary statistics and PGS weights.
+
+One place for the steps every downstream method repeats -- parsing the many
+summary-statistics dialects, getting effect alleles right against a reference,
+and the checks that catch bad input before it becomes a confident wrong
+number. NumPy-only; Numba and SciPy speed up the parser and the LD screen when
+installed.
+"""
+
+__version__ = "0.1.0"
+
+from .alleles import (allele_orientation, is_ambiguous, normalize_chrom,
+                      reverse_complement)
+from .build import BuildMismatchError, check_build, normalize_build
+from .catalog import resolve_gwas_catalog_columns
+from .download import download_ref, parse_ref, read_keep_ids, resolve_ref
+from .genotypes import Bed, ld_consistency_screen_genotypes
+from .align import (Harmonized, HarmonizedWeights,
+                    count_positional_only_matches, coverage_message,
+                    diagnose_match, harmonize, harmonize_weights,
+                    reanchor_on_identifier, reference_coverage,
+                    variant_indices)
+from .ldcheck import (chromosome_blocks, dense_blocks, dentist_statistic,
+                      ld_consistency_screen_selected,
+                      ld_blocks_from_genotypes, ld_consistency_screen,
+                      loo_statistic)
+from .qc import (af_concordance_mask, genomic_control_factor,
+                 genomic_inflation, gwas_af_on_counted_allele,
+                 implied_sample_size, impute_n_eff, in_long_range_ld,
+                 qc_sumstats, sd_consistency_mask, should_impute_n)
+from .status import (QC_REASON_NAMES, new_status, status_counts,
+                     write_status_table)
+from .sumstats import (ColumnMappingError, Sumstats, anchor_n_eff,
+                       detect_columns, inspect_columns, n_eff_case_control,
+                       read_sumstats, rescale_n_eff, write_sumstats)
+from .variants import Variants, read_bim, read_pvar, read_variants
+from .weights import (SCORING_COLUMNS, ScoringFile, WeightsTable, read_scoring_file,
+                      read_weights, scoring_file_id, write_pgs_scoring_file,
+                      write_weights)
+
+__all__ = [
+    "__version__", "SCORING_COLUMNS", "resolve_gwas_catalog_columns",
+    # reading and writing
+    "Sumstats", "read_sumstats", "write_sumstats", "detect_columns",
+    "inspect_columns", "ColumnMappingError", "n_eff_case_control",
+    "rescale_n_eff", "anchor_n_eff",
+    "Variants", "read_bim", "read_pvar", "read_variants", "Bed",
+    "WeightsTable", "read_weights", "write_weights", "ScoringFile",
+    "read_scoring_file", "scoring_file_id", "write_pgs_scoring_file",
+    # alignment
+    "Harmonized", "harmonize", "HarmonizedWeights", "harmonize_weights",
+    "reanchor_on_identifier", "reference_coverage", "coverage_message",
+    "diagnose_match", "count_positional_only_matches", "variant_indices",
+    "normalize_chrom", "reverse_complement", "is_ambiguous",
+    "allele_orientation", "normalize_build", "check_build",
+    "BuildMismatchError",
+    # quality control
+    "qc_sumstats", "sd_consistency_mask", "af_concordance_mask",
+    "gwas_af_on_counted_allele", "should_impute_n", "impute_n_eff",
+    "genomic_control_factor", "implied_sample_size", "genomic_inflation",
+    "in_long_range_ld", "ld_consistency_screen",
+    "ld_consistency_screen_selected", "dentist_statistic",
+    "loo_statistic", "ld_blocks_from_genotypes", "dense_blocks",
+    "chromosome_blocks", "ld_consistency_screen_genotypes",
+    # per-variant status
+    "QC_REASON_NAMES", "new_status", "status_counts", "write_status_table",
+    # downloading
+    "parse_ref", "resolve_ref", "download_ref", "read_keep_ids",
+]

allelign/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

allelign/_common.py

@@ -0,0 +1,95 @@
+"""Small shared helpers: control validation, text input and atomic output."""
+
+from __future__ import annotations
+
+import gzip
+import os
+import tempfile
+from contextlib import contextmanager
+from pathlib import Path
+
+import numpy as np
+
+
+def finite_control(name, value, *, lower=None, upper=None):
+    """Coerce a finite scalar control, rejecting booleans and vectors."""
+    if isinstance(value, (bool, np.bool_)) or np.ndim(value) != 0:
+        raise ValueError(f"{name} must be a finite number")
+    try:
+        value = float(value)
+    except (TypeError, ValueError, OverflowError):
+        raise ValueError(f"{name} must be a finite number") from None
+    if not np.isfinite(value):
+        raise ValueError(f"{name} must be a finite number")
+    if lower is not None and value < lower:
+        raise ValueError(f"{name} must be >= {lower}")
+    if upper is not None and value > upper:
+        raise ValueError(f"{name} must be <= {upper}")
+    return value
+
+
+def integer_at_least(name, value, minimum):
+    """Return an integer control, rejecting bools and silent coercion."""
+    if (isinstance(value, (bool, np.bool_))
+            or not isinstance(value, (int, np.integer))
+            or int(value) < minimum):
+        raise ValueError(f"{name} must be an integer >= {minimum}")
+    return int(value)
+
+
+def validate_boolean(**controls):
+    """Reject truthy/falsy surrogates for controls that are genuinely boolean."""
+    for name, value in controls.items():
+        if not isinstance(value, (bool, np.bool_)):
+            raise ValueError(f"{name} must be a boolean")
+
+
+def validate_seed(seed):
+    """Return a seed usable by ``numpy.random.SeedSequence``, or ``None``."""
+    if seed is None:
+        return None
+    if (isinstance(seed, (bool, np.bool_))
+            or not isinstance(seed, (int, np.integer))
+            or not 0 <= int(seed) <= np.iinfo(np.uint32).max):
+        raise ValueError("seed must be an integer in [0, 2**32 - 1] or None")
+    return int(seed)
+
+
+def open_text(path):
+    """Open a plain or gzip/bgzip text file for reading.
+
+    ``utf-8-sig`` strips a UTF-8 byte-order mark, which Excel and several GWAS
+    portals emit; left in place it glues itself to the first header token,
+    which then matches no alias, so the first column (usually the variant ID)
+    is silently never mapped.
+    """
+    name = os.fspath(path)
+    if name.endswith((".gz", ".bgz")):
+        return gzip.open(name, "rt", encoding="utf-8-sig")
+    return open(name, "r", encoding="utf-8-sig")
+
+
+@contextmanager
+def atomic_text(path):
+    """Write text so that only a complete file is ever published at ``path``.
+
+    A ``.gz`` destination is gzip-compressed. The temporary file lives on the
+    destination filesystem, so the final ``os.replace`` is atomic.
+    """
+    path = Path(path)
+    fd, temporary = tempfile.mkstemp(prefix=f".{path.name}.",
+                                     dir=path.parent or ".")
+    try:
+        if path.name.endswith(".gz"):
+            os.close(fd)
+            with gzip.open(temporary, "wt", encoding="utf-8", compresslevel=1) as fh:
+                yield fh
+        else:
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                yield fh
+                fh.flush()
+                os.fsync(fh.fileno())
+        os.replace(temporary, path)
+    finally:
+        if os.path.exists(temporary):
+            os.unlink(temporary)

allelign/_numba.py

@@ -0,0 +1,22 @@
+"""Optional Numba support. Everything has a pure-NumPy/Python fallback."""
+
+from __future__ import annotations
+
+try:  # pragma: no cover - depends on the environment
+    import numba as _numba
+    from numba import config as numba_config
+    HAVE_NUMBA = True
+except Exception:  # pragma: no cover - a missing or broken install
+    _numba = None
+    numba_config = None
+    HAVE_NUMBA = False
+
+
+def jit_available():
+    """True when compiled kernels can actually run (not disabled by config)."""
+    return HAVE_NUMBA and not getattr(numba_config, "DISABLE_JIT", False)
+
+
+def jit_nogil(fn):
+    """Compile ``fn`` in nopython, GIL-releasing mode with an on-disk cache."""
+    return _numba.njit(cache=True, nogil=True)(fn)