statgen 0.2.3__tar.gz → 0.2.4__tar.gz

{statgen-0.2.3 → statgen-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: statgen
-Version: 0.2.3
+Version: 0.2.4
 Summary: Statistical genetics data objects and loaders for Python and MATLAB/Octave.
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{statgen-0.2.3 → statgen-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "statgen"
-version = "0.2.3"
+version = "0.2.4"
 description = "Statistical genetics data objects and loaders for Python and MATLAB/Octave."
 readme = "README.md"
 requires-python = ">=3.10"

statgen-0.2.4/statgen/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.4"

{statgen-0.2.3 → statgen-0.2.4}/statgen/_bfile_utils.py

@@ -180,12 +180,16 @@ def _parse_fam(path: Path) -> pd.DataFrame:
     return out.reset_index(drop=True)
 
 
-def _parse_ploidy(path: Path | None, source_num_snp: int) -> tuple[np.ndarray, np.ndarray]:
+def _parse_ploidy(path: Path | None, source_num_snp: int, source_chr=None) -> tuple[np.ndarray, np.ndarray]:
     if path is None:
-        return (
-            np.full(source_num_snp, 2.0, dtype=float),
-            np.full(source_num_snp, 2.0, dtype=float),
-        )
+        ploidy_male = np.full(source_num_snp, 2.0, dtype=float)
+        ploidy_female = np.full(source_num_snp, 2.0, dtype=float)
+        if source_chr is not None:
+            chrs = np.asarray(source_chr, dtype=object).reshape(-1)
+            if chrs.size != source_num_snp:
+                raise ValueError("source_chr length must match source_num_snp")
+            ploidy_male[chrs == "X"] = 1.0
+        return ploidy_male, ploidy_female
 
     path = Path(path)
     df = _read_csv_strict(

{statgen-0.2.3 → statgen-0.2.4}/statgen/_variant_match.py

@@ -36,13 +36,13 @@ def match_shard_numeric(
     shard_label: str,
     *,
     source_name: str = "source",
-) -> np.ndarray:
+) -> tuple[np.ndarray, int]:
     ref_order = np.argsort(ref_keys, kind="mergesort", order=("bp", "a1_hash64", "a2_hash64"))
     ref_sorted = ref_keys[ref_order]
     check_unique_sorted_variant_keys(ref_sorted, f"reference shard {shard_label}", source_name)
 
     if src_keys.size == 0:
-        return np.full(ref_keys.size, -1, dtype=np.int64)
+        return np.full(ref_keys.size, -1, dtype=np.int64), 0
 
     src_order = np.argsort(src_keys, kind="mergesort", order=("bp", "a1_hash64", "a2_hash64"))
     src_sorted = src_keys[src_order]
@@ -55,4 +55,22 @@ def match_shard_numeric(
 
     out = np.full(ref_keys.size, -1, dtype=np.int64)
     out[matched] = src_order[pos[matched]]
-    return out
+
+    matched_src = np.zeros(src_keys.size, dtype=bool)
+    matched_src[out[matched]] = True
+    unmatched_src = src_keys[~matched_src]
+    if unmatched_src.size == 0 or ref_sorted.size == 0:
+        return out, 0
+
+    swapped_src = np.empty(unmatched_src.size, dtype=_KEY_DTYPE)
+    swapped_src["bp"] = unmatched_src["bp"]
+    swapped_src["a1_hash64"] = unmatched_src["a2_hash64"]
+    swapped_src["a2_hash64"] = unmatched_src["a1_hash64"]
+    swapped_pos = np.searchsorted(ref_sorted, swapped_src)
+    swapped_in_range = swapped_pos < ref_sorted.size
+    swapped_match = np.zeros(swapped_src.size, dtype=bool)
+    swapped_match[swapped_in_range] = (
+        ref_sorted[swapped_pos[swapped_in_range]]
+        == swapped_src[swapped_in_range]
+    )
+    return out, int(np.count_nonzero(swapped_match))

{statgen-0.2.3 → statgen-0.2.4}/statgen/genotype.py

@@ -20,6 +20,7 @@ from ._variant_match import match_shard_numeric, numeric_variant_keys
 
 _CACHE_SCHEMA = "genotype_cache/0.1"
 _BED_MISSING_INT8 = np.int8(-1)
+_HAPLOID_MODES = {"raw", "ploidy_scaled"}
 _CACHE_ARRAY_FIELDS = (
     "is_present",
     "ploidy_male",
@@ -73,9 +74,17 @@ def _normalize_snp_indices(snp_indices, num_snp: int) -> np.ndarray:
         )
     return out
 
+
+def _normalize_haploid_mode(haploid_mode) -> str:
+    mode = str(haploid_mode)
+    if mode not in _HAPLOID_MODES:
+        raise ValueError("GenotypePanel.fetch_genotypes: haploid_mode must be 'raw' or 'ploidy_scaled'")
+    return mode
+
 @dataclass(frozen=True)
 class _SourceRecord:
     bed_path: Path
+    bim_path: Path
     bed_file_size: int
     source_num_snp: int
     source_num_sample: int
@@ -105,14 +114,20 @@ def _load_source_record(prefix: str, label: str | None) -> _SourceRecord:
     source_fam = _parse_fam(fam)
     if label == "X" and ploidy is None:
         warnings.warn(
-            f"{prefix}: chrX genotype source has no .ploidy sidecar; defaulting matched rows to diploid ploidy",
+            f"{prefix}: chrX genotype source has no .ploidy sidecar; "
+            "defaulting chrX rows to male/female ploidy (1, 2)",
             RuntimeWarning,
             stacklevel=2,
         )
-    ploidy_male, ploidy_female = _parse_ploidy(ploidy, source_num_snp)
+    ploidy_male, ploidy_female = _parse_ploidy(
+        ploidy,
+        source_num_snp,
+        source_bim["chr"].to_numpy(dtype=object),
+    )
     bed_file_size = _validate_bed(bed, source_fam.shape[0], source_num_snp)
     return _SourceRecord(
         bed_path=bed,
+        bim_path=bim,
         bed_file_size=bed_file_size,
         source_num_snp=source_num_snp,
         source_num_sample=int(source_fam.shape[0]),
@@ -466,12 +481,44 @@ class GenotypePanel:
                 out[np.ix_(panel_rows, cols)] = source_geno[source_subject_rows, :]
         return out
 
-    def fetch_genotypes(self, snp_indices, bed_path=None):
+    def fetch_genotypes(self, snp_indices, bed_path=None, haploid_mode="raw"):
+        mode = _normalize_haploid_mode(haploid_mode)
         geno_int8 = self.fetch_genotypes_int8(snp_indices, bed_path=bed_path)
         geno = geno_int8.astype(np.float64)
         geno[geno_int8 == _BED_MISSING_INT8] = np.nan
+        if mode == "ploidy_scaled":
+            self._apply_ploidy_scaled(geno, _normalize_snp_indices(snp_indices, self._num_snp))
         return geno
 
+    def _apply_ploidy_scaled(self, geno: np.ndarray, indices: np.ndarray) -> None:
+        if indices.size == 0:
+            return
+        is_male = self._sex == 1
+        is_female = self._sex == 2
+        is_unknown = self._sex == 0
+        addressed = self._addressed_shards(indices)
+        for shard, cols, local_indices in addressed:
+            ploidy_male = shard.ploidy_male[local_indices]
+            ploidy_female = shard.ploidy_female[local_indices]
+            differs = ploidy_male != ploidy_female
+            unknown_present = is_unknown & shard.subject_present
+            if (
+                np.any(unknown_present)
+                and np.any(differs)
+                and np.any(np.isfinite(geno[np.ix_(unknown_present, cols[differs])]))
+            ):
+                raise ValueError(
+                    "GenotypePanel.fetch_genotypes: haploid_mode='ploidy_scaled' "
+                    "requires known FAM sex when male and female ploidy differ"
+                )
+            if np.any(is_male):
+                geno[np.ix_(is_male, cols)] *= ploidy_male.reshape(1, -1) / 2.0
+            if np.any(is_female):
+                geno[np.ix_(is_female, cols)] *= ploidy_female.reshape(1, -1) / 2.0
+            if np.any(is_unknown):
+                same_ploidy = ploidy_male.reshape(1, -1)
+                geno[np.ix_(is_unknown, cols)] *= same_ploidy / 2.0
+
     def save_cache(self, path, format=None) -> None:
         save_genotype_cache(self, path, format=format)
 
@@ -536,7 +583,15 @@ def _build_shard(ref_shard, source: _SourceRecord, subject_present, source_subje
             source_bim["a1_hash64"].to_numpy(dtype=np.uint64),
             source_bim["a2_hash64"].to_numpy(dtype=np.uint64),
         )
-        local_match = match_shard_numeric(ref_keys, src_keys, ref_shard.label, source_name="genotype")
+        local_match, n_swapped = match_shard_numeric(ref_keys, src_keys, ref_shard.label, source_name="genotype")
+        if n_swapped > 0:
+            warnings.warn(
+                f"{source.bim_path}: shard {ref_shard.label}: {n_swapped} unmatched genotype "
+                "variant(s) would match the reference if a1/a2 were swapped; "
+                "variants remain unmatched",
+                RuntimeWarning,
+                stacklevel=3,
+            )
 
     is_present = local_match >= 0
     source_row0 = np.full(int(ref_shard.num_snp), -1, dtype=np.int64)
@@ -589,7 +644,8 @@ def load_genotype(bfile_prefix, reference) -> GenotypePanel:
         shared = _load_source_record(prefix, None)
         if "X" in ref_labels and Path(prefix + ".ploidy").is_file() is False:
             warnings.warn(
-                f"{prefix}: chrX genotype source has no .ploidy sidecar; defaulting matched rows to diploid ploidy",
+                f"{prefix}: chrX genotype source has no .ploidy sidecar; "
+                "defaulting chrX rows to male/female ploidy (1, 2)",
                 RuntimeWarning,
                 stacklevel=2,
             )

{statgen-0.2.3 → statgen-0.2.4}/statgen/reference.py

@@ -12,6 +12,40 @@ from ._utils import CANONICAL_CHR_ORDER, allele_hash64, validate_requested_shard
 logger = logging.getLogger(__name__)
 
 _CACHE_SCHEMA = "reference_cache/0.1"
+_A_HASH64, _C_HASH64, _G_HASH64, _T_HASH64 = allele_hash64(
+    np.array(["A", "C", "G", "T"], dtype=object)
+)
+_SINGLE_BASE_HASH64 = np.array(
+    [_A_HASH64, _C_HASH64, _G_HASH64, _T_HASH64], dtype=np.uint64
+)
+
+
+def _is_single_nucleotide_variant(a1_hash64, a2_hash64) -> np.ndarray:
+    return np.isin(a1_hash64, _SINGLE_BASE_HASH64) & np.isin(
+        a2_hash64, _SINGLE_BASE_HASH64
+    )
+
+
+def _is_strand_ambiguous(a1_hash64, a2_hash64) -> np.ndarray:
+    a1 = np.asarray(a1_hash64, dtype=np.uint64).reshape(-1)
+    a2 = np.asarray(a2_hash64, dtype=np.uint64).reshape(-1)
+    return (
+        ((a1 == _A_HASH64) & (a2 == _T_HASH64))
+        | ((a1 == _T_HASH64) & (a2 == _A_HASH64))
+        | ((a1 == _C_HASH64) & (a2 == _G_HASH64))
+        | ((a1 == _G_HASH64) & (a2 == _C_HASH64))
+    )
+
+
+def _validate_distinct_alleles(label: str, a1_arr: np.ndarray, a2_arr: np.ndarray) -> None:
+    same = np.asarray(a1_arr, dtype=object).reshape(-1) == np.asarray(
+        a2_arr, dtype=object
+    ).reshape(-1)
+    if np.any(same):
+        idx0 = int(np.flatnonzero(same)[0])
+        raise ValueError(
+            f"Reference shard {label} variant {idx0 + 1}: a1 and a2 must differ"
+        )
 
 
 def _checksum_from_arrays(
@@ -56,6 +90,7 @@ class ReferenceShard:
             raise ValueError("ReferenceShard vector lengths must match")
         if self._chr.size and not np.all(self._chr == self._label):
             raise ValueError(f"Reference shard {self._label} contains multiple chr labels")
+        _validate_distinct_alleles(self._label, self._a1, self._a2)
         self._a1_hash64 = allele_hash64(self._a1)
         self._a2_hash64 = allele_hash64(self._a2)
         self._checksum = _checksum_from_arrays(self._chr, self._bp, self._a1, self._a2)
@@ -96,6 +131,14 @@ class ReferenceShard:
     def a2_hash64(self) -> np.ndarray:
         return self._a2_hash64
 
+    @property
+    def is_single_nucleotide_variant(self) -> np.ndarray:
+        return _is_single_nucleotide_variant(self._a1_hash64, self._a2_hash64)
+
+    @property
+    def is_strand_ambiguous(self) -> np.ndarray:
+        return _is_strand_ambiguous(self._a1_hash64, self._a2_hash64)
+
     @property
     def checksum(self) -> str:
         return self._checksum
@@ -130,6 +173,7 @@ class ReferenceShard:
             raise ValueError("Invalid reference cache: panel-wide vector lengths mismatch")
         if obj._chr.size and not np.all(obj._chr == obj._label):
             raise ValueError(f"Invalid reference cache: shard {obj._label} contains multiple chr labels")
+        _validate_distinct_alleles(obj._label, obj._a1, obj._a2)
         obj._a1_hash64 = (
             allele_hash64(obj._a1)
             if a1_hash64 is None
@@ -205,6 +249,18 @@ class ReferencePanel:
             return np.array([], dtype=np.uint64)
         return np.concatenate([s.a2_hash64 for s in self._shards])
 
+    @property
+    def is_single_nucleotide_variant(self) -> np.ndarray:
+        if not self._shards:
+            return np.array([], dtype=bool)
+        return np.concatenate([s.is_single_nucleotide_variant for s in self._shards])
+
+    @property
+    def is_strand_ambiguous(self) -> np.ndarray:
+        if not self._shards:
+            return np.array([], dtype=bool)
+        return np.concatenate([s.is_strand_ambiguous for s in self._shards])
+
     @property
     def shard_offsets(self) -> list:
         return list(self._shard_offsets)

{statgen-0.2.3 → statgen-0.2.4}/statgen/sumstats.py

@@ -328,7 +328,18 @@ def _build_sumstats_from_aligned(
     return Sumstats(shards)
 
 
-def _build_sumstats_panel(df: pd.DataFrame, reference) -> Sumstats:
+def _warn_swapped_allele_matches(source_path, shard_label: str, count: int, context: str) -> None:
+    if count > 0:
+        warnings.warn(
+            f"{source_path}: shard {shard_label}: {count} unmatched {context} "
+            "variant(s) would match the reference if a1/a2 were swapped; "
+            "variants remain unmatched",
+            RuntimeWarning,
+            stacklevel=3,
+        )
+
+
+def _build_sumstats_panel(df: pd.DataFrame, reference, source_path) -> Sumstats:
     n = int(reference.num_snp)
     aligned_optional = {
         col: (np.full(n, np.nan, dtype=float) if col in df.columns else None)
@@ -348,7 +359,8 @@ def _build_sumstats_panel(df: pd.DataFrame, reference) -> Sumstats:
         src_idx = np.flatnonzero(src_mask)
         ref_keys = numeric_variant_keys(ref_shard.bp, ref_shard.a1_hash64, ref_shard.a2_hash64)
         src_keys = numeric_variant_keys(src_bp[src_idx], src_a1_hash64[src_idx], src_a2_hash64[src_idx])
-        local_match = match_shard_numeric(ref_keys, src_keys, ref_shard.label, source_name="sumstats")
+        local_match, n_swapped = match_shard_numeric(ref_keys, src_keys, ref_shard.label, source_name="sumstats")
+        _warn_swapped_allele_matches(source_path, ref_shard.label, n_swapped, "sumstats")
         has_match = local_match >= 0
         matched_src = src_idx[local_match[has_match]]
         aligned_ix = np.arange(start, stop, dtype=np.int64)[has_match]
@@ -375,8 +387,8 @@ def _build_sumstats_panel(df: pd.DataFrame, reference) -> Sumstats:
 
 
 def load_sumstats(path, reference) -> Sumstats:
-    df = _parse_sumstats(Path(path))
-    return _build_sumstats_panel(df, reference)
+    path = Path(path)
+    return _build_sumstats_panel(_parse_sumstats(path), reference, path)
 
 
 def create_sumstats(

{statgen-0.2.3 → statgen-0.2.4}/statgen.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: statgen
-Version: 0.2.3
+Version: 0.2.4
 Summary: Statistical genetics data objects and loaders for Python and MATLAB/Octave.
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

statgen-0.2.3/statgen/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.2.3"