gsMap3D 0.1.0a1__py3-none-any.whl

gsMap/latent2gene/row_ordering.py

@@ -0,0 +1,182 @@
+"""
+Row ordering optimization for cache efficiency
+"""
+
+import logging
+
+import numpy as np
+from numba import njit
+
+logger = logging.getLogger(__name__)
+
+
+@njit
+def compute_jaccard_similarity(neighbors_a: np.ndarray, neighbors_b: np.ndarray) -> float:
+    """Compute Jaccard similarity between two neighbor sets"""
+    set_a = set(neighbors_a)
+    set_b = set(neighbors_b)
+    intersection = len(set_a & set_b)
+    union = len(set_a | set_b)
+    return intersection / union if union > 0 else 0.0
+
+
+def optimize_row_order(
+    neighbor_indices: np.ndarray,
+    cell_indices: np.ndarray,
+    method: str | None = None,
+    neighbor_weights: np.ndarray | None = None
+) -> np.ndarray:
+    """
+    Sort rows by shared neighbors to improve cache locality
+
+    Args:
+        neighbor_indices: (n_cells, k) array of neighbor indices (global indices)
+        cell_indices: (n_cells,) array of global indices for each cell
+        method: None (auto), 'weighted', 'greedy', or 'none'
+        neighbor_weights: Optional (n_cells, k) array of weights for each neighbor
+
+    Returns:
+        Reordered row indices (local indices 0 to n_cells-1)
+
+    Complexity:
+        - weighted: O(n*k) where k is number of neighbors - very efficient!
+        - greedy: O(n²) - only for very small datasets
+        - none: O(1) - returns original order
+    """
+    n_cells = len(neighbor_indices)
+
+    # Create mapping from global to local indices
+    global_to_local = {global_idx: local_idx for local_idx, global_idx in enumerate(cell_indices)}
+
+    # Auto-select method if None
+    if method is None:
+        if neighbor_weights is not None and n_cells > 2000:
+            method = 'weighted'
+        else:
+            method = 'greedy'
+
+    if method == 'weighted' and neighbor_weights is not None:
+        # Efficient weighted heuristic: follow highest-weight neighbors
+        visited = np.zeros(n_cells, dtype=bool)
+        ordered = []
+
+        # Start with cell that has highest max weight to any single neighbor
+        max_weights = neighbor_weights.max(axis=1)
+        current = np.argmax(max_weights)
+
+        ordered.append(current)
+        visited[current] = True
+
+        # Build reverse lookup (using local indices)
+        reverse_neighbors = [[] for _ in range(n_cells)]
+        for i in range(n_cells):
+            for j, neighbor_global_idx in enumerate(neighbor_indices[i]):
+                if neighbor_global_idx in global_to_local:
+                    neighbor_local_idx = global_to_local[neighbor_global_idx]
+                    reverse_neighbors[neighbor_local_idx].append((i, neighbor_weights[i, j]))
+
+        # Process all cells
+        for _ in range(n_cells - 1):
+            neighbors = neighbor_indices[current]
+            weights = neighbor_weights[current]
+
+            # Sort neighbors by weight (highest first)
+            sorted_idx = np.argsort(weights)[::-1]
+
+            # Find the unvisited neighbor with highest weight
+            next_cell = None
+            best_weight = -1
+
+            for idx in sorted_idx:
+                neighbor_global_idx = neighbors[idx]
+                if neighbor_global_idx in global_to_local:
+                    neighbor_local_idx = global_to_local[neighbor_global_idx]
+                    if not visited[neighbor_local_idx]:
+                        if weights[idx] > best_weight:
+                            best_weight = weights[idx]
+                            next_cell = neighbor_local_idx
+
+            # If no unvisited direct neighbors, find closest unvisited cell
+            if next_cell is None:
+                connection_scores = np.zeros(n_cells)
+
+                # Check connections from last few visited cells
+                for cell_idx in ordered[-min(10, len(ordered)):]:
+                    # Add forward connections
+                    for j, neighbor_global_idx in enumerate(neighbor_indices[cell_idx]):
+                        if neighbor_global_idx in global_to_local:
+                            neighbor_local_idx = global_to_local[neighbor_global_idx]
+                            if not visited[neighbor_local_idx]:
+                                connection_scores[neighbor_local_idx] += neighbor_weights[cell_idx, j]
+
+                    # Add reverse connections
+                    for reverse_idx, reverse_weight in reverse_neighbors[cell_idx]:
+                        if not visited[reverse_idx]:
+                            connection_scores[reverse_idx] += reverse_weight
+
+                # Pick the unvisited cell with highest connection score
+                if connection_scores.max() > 0:
+                    unvisited_scores = connection_scores.copy()
+                    unvisited_scores[visited] = -1
+                    next_cell = np.argmax(unvisited_scores)
+                else:
+                    # No connections found, pick cell with highest max weight
+                    unvisited_max_weights = max_weights.copy()
+                    unvisited_max_weights[visited] = -1
+                    next_cell = np.argmax(unvisited_max_weights)
+
+            ordered.append(next_cell)
+            visited[next_cell] = True
+            current = next_cell
+
+        return np.array(ordered)
+
+    elif method == 'greedy':
+        # Original greedy approach - only for small datasets
+        if n_cells > 5000:
+            logger.warning(f"Greedy method is O(n²) - not recommended for {n_cells} cells")
+
+        # Convert neighbor indices to sets of local indices for Jaccard computation
+        neighbor_sets = []
+        for i in range(n_cells):
+            local_neighbors = set()
+            for neighbor_global_idx in neighbor_indices[i]:
+                if neighbor_global_idx in global_to_local:
+                    local_neighbors.add(global_to_local[neighbor_global_idx])
+            neighbor_sets.append(local_neighbors)
+
+        remaining = set(range(n_cells))
+        ordered = []
+
+        current = np.random.choice(list(remaining))
+        ordered.append(current)
+        remaining.remove(current)
+
+        while remaining:
+            max_sim = -1
+            next_row = None
+
+            # Sample candidates for large datasets
+            candidates = list(remaining)
+            if len(candidates) > 100:
+                candidates = np.random.choice(candidates, min(100, len(candidates)), replace=False)
+
+            for candidate in candidates:
+                # Use precomputed sets for Jaccard similarity
+                intersection = len(neighbor_sets[current] & neighbor_sets[candidate])
+                union = len(neighbor_sets[current] | neighbor_sets[candidate])
+                sim = intersection / union if union > 0 else 0.0
+
+                if sim > max_sim:
+                    max_sim = sim
+                    next_row = candidate
+
+            ordered.append(next_row)
+            remaining.remove(next_row)
+            current = next_row
+
+        return np.array(ordered)
+
+    else:
+        # Simple sequential order as fallback
+        return np.arange(n_cells)

