statgen 0.2.1__tar.gz → 0.2.2__tar.gz

{statgen-0.2.1 → statgen-0.2.2}/PKG-INFO

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

{statgen-0.2.1 → statgen-0.2.2}/pyproject.toml

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

statgen-0.2.2/statgen/__init__.py

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

statgen-0.2.2/statgen/_utils.py

@@ -0,0 +1,77 @@
+import warnings
+
+import numpy as np
+
+CANONICAL_CHR_ORDER = [str(i) for i in range(1, 23)] + ["X"]
+CHR_RANK = {c: i for i, c in enumerate(CANONICAL_CHR_ORDER)}
+_ALLELE_HASH_P = 2_147_483_647
+_ALLELE_HASH_BASE1 = 257
+_ALLELE_HASH_BASE2 = 263
+_ALLELE_HASH_MAX_CHARS = 150
+
+
+def validate_requested_shards(shards, available_labels, where: str) -> list[str]:
+    labels = list(available_labels)
+    if shards is None:
+        return labels
+    if isinstance(shards, str):
+        raise ValueError(f"{where}: shards must be a non-empty list of unique canonical contig labels")
+
+    requested = list(shards)
+    if not requested:
+        raise ValueError(f"{where}: shards must be a non-empty list of unique canonical contig labels")
+
+    seen = set()
+    prev_rank = None
+    for label in requested:
+        if label not in CHR_RANK:
+            raise ValueError(f"{where}: unsupported shard label {label!r}; expected canonical labels 1-22 or X")
+        if label in seen:
+            raise ValueError(f"{where}: duplicate shard label {label!r} in shards")
+        rank = CHR_RANK[label]
+        if prev_rank is not None and rank <= prev_rank:
+            raise ValueError(f"{where}: shards must be in canonical subsequence order")
+        seen.add(label)
+        prev_rank = rank
+        if label not in labels:
+            raise ValueError(f"{where}: requested shard {label!r} is not present")
+    return requested
+
+
+def allele_hash64(alleles) -> np.ndarray:
+    arr = np.asarray(alleles, dtype=object).reshape(-1)
+    n = arr.size
+    if n == 0:
+        return np.array([], dtype=np.uint64)
+
+    strings = [str(allele) for allele in arr]
+    lengths = np.fromiter((len(s) for s in strings), dtype=np.int64, count=n)
+    if np.any(lengths > _ALLELE_HASH_MAX_CHARS):
+        warnings.warn(
+            "Allele length exceeds 150 characters; hashing uses first 150 characters",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+        strings = [s[:_ALLELE_HASH_MAX_CHARS] for s in strings]
+        lengths = np.minimum(lengths, _ALLELE_HASH_MAX_CHARS)
+
+    encoded = [s.encode("utf-8") for s in strings]
+    byte_lengths = np.fromiter((len(b) for b in encoded), dtype=np.int64, count=n)
+    max_len = int(byte_lengths.max(initial=0))
+    mat = np.zeros((n, max_len), dtype=np.uint8)
+    if max_len:
+        flat = np.frombuffer(b"".join(encoded), dtype=np.uint8)
+        row_idx = np.repeat(np.arange(n, dtype=np.int64), byte_lengths)
+        starts = np.cumsum(byte_lengths, dtype=np.int64) - byte_lengths
+        col_idx = np.arange(flat.size, dtype=np.int64) - np.repeat(starts, byte_lengths)
+        mat[row_idx, col_idx] = flat
+
+    h1 = np.ones(n, dtype=np.int64)
+    h2 = np.ones(n, dtype=np.int64)
+    for j in range(max_len):
+        active = j < byte_lengths
+        x = mat[active, j].astype(np.int64) + 1
+        h1[active] = (h1[active] * _ALLELE_HASH_BASE1 + x) % _ALLELE_HASH_P
+        h2[active] = (h2[active] * _ALLELE_HASH_BASE2 + x) % _ALLELE_HASH_P
+
+    return (h1.astype(np.uint64) << np.uint64(32)) + h2.astype(np.uint64)

{statgen-0.2.1 → statgen-0.2.2}/statgen/reference.py

@@ -8,7 +8,7 @@ import numpy as np
 import pandas as pd
 from pandas.errors import ParserError
 
-from ._utils import CANONICAL_CHR_ORDER, CHR_RANK, validate_requested_shards
+from ._utils import CANONICAL_CHR_ORDER, CHR_RANK, allele_hash64, validate_requested_shards
 
 logger = logging.getLogger(__name__)
 
@@ -16,8 +16,6 @@ _CACHE_SCHEMA = "reference_cache/0.1"
 _BIM_NCOLS = 6
 _IGNORED_CHR = {"Y", "MT"}
 _DNA_ALLELE_RE = re.compile(r"^[ACGT]+$")
-
-
 def _validate_reference_sort_order(
     chr_col: pd.Series,
     bp_col: np.ndarray,
@@ -34,23 +32,21 @@ def _validate_reference_sort_order(
             f"{path}:{idx + 1}: chr must use canonical labels 1-22 or X"
         )
 
-    order_df = pd.DataFrame(
-        {
-            "chr_rank": chr_rank.to_numpy(dtype=np.int64),
-            "bp": np.asarray(bp_col, dtype=np.int64),
-            "a1": a1_col.to_numpy(dtype=object),
-            "a2": a2_col.to_numpy(dtype=object),
-            "line": np.asarray(line_numbers, dtype=np.int64),
-        }
-    )
+    order_df = pd.DataFrame({
+        "chr_rank": chr_rank.to_numpy(dtype=np.int64),
+        "bp": np.asarray(bp_col, dtype=np.int64),
+        "a1_hash64": allele_hash64(a1_col.to_numpy(dtype=object)),
+        "a2_hash64": allele_hash64(a2_col.to_numpy(dtype=object)),
+        "line": np.asarray(line_numbers, dtype=np.int64),
+    })
 
     dup_mask = order_df.duplicated(
-        subset=["chr_rank", "bp", "a1", "a2"], keep="first"
+        subset=["chr_rank", "bp", "a1_hash64", "a2_hash64"], keep="first"
     )
     if dup_mask.any():
         line = int(order_df.loc[dup_mask.idxmax(), "line"])
         raise ValueError(
-            f"{path}:{line}: duplicate (chr, bp, a1, a2) tuple is not allowed"
+            f"{path}:{line}: duplicate (chr, bp, a1_hash64, a2_hash64) matching key is not allowed"
         )
 
     prev = order_df.shift(1)
@@ -58,26 +54,14 @@ def _validate_reference_sort_order(
         (order_df["chr_rank"] < prev["chr_rank"])
         | (
             (order_df["chr_rank"] == prev["chr_rank"])
-            & (
-                (order_df["bp"] < prev["bp"])
-                | (
-                    (order_df["bp"] == prev["bp"])
-                    & (
-                        (order_df["a1"] < prev["a1"])
-                        | (
-                            (order_df["a1"] == prev["a1"])
-                            & (order_df["a2"] < prev["a2"])
-                        )
-                    )
-                )
-            )
+            & (order_df["bp"] < prev["bp"])
         )
     )
     bad_order = bad_order.fillna(False)
     if bad_order.any():
         line = int(order_df.loc[bad_order.idxmax(), "line"])
         raise ValueError(
-            f"{path}:{line}: rows must be sorted by (chr_rank, bp, a1, a2) in canonical contig order"
+            f"{path}:{line}: rows must be sorted by (chr_rank, bp) in canonical contig order"
         )
 
 
@@ -221,6 +205,18 @@ class ReferenceShard:
         self._bp = np.asarray(bp_arr, dtype=np.int64)
         self._a1 = np.asarray(a1_arr, dtype=object)
         self._a2 = np.asarray(a2_arr, dtype=object)
+        if not (
+            self._chr.size
+            == self._snp.size
+            == self._bp.size
+            == self._a1.size
+            == self._a2.size
+        ):
+            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")
+        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)
 
     @property
@@ -251,12 +247,31 @@ class ReferenceShard:
     def a2(self) -> np.ndarray:
         return self._a2
 
+    @property
+    def a1_hash64(self) -> np.ndarray:
+        return self._a1_hash64
+
+    @property
+    def a2_hash64(self) -> np.ndarray:
+        return self._a2_hash64
+
     @property
     def checksum(self) -> str:
         return self._checksum
 
     @classmethod
-    def _from_arrays(cls, label, chr_arr, snp_arr, bp_arr, a1_arr, a2_arr, checksum):
+    def _from_arrays(
+        cls,
+        label,
+        chr_arr,
+        snp_arr,
+        bp_arr,
+        a1_arr,
+        a2_arr,
+        checksum,
+        a1_hash64=None,
+        a2_hash64=None,
+    ):
         obj = cls.__new__(cls)
         obj._label = label
         obj._chr = np.asarray(chr_arr, dtype=object)
@@ -264,6 +279,28 @@ class ReferenceShard:
         obj._bp = np.asarray(bp_arr, dtype=np.int64)
         obj._a1 = np.asarray(a1_arr, dtype=object)
         obj._a2 = np.asarray(a2_arr, dtype=object)
+        if not (
+            obj._chr.size
+            == obj._snp.size
+            == obj._bp.size
+            == obj._a1.size
+            == obj._a2.size
+        ):
+            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")
+        obj._a1_hash64 = (
+            allele_hash64(obj._a1)
+            if a1_hash64 is None
+            else np.asarray(a1_hash64, dtype=np.uint64).reshape(-1)
+        )
+        obj._a2_hash64 = (
+            allele_hash64(obj._a2)
+            if a2_hash64 is None
+            else np.asarray(a2_hash64, dtype=np.uint64).reshape(-1)
+        )
+        if obj._a1_hash64.size != obj._bp.size or obj._a2_hash64.size != obj._bp.size:
+            raise ValueError("Invalid reference cache: allele hash vector lengths mismatch")
         obj._checksum = checksum
         return obj
 
@@ -313,6 +350,18 @@ class ReferencePanel:
             return np.array([], dtype=object)
         return np.concatenate([s.a2 for s in self._shards])
 
+    @property
+    def a1_hash64(self) -> np.ndarray:
+        if not self._shards:
+            return np.array([], dtype=np.uint64)
+        return np.concatenate([s.a1_hash64 for s in self._shards])
+
+    @property
+    def a2_hash64(self) -> np.ndarray:
+        if not self._shards:
+            return np.array([], dtype=np.uint64)
+        return np.concatenate([s.a2_hash64 for s in self._shards])
+
     @property
     def shard_offsets(self) -> list:
         return list(self._shard_offsets)
@@ -327,6 +376,13 @@ class ReferencePanel:
         by_label = {s.label: s for s in self._shards}
         return ReferencePanel([by_label[label] for label in selected])
 
+    def validate_checksums(self) -> bool:
+        for shard in self._shards:
+            computed = _checksum_from_arrays(shard.chr, shard.bp, shard.a1, shard.a2)
+            if computed != shard.checksum:
+                raise ValueError(f"Reference checksum mismatch for shard {shard.label}")
+        return True
+
     def is_object_compatible(self, obj) -> bool:
         log_fn = logger.warning
 
@@ -441,12 +497,18 @@ def load_reference(path, shards=None) -> ReferencePanel:
     return ReferencePanel(out_shards)
 
 
-def save_reference_cache(panel: ReferencePanel, path) -> None:
+def save_reference_cache(panel: ReferencePanel, path, mode: str = "full") -> None:
+    mode = str(mode).lower()
+    if mode not in {"full", "thin"}:
+        raise ValueError("save_reference_cache mode must be 'full' or 'thin'")
+
     # Metadata (schema, labels, checksums) as a compact JSON blob stored in the npz.
     # SNP-axis numeric vectors (bp) and string arrays are stored as native
     # binary numpy arrays — not JSON — per the performance contract.
+    # Python keeps reference caches full even when mode='thin' is requested.
     meta = {
         "schema": _CACHE_SCHEMA,
+        "mode": "full",
         "shard_labels": [s.label for s in panel.shards],
         "shard_checksums": [s.checksum for s in panel.shards],
     }
@@ -460,6 +522,8 @@ def save_reference_cache(panel: ReferencePanel, path) -> None:
         arrays[p + "bp"]  = s.bp
         arrays[p + "a1"]  = np.asarray(s.a1, dtype=str)
         arrays[p + "a2"]  = np.asarray(s.a2, dtype=str)
+        arrays[p + "a1_hash64"] = s.a1_hash64
+        arrays[p + "a2_hash64"] = s.a2_hash64
     np.savez_compressed(path, **arrays)
 
 
@@ -469,6 +533,11 @@ def load_reference_cache(path, shards=None) -> ReferencePanel:
         schema = meta.get("schema")
         if schema != _CACHE_SCHEMA:
             raise ValueError(f"Unsupported reference cache schema: {schema!r}")
+        mode = meta.get("mode")
+        if mode is None:
+            raise ValueError("reference cache missing mode; delete and rebuild old cache")
+        if mode != "full":
+            raise ValueError(f"Unsupported Python reference cache mode: {mode!r}")
 
         labels = list(meta.get("shard_labels", []))
         checksums = list(meta.get("shard_checksums", []))
@@ -481,6 +550,8 @@ def load_reference_cache(path, shards=None) -> ReferencePanel:
         for label in selected:
             i = label_to_index[label]
             p = f"s{i}_"
+            if p + "a1_hash64" not in data or p + "a2_hash64" not in data:
+                raise ValueError("reference cache missing a1_hash64/a2_hash64; rebuild cache")
             shard_objs.append(
                 ReferenceShard._from_arrays(
                     label,
@@ -490,6 +561,8 @@ def load_reference_cache(path, shards=None) -> ReferencePanel:
                     data[p + "a1"],
                     data[p + "a2"],
                     checksums[i],
+                    data[p + "a1_hash64"],
+                    data[p + "a2_hash64"],
                 )
             )
     return ReferencePanel(shard_objs)

{statgen-0.2.1 → statgen-0.2.2}/statgen/sumstats.py

@@ -5,20 +5,77 @@ import numpy as np
 import pandas as pd
 from pandas.errors import ParserError
 
-from ._utils import validate_requested_shards
+from ._utils import allele_hash64, validate_requested_shards
 
 _CACHE_SCHEMA = "sumstats_cache/0.1"
 _REQUIRED_COLS = ("chr", "bp", "a1", "a2", "z", "n")
 _OPTIONAL_COLS = ("p", "beta", "se", "eaf", "info")
+_SUMSTATS_COL_MAP = {
+    "pos": "bp",
+    "effectallele": "a1",
+    "otherallele": "a2",
+}
+
+
+_KEY_DTYPE = np.dtype([("bp", "<i8"), ("a1_hash64", "<u8"), ("a2_hash64", "<u8")])
+
+
+def _numeric_keys(bp_arr, a1_hash64, a2_hash64) -> np.ndarray:
+    bp = np.asarray(bp_arr, dtype=np.int64).reshape(-1)
+    a1h = np.asarray(a1_hash64, dtype=np.uint64).reshape(-1)
+    a2h = np.asarray(a2_hash64, dtype=np.uint64).reshape(-1)
+    if not (bp.size == a1h.size == a2h.size):
+        raise ValueError("numeric key vector lengths mismatch")
+    keys = np.empty(bp.size, dtype=_KEY_DTYPE)
+    keys["bp"] = bp
+    keys["a1_hash64"] = a1h
+    keys["a2_hash64"] = a2h
+    return keys
+
+
+def _check_unique_sorted_keys(sorted_keys: np.ndarray, where: str) -> None:
+    if sorted_keys.size < 2:
+        return
+    dup = sorted_keys[1:] == sorted_keys[:-1]
+    if np.any(dup):
+        pos = int(np.flatnonzero(dup)[0] + 1)
+        key = sorted_keys[pos]
+        raise ValueError(
+            f"Ambiguous duplicate sumstats/reference matching key in {where}: "
+            f"bp={int(key['bp'])}, a1_hash64={int(key['a1_hash64'])}, "
+            f"a2_hash64={int(key['a2_hash64'])}"
+        )
 
 
-def _key_from_arrays(chr_arr, bp_arr, a1_arr, a2_arr) -> pd.Series:
-    return (
-        pd.Series(chr_arr, dtype="string")
-        .str.cat(pd.Series(bp_arr, dtype=np.int64).astype("string"), sep=":")
-        .str.cat(pd.Series(a1_arr, dtype="string"), sep=":")
-        .str.cat(pd.Series(a2_arr, dtype="string"), sep=":")
-    )
+def _match_shard_numeric(ref_keys: np.ndarray, src_keys: np.ndarray, shard_label: str) -> np.ndarray:
+    if src_keys.size == 0:
+        return np.full(ref_keys.size, -1, dtype=np.int64)
+
+    ref_order = np.argsort(ref_keys, kind="mergesort", order=("bp", "a1_hash64", "a2_hash64"))
+    src_order = np.argsort(src_keys, kind="mergesort", order=("bp", "a1_hash64", "a2_hash64"))
+    ref_sorted = ref_keys[ref_order]
+    src_sorted = src_keys[src_order]
+    _check_unique_sorted_keys(ref_sorted, f"reference shard {shard_label}")
+    _check_unique_sorted_keys(src_sorted, f"sumstats shard {shard_label}")
+
+    pos = np.searchsorted(src_sorted, ref_keys)
+    in_range = pos < src_sorted.size
+    matched = np.zeros(ref_keys.size, dtype=bool)
+    matched[in_range] = src_sorted[pos[in_range]] == ref_keys[in_range]
+
+    out = np.full(ref_keys.size, -1, dtype=np.int64)
+    out[matched] = src_order[pos[matched]]
+    return out
+
+
+def _canonicalize_columns(df: pd.DataFrame, path: Path) -> pd.DataFrame:
+    columns = [_SUMSTATS_COL_MAP.get(str(c).lower(), str(c).lower()) for c in df.columns]
+    duplicates = sorted({c for c in columns if columns.count(c) > 1})
+    if duplicates:
+        raise ValueError(f"{path}: duplicate columns after column normalization: {', '.join(duplicates)}")
+    out = df.copy()
+    out.columns = columns
+    return out
 
 
 def _parse_sumstats(path: Path) -> pd.DataFrame:
@@ -34,6 +91,8 @@ def _parse_sumstats(path: Path) -> pd.DataFrame:
     except ParserError as exc:
         raise ValueError(f"{path}: malformed TSV") from exc
 
+    df = _canonicalize_columns(df, path)
+
     missing = [c for c in _REQUIRED_COLS if c not in df.columns]
     if missing:
         raise ValueError(f"{path}: missing required columns: {', '.join(missing)}")
@@ -289,40 +348,45 @@ def _build_sumstats_from_aligned(
 
 
 def _build_sumstats_panel(df: pd.DataFrame, reference) -> Sumstats:
-    ref_chr = np.asarray(reference.chr, dtype=object)
-    ref_bp = np.asarray(reference.bp, dtype=np.int64)
-    ref_a1 = np.asarray(reference.a1, dtype=object)
-    ref_a2 = np.asarray(reference.a2, dtype=object)
-    ref_keys = _key_from_arrays(ref_chr, ref_bp, ref_a1, ref_a2)
-
-    src_keys = _key_from_arrays(
-        df["chr"].to_numpy(dtype=object),
-        df["bp"].to_numpy(dtype=np.int64),
-        df["a1"].to_numpy(dtype=object),
-        df["a2"].to_numpy(dtype=object),
-    )
-    src = df.copy()
-    src["_key"] = src_keys
-
-    key_to = {}
-    for col in ("z", "n") + _OPTIONAL_COLS:
-        if col in src.columns:
-            key_to[col] = src.set_index("_key")[col]
-
-    aligned_z = key_to["z"].reindex(ref_keys).to_numpy(dtype=float)
-    aligned_n = key_to["n"].reindex(ref_keys).to_numpy(dtype=float)
-    if "p" in key_to:
-        aligned_p = key_to["p"].reindex(ref_keys).to_numpy(dtype=float)
-        aligned_logp = _derive_logp(aligned_p)
+    n = int(reference.num_snp)
+    aligned_z = np.full(n, np.nan, dtype=float)
+    aligned_n = np.full(n, np.nan, dtype=float)
+    aligned_p = np.full(n, np.nan, dtype=float) if "p" in df.columns else None
+
+    aligned_optional = {
+        col: (np.full(n, np.nan, dtype=float) if col in df.columns else None)
+        for col in ("beta", "se", "eaf", "info")
+    }
+
+    src_chr = df["chr"].to_numpy(dtype=object)
+    src_bp = df["bp"].to_numpy(dtype=np.int64)
+    src_a1_hash64 = allele_hash64(df["a1"].to_numpy(dtype=object))
+    src_a2_hash64 = allele_hash64(df["a2"].to_numpy(dtype=object))
+
+    for ref_shard, off in zip(reference.shards, reference.shard_offsets):
+        start = int(off["start0"])
+        stop = int(off["stop0"])
+        src_mask = src_chr == ref_shard.label
+        src_idx = np.flatnonzero(src_mask)
+        ref_keys = _numeric_keys(ref_shard.bp, ref_shard.a1_hash64, ref_shard.a2_hash64)
+        src_keys = _numeric_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)
+        has_match = local_match >= 0
+        matched_src = src_idx[local_match[has_match]]
+        aligned_ix = np.arange(start, stop, dtype=np.int64)[has_match]
+
+        aligned_z[aligned_ix] = df["z"].to_numpy(dtype=float)[matched_src]
+        aligned_n[aligned_ix] = df["n"].to_numpy(dtype=float)[matched_src]
+        if aligned_p is not None:
+            aligned_p[aligned_ix] = df["p"].to_numpy(dtype=float)[matched_src]
+        for col, out in aligned_optional.items():
+            if out is not None:
+                out[aligned_ix] = df[col].to_numpy(dtype=float)[matched_src]
+
+    if aligned_p is None:
+        aligned_logp = np.full(n, np.nan, dtype=float)
     else:
-        aligned_logp = np.full(ref_keys.size, np.nan, dtype=float)
-
-    aligned_optional = {}
-    for col in ("beta", "se", "eaf", "info"):
-        if col in key_to:
-            aligned_optional[col] = key_to[col].reindex(ref_keys).to_numpy(dtype=float)
-        else:
-            aligned_optional[col] = None
+        aligned_logp = _derive_logp(aligned_p)
 
     return _build_sumstats_from_aligned(
         reference,

{statgen-0.2.1 → statgen-0.2.2}/statgen.egg-info/PKG-INFO

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

statgen-0.2.1/statgen/__init__.py

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

statgen-0.2.1/statgen/_utils.py

@@ -1,30 +0,0 @@
-CANONICAL_CHR_ORDER = [str(i) for i in range(1, 23)] + ["X"]
-CHR_RANK = {c: i for i, c in enumerate(CANONICAL_CHR_ORDER)}
-
-
-def validate_requested_shards(shards, available_labels, where: str) -> list[str]:
-    labels = list(available_labels)
-    if shards is None:
-        return labels
-    if isinstance(shards, str):
-        raise ValueError(f"{where}: shards must be a non-empty list of unique canonical contig labels")
-
-    requested = list(shards)
-    if not requested:
-        raise ValueError(f"{where}: shards must be a non-empty list of unique canonical contig labels")
-
-    seen = set()
-    prev_rank = None
-    for label in requested:
-        if label not in CHR_RANK:
-            raise ValueError(f"{where}: unsupported shard label {label!r}; expected canonical labels 1-22 or X")
-        if label in seen:
-            raise ValueError(f"{where}: duplicate shard label {label!r} in shards")
-        rank = CHR_RANK[label]
-        if prev_rank is not None and rank <= prev_rank:
-            raise ValueError(f"{where}: shards must be in canonical subsequence order")
-        seen.add(label)
-        prev_rank = rank
-        if label not in labels:
-            raise ValueError(f"{where}: requested shard {label!r} is not present")
-    return requested