gsMap/latent2gene/row_ordering_jax.py

@@ -0,0 +1,159 @@
+"""JAX-accelerated row ordering optimization using jax.lax.scan"""
+
+import logging
+
+import jax
+import jax.numpy as jnp
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+# @partial(jit, static_argnames=['k'])
+def _optimize_weighted_scan(
+        neighbor_indices: jnp.ndarray,
+        neighbor_weights: jnp.ndarray,
+        cell_indices: jnp.ndarray,
+        k: int
+) -> jnp.ndarray:
+    """
+    JIT-compiled weighted row ordering using jax.lax.scan for optimal performance.
+
+    Args:
+        neighbor_indices: (n_cells, k) neighbor indices (global)
+        neighbor_weights: (n_cells, k) neighbor weights
+        cell_indices: (n_cells,) global cell indices
+        k: Number of neighbors per cell
+
+    Returns:
+        Reordered row indices (local 0..n-1)
+    """
+    n_cells = len(neighbor_indices)
+
+    # Pre-compute global to local mapping
+    # Handle -1 values in neighbor_indices (invalid neighbors)
+    valid_mask = neighbor_indices >= 0
+    max_global_idx = jnp.max(jnp.where(valid_mask, neighbor_indices, 0))
+
+    # Create inverse mapping from global to local indices
+    inverse_map = jnp.full(max_global_idx + 1, -1, dtype=jnp.int32)
+    inverse_map = inverse_map.at[cell_indices].set(jnp.arange(n_cells))
+
+    # Convert to local indices, preserving -1 for invalid neighbors
+    neighbor_indices_flat = neighbor_indices.ravel()
+    # For invalid indices (-1), keep them as -1
+    # For valid indices, map them through inverse_map
+    local_indices_flat = jnp.where(
+        neighbor_indices_flat >= 0,
+        inverse_map[jnp.where(neighbor_indices_flat >= 0, neighbor_indices_flat, 0)],
+        -1
+    )
+    local_neighbor_indices = local_indices_flat.reshape(n_cells, k)
+
+    # Initialize with highest weight cell
+    # Only consider valid neighbors when computing max weights
+    weights_masked = jnp.where(valid_mask, neighbor_weights, 0)
+    max_weights = jnp.max(weights_masked, axis=1)
+    start_node = jnp.argmax(max_weights)
+
+    # Initial state for scan
+    initial_state = {
+        "current": start_node,
+        "visited": jnp.zeros(n_cells, dtype=jnp.bool_).at[start_node].set(True),
+        "ordered": jnp.full(n_cells, -1, dtype=jnp.int32).at[0].set(start_node),
+        "max_weights": max_weights,
+        "local_neighbor_indices": local_neighbor_indices,
+        "neighbor_weights": neighbor_weights
+    }
+
+    def scan_step(state, t):
+        """Single step of the greedy ordering algorithm"""
+        current = state["current"]
+        visited = state["visited"]
+
+        # Find best unvisited neighbor
+        neighbors = state["local_neighbor_indices"][current]
+        weights = state["neighbor_weights"][current]
+
+        # Handle -1 values: create a mask for valid neighbors
+        is_valid = neighbors != -1
+        # For invalid neighbors, use False for is_unvisited to avoid indexing with -1
+        is_unvisited = jnp.where(is_valid, ~visited[jnp.where(is_valid, neighbors, 0)], False)
+        mask = is_valid & is_unvisited
+
+        neighbor_scores = jnp.where(mask, weights, -jnp.inf)
+        best_idx = jnp.argmax(neighbor_scores)
+
+        # If neighbor found, use it; otherwise pick highest weight unvisited
+        has_neighbor = neighbor_scores[best_idx] > -jnp.inf
+        next_neighbor = neighbors[best_idx]
+
+        # Fallback to highest weight unvisited cell
+        unvisited_weights = jnp.where(visited, -jnp.inf, state["max_weights"])
+        next_maxweight = jnp.argmax(unvisited_weights)
+
+        next_cell = jnp.where(has_neighbor, next_neighbor, next_maxweight)
+
+        # Update state
+        new_state = {
+            "current": next_cell,
+            "visited": visited.at[next_cell].set(True),
+            "ordered": state["ordered"].at[t].set(next_cell),
+            "max_weights": state["max_weights"],
+            "local_neighbor_indices": state["local_neighbor_indices"],
+            "neighbor_weights": state["neighbor_weights"]
+        }
+
+        return new_state, None
+
+    # Run scan for n_cells-1 iterations (first cell already placed)
+    final_state, _ = jax.lax.scan(scan_step, initial_state, jnp.arange(1, n_cells))
+
+    return final_state["ordered"]
+
+
+def optimize_row_order_jax(
+        neighbor_indices: np.ndarray,
+        cell_indices: np.ndarray,
+        neighbor_weights: np.ndarray | None,
+        device: jax.Device | None = None
+) -> np.ndarray:
+    """
+    High-performance JAX-based row ordering for cache efficiency.
+
+    Args:
+        neighbor_indices: (n_cells, k) neighbor indices (global)
+        cell_indices: (n_cells,) global cell indices
+        neighbor_weights: (n_cells, k) neighbor weights
+        device: JAX device or None (uses default JAX device)
+
+    Returns:
+        Reordered row indices (local 0..n-1) as NumPy array
+    """
+    # Use default device if not provided (should be already configured by configure_jax_platform)
+    if device is None:
+        device = jax.devices()[0]
+
+    # Skip if on CPU - scanning is extremely slow on CPU
+    if device.platform == 'cpu':
+        n_cells = len(neighbor_indices)
+        logger.info(f"Skipping JAX-based row ordering optimization on CPU for {n_cells} cells (too slow).")
+        return np.arange(n_cells)
+
+    n_cells, k = neighbor_indices.shape
+    logger.debug(f"Running JAX scan-based weighted ordering for {n_cells} cells on {device.platform}")
+
+    with jax.default_device(device):
+        neighbor_indices_jax = jnp.asarray(neighbor_indices)
+        neighbor_weights_jax = jnp.asarray(neighbor_weights)
+        cell_indices_jax = jnp.asarray(cell_indices)
+
+        # Run optimized weighted ordering
+        ordered_jax = _optimize_weighted_scan(
+            neighbor_indices_jax,
+            neighbor_weights_jax,
+            cell_indices_jax,
+            k
+        )
+
+    return np.array(ordered_jax)

gsMap/ldscore/__init__.py

@@ -0,0 +1 @@
+from gsMap.config import LDScoreConfig

gsMap/ldscore/batch_construction.py

@@ -0,0 +1,163 @@
+"""
+Simplified batch construction for LD score calculation.
+
+This module handles:
+1. Splitting HM3 SNPs into fixed-size batches
+2. Calculating reference block boundaries for each batch based on LD window
+"""
+
+import logging
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class BatchInfo:
+    """
+    Information for a single HM3 batch.
+
+    Attributes
+    ----------
+    chromosome : str
+        Chromosome identifier
+    hm3_indices : np.ndarray
+        Indices of HM3 SNPs in this batch (relative to chromosome BIM)
+    ref_start_idx : int
+        Start index of reference block in chromosome (inclusive)
+    ref_end_idx : int
+        End index of reference block in chromosome (exclusive)
+    """
+
+    chromosome: str
+    hm3_indices: np.ndarray
+    ref_start_idx: int
+    ref_end_idx: int
+
+
+def construct_batches(
+    bim_df: pd.DataFrame,
+    hm3_snp_names: list[str],
+    batch_size_hm3: int,
+    ld_wind: float = 1.0,
+    ld_unit: str = "CM",
+) -> list[BatchInfo]:
+    """
+    Construct batches of HM3 SNPs with reference block boundaries.
+
+    Optimized implementation using searchsorted for O(log N) boundary finding.
+
+    Parameters
+    ----------
+    bim_df : pd.DataFrame
+        BIM dataframe for this chromosome
+    hm3_snp_names : List[str]
+        List of HM3 SNP names for this chromosome
+    batch_size_hm3 : int
+        Number of HM3 SNPs per batch
+    ld_wind : float
+        LD window size (default: 1.0)
+    ld_unit : str
+        Unit for LD window: 'SNP', 'KB', 'CM' (default: 'CM')
+
+    Returns
+    -------
+    List[BatchInfo]
+        List of BatchInfo objects
+    """
+    chromosome = str(bim_df["CHR"].iloc[0])
+
+    # Pre-extract arrays for performance
+    bim_df["SNP"].values
+
+    # helper to get coordinates based on unit
+    if ld_unit == "SNP":
+        coords = np.arange(len(bim_df))
+        max_dist = int(ld_wind)
+    elif ld_unit == "KB":
+        coords = bim_df["BP"].values
+        max_dist = ld_wind * 1000
+    elif ld_unit == "CM":
+        coords = bim_df["CM"].values
+        max_dist = ld_wind
+        # Fallback if CM is all zero
+        if np.all(coords == 0):
+            logger.warning(f"All CM values are 0 for chromosome {chromosome}. Fallback to 1MB window (BP).")
+            coords = bim_df["BP"].values
+            max_dist = 1_000_000
+    else:
+        raise ValueError(f"Invalid ld_unit: {ld_unit}. Must be 'SNP', 'KB', or 'CM'.")
+
+    # Find indices of HM3 SNPs in BIM
+    hm3_set = set(hm3_snp_names)
+    # np.isin on strings is very slow, use pandas isin instead
+    hm3_mask = bim_df["SNP"].isin(hm3_set).values
+    hm3_indices_all = np.where(hm3_mask)[0]
+
+    n_hm3 = len(hm3_indices_all)
+    if n_hm3 == 0:
+        logger.warning(f"No HM3 SNPs found in chromosome {chromosome}")
+        return []
+    if n_hm3 < len(hm3_snp_names):
+        logger.warning(f"{len(hm3_snp_names) - n_hm3} HM3 SNPs not found in chromosome {chromosome} reference plink panel")
+
+    logger.info(f"Found {n_hm3} HM3 SNPs in chromosome {chromosome}")
+
+    # Calculate batch boundaries
+    # We want batches of size batch_size_hm3
+    # Start indices: 0, batch_size, 2*batch_size, ...
+    batch_starts = np.arange(0, n_hm3, batch_size_hm3)
+    # End indices: batch_size, 2*batch_size, ..., n_hm3
+    batch_ends = np.minimum(batch_starts + batch_size_hm3, n_hm3)
+
+    n_batches = len(batch_starts)
+
+    # Get indices in BIM for start and end of each batch
+    # hm3_indices_all contains the BIM indices of HM3 SNPs
+    # We need the BIM index of the first and last HM3 SNP in each batch
+
+    # First HM3 SNP in each batch
+    batch_start_bim_indices = hm3_indices_all[batch_starts]
+    # Last HM3 SNP in each batch (indices are exclusive in slice, so -1 for element access)
+    batch_end_bim_indices = hm3_indices_all[batch_ends - 1]
+
+    # Get coordinates for these batch boundaries
+    min_coords = coords[batch_start_bim_indices]
+    max_coords = coords[batch_end_bim_indices]
+
+    # Calculate window boundaries
+    window_starts = min_coords - max_dist
+    window_ends = max_coords + max_dist
+
+    if ld_unit == "SNP":
+        # For SNP unit, coordinates are indices, so we just clip
+        ref_starts = np.maximum(window_starts, 0).astype(int)
+        ref_ends = np.minimum(window_ends, len(coords)).astype(int)
+    else:
+        # Vectorized searchsorted
+        # Find insertion points for all window starts and ends at once
+        ref_starts = np.searchsorted(coords, window_starts, side='left')
+        ref_ends = np.searchsorted(coords, window_ends, side='right')
+
+    # Construct BatchInfo objects
+    batch_infos = []
+    for i in range(n_batches):
+        # Slice the HM3 indices for this batch
+        b_hm3_indices = hm3_indices_all[batch_starts[i]:batch_ends[i]]
+
+        batch_infos.append(BatchInfo(
+            chromosome=chromosome,
+            hm3_indices=b_hm3_indices,
+            ref_start_idx=int(ref_starts[i]),
+            ref_end_idx=int(ref_ends[i]),
+        ))
+
+    logger.info(f"Created {len(batch_infos)} batches for chromosome {chromosome}")
+    if len(batch_infos) > 0:
+        avg_size = np.mean(ref_ends - ref_starts)
+        logger.info(f"  Average reference block size: {avg_size:.0f} SNPs")
+
+    return batch_infos

gsMap/ldscore/compute.py

@@ -0,0 +1,126 @@
+"""
+Simplified LD score computation without masking or padding.
+
+Direct computation of unbiased L2 statistics from genotype matrices using NumPy and Scipy.
+"""
+
+
+import numpy as np
+import scipy.sparse
+
+from .constants import LDSC_BIAS_CORRECTION_DF
+
+
+def compute_unbiased_l2_batch(
+    X_hm3: np.ndarray,
+    X_ref_block: np.ndarray,
+) -> np.ndarray:
+    """
+    Compute unbiased LD scores (L2) for HM3 SNPs against reference block.
+
+    The unbiased L2 estimator is:
+        L2 = r^2 - (1 - r^2) / (N - 2)
+
+    where r^2 is the squared correlation and N is the number of individuals.
+
+    Parameters
+    ----------
+    X_hm3 : np.ndarray
+        Standardized genotypes for HM3 SNPs, shape (n_individuals, n_hm3_snps)
+    X_ref_block : np.ndarray
+        Standardized genotypes for reference block, shape (n_individuals, n_ref_snps)
+
+    Returns
+    -------
+    np.ndarray
+        Unbiased LD scores, shape (n_hm3_snps, n_ref_snps)
+    """
+    n_individuals = X_hm3.shape[0]
+
+    # Compute correlation matrix: r = (1/N) * X_hm3^T @ X_ref_block
+    # shape: (n_hm3_snps, n_ref_snps)
+    r = np.dot(X_hm3.T, X_ref_block) / n_individuals
+
+    # Compute r^2
+    r_squared = r ** 2
+
+    # Apply bias correction
+    bias_correction = (1.0 - r_squared) / (n_individuals - LDSC_BIAS_CORRECTION_DF)
+    l2_unbiased = r_squared - bias_correction
+
+    return l2_unbiased
+
+
+def compute_ld_scores(
+    X_hm3: np.ndarray,
+    X_ref_block: np.ndarray,
+) -> np.ndarray:
+    """
+    Compute LD scores by summing unbiased L2 over reference SNPs.
+
+    Parameters
+    ----------
+    X_hm3 : np.ndarray
+        Standardized genotypes for HM3 SNPs, shape (n_individuals, n_hm3_snps)
+    X_ref_block : np.ndarray
+        Standardized genotypes for reference block, shape (n_individuals, n_ref_snps)
+
+    Returns
+    -------
+    np.ndarray
+        LD scores for each HM3 SNP, shape (n_hm3_snps,)
+    """
+    # Compute unbiased L2 matrix
+    l2_unbiased = compute_unbiased_l2_batch(X_hm3, X_ref_block)
+
+    # Sum over reference SNPs (axis=1)
+    ld_scores = np.sum(l2_unbiased, axis=1)
+
+    return ld_scores
+
+
+def compute_batch_weights_sparse(
+    X_hm3: np.ndarray,
+    X_ref_block: np.ndarray,
+    block_mapping_matrix: scipy.sparse.csr_matrix | np.ndarray,
+) -> np.ndarray:
+    """
+    Compute LD score weight matrix using matrix multiplication.
+
+    Works for both sparse and dense mapping matrices.
+    Weights = L2_Unbiased @ Mapping_Matrix
+
+    Parameters
+    ----------
+    X_hm3 : np.ndarray
+        Standardized genotypes for HM3 SNPs, shape (n_individuals, n_hm3_snps)
+    X_ref_block : np.ndarray
+        Standardized genotypes for reference block, shape (n_individuals, n_ref_snps)
+    block_mapping_matrix : Union[scipy.sparse.csr_matrix, np.ndarray]
+        Mapping matrix for the reference block, shape (n_ref_snps, n_features).
+        Can be a sparse CSR matrix (from creating_snp_feature_map) or a dense array (from annotations).
+
+    Returns
+    -------
+    weights : np.ndarray
+        Weight matrix, shape (n_hm3_snps, n_features)
+    """
+    # 1. Compute unbiased L2 matrix: (n_hm3_snps, n_ref_snps)
+    l2_unbiased = compute_unbiased_l2_batch(X_hm3, X_ref_block)
+
+    # 2. Compute Weights: W = L2 @ M
+    # (n_hm3, n_ref) @ (n_ref, n_features) -> (n_hm3, n_features)
+    # numpy dot handles dense @ dense
+    # scipy.sparse handles dense @ sparse
+    if scipy.sparse.issparse(block_mapping_matrix):
+        weights = l2_unbiased @ block_mapping_matrix
+    else:
+        weights = np.dot(l2_unbiased, block_mapping_matrix)
+
+    # Ensure output is a dense numpy array
+    if scipy.sparse.issparse(weights):
+        weights = weights.toarray()
+    elif isinstance(weights, np.matrix):
+        weights = np.asarray(weights)
+
+    return weights

gsMap/ldscore/constants.py

@@ -0,0 +1,70 @@
+"""
+Constants and magic numbers used in LD score regression and spatial LDSC.
+
+This module centralizes all numerical constants to improve code readability
+and maintainability.
+"""
+
+# === LD Score Calculation Constants ===
+
+# Degrees of freedom for unbiased L2 estimator bias correction
+# The unbiased estimator is: r^2 - (1 - r^2) / (N - LDSC_BIAS_CORRECTION_DF)
+LDSC_BIAS_CORRECTION_DF = 2.0
+
+# Default LD window sizes
+DEFAULT_LD_WINDOW_CM = 1.0  # centiMorgans
+DEFAULT_LD_WINDOW_KB = 1000  # kilobases
+DEFAULT_LD_WINDOW_MB = 1.0  # megabases (in base pairs)
+
+# === Genomic Control Constants ===
+
+# Median of chi-squared distribution with 1 degree of freedom
+# Used for calculating genomic control lambda (λGC):
+# λGC = median(χ²) / CHI_SQUARED_1DF_MEDIAN
+# where χ² = Z^2 from GWAS summary statistics
+CHI_SQUARED_1DF_MEDIAN = 0.4559364
+
+# === Statistical Thresholds ===
+
+# Standard genome-wide significance level (GWAS)
+GWAS_SIGNIFICANCE_ALPHA = 5e-8
+
+# Standard nominal significance level
+NOMINAL_SIGNIFICANCE_ALPHA = 0.05
+
+# FDR significance threshold (commonly used for spatial analysis)
+FDR_SIGNIFICANCE_ALPHA = 0.001
+
+# === Numerical Stability Constants ===
+
+# Minimum p-value for log transformation (prevents log(0) = -inf)
+# log10(1e-300) ≈ -300, which is reasonable for visualization
+MIN_P_VALUE = 1e-300
+
+# Maximum p-value (ceiling for numerical stability)
+MAX_P_VALUE = 1.0
+
+# Minimum MAF (minor allele frequency) for SNP filtering
+DEFAULT_MAF_THRESHOLD = 0.05
+
+# === Storage and Precision Constants ===
+
+# Default dtype for LD score storage (saves ~75% disk space vs float32)
+LDSCORE_STORAGE_DTYPE = "float16"
+
+# Default dtype for computation
+LDSCORE_COMPUTE_DTYPE = "float32"
+
+# === Regression Constants ===
+
+# Default number of jackknife blocks for standard error estimation
+DEFAULT_N_BLOCKS = 200
+
+# Minimum number of SNPs required for reliable LD score estimation
+MIN_SNPS_FOR_LDSC = 200
+
+# === Window Quantization Constants ===
+
+# Default number of bins for dynamic programming quantization
+# (balances JIT compilation overhead vs padding waste)
+DEFAULT_QUANTIZATION_BINS = 20