fix: document new params via Annotated types and @doc parameters dict

- Define min_snps_threshold and window_adjustment_factor as Annotated
  TypeAlias in fst_params.py so numpydoc_decorator 2.2.1 can extract
  their documentation automatically (plain int params without Annotated
  or explicit parameters dict cause DocumentationError at import time)
- Add explicit parameters dict entries to @doc(fst_gwss) as belt-and-
  suspenders documentation for both new parameters
- Switch fst_gwss signature from plain int to fst_params.min_snps_threshold
  and fst_params.window_adjustment_factor (consistent with codebase style)
- Replace unseeded random.choice/random.sample in new tests with seeded
  np.random.choice (matching all existing tests that use np.random seeded
  with 42 via the autouse session fixture)
- Remove import random from test_fst.py (no longer needed)

Author: suhr25

malariagen_data/anoph/fst.py

@@ -123,6 +123,17 @@ def _fst_gwss(
             is raised if the number of available SNP sites is below
             min_snps_threshold.
         """,
+        parameters=dict(
+            min_snps_threshold="""
+                Minimum number of SNP sites required. If fewer sites are
+                available a ValueError is raised.
+            """,
+            window_adjustment_factor="""
+                If window_size is >= the number of available SNP sites,
+                window_size is automatically set to
+                number_of_snps // window_adjustment_factor.
+            """,
+        ),
         returns=dict(
             x="An array containing the window centre point genomic positions",
             fst="An array with Fst statistic values for each window.",
@@ -148,8 +159,8 @@ def fst_gwss(
         inline_array: base_params.inline_array = base_params.inline_array_default,
         chunks: base_params.chunks = base_params.native_chunks,
         clip_min: fst_params.clip_min = 0.0,
-        min_snps_threshold: int = 1000,
-        window_adjustment_factor: int = 10,
+        min_snps_threshold: fst_params.min_snps_threshold = 1000,
+        window_adjustment_factor: fst_params.window_adjustment_factor = 10,
     ) -> Tuple[np.ndarray, np.ndarray]:
         # Change this name if you ever change the behaviour of this function, to
         # invalidate any previously cached data.

malariagen_data/anoph/fst_params.py

@@ -34,6 +34,22 @@
     """,
 ]
 
+min_snps_threshold: TypeAlias = Annotated[
+    int,
+    """
+    Minimum number of SNP sites required for the Fst GWSS computation. If
+    fewer sites are available, a ValueError is raised.
+    """,
+]
+
+window_adjustment_factor: TypeAlias = Annotated[
+    int,
+    """
+    If window_size is >= the number of available SNP sites, the window_size
+    is automatically adjusted to number_of_snps // window_adjustment_factor.
+    """,
+]
+
 annotation: TypeAlias = Annotated[
     Optional[Literal["standard error", "Z score", "lower triangle"]],
     """

tests/anoph/test_fst.py

@@ -1,5 +1,4 @@
 import itertools
-import random
 import pytest
 from pytest_cases import parametrize_with_cases
 import numpy as np
@@ -146,16 +145,16 @@ def test_fst_gwss_window_size_too_large(fixture, api: AnophelesFstAnalysis):
     # the function must still return a valid result using the adjusted window_size.
     all_sample_sets = api.sample_sets()["sample_set"].to_list()
     all_countries = api.sample_metadata()["country"].dropna().unique().tolist()
-    countries = random.sample(all_countries, 2)
+    countries = np.random.choice(all_countries, size=2, replace=False).tolist()
     cohort1_query = f"country == {countries[0]!r}"
     cohort2_query = f"country == {countries[1]!r}"
     with pytest.warns(UserWarning, match="window_size"):
         x, fst = api.fst_gwss(
-            contig=random.choice(api.contigs),
+            contig=str(np.random.choice(api.contigs)),
             sample_sets=all_sample_sets,
             cohort1_query=cohort1_query,
             cohort2_query=cohort2_query,
-            site_mask=random.choice(api.site_mask_ids),
+            site_mask=str(np.random.choice(api.site_mask_ids)),
             window_size=10_000_000,  # far larger than any fixture SNP count
             min_cohort_size=1,
         )
@@ -170,16 +169,16 @@ def test_fst_gwss_too_few_snps(fixture, api: AnophelesFstAnalysis):
     # When min_snps_threshold exceeds available SNPs, a ValueError must be raised.
     all_sample_sets = api.sample_sets()["sample_set"].to_list()
     all_countries = api.sample_metadata()["country"].dropna().unique().tolist()
-    countries = random.sample(all_countries, 2)
+    countries = np.random.choice(all_countries, size=2, replace=False).tolist()
     cohort1_query = f"country == {countries[0]!r}"
     cohort2_query = f"country == {countries[1]!r}"
     with pytest.raises(ValueError, match="Too few SNP sites"):
         api.fst_gwss(
-            contig=random.choice(api.contigs),
+            contig=str(np.random.choice(api.contigs)),
             sample_sets=all_sample_sets,
             cohort1_query=cohort1_query,
             cohort2_query=cohort2_query,
-            site_mask=random.choice(api.site_mask_ids),
+            site_mask=str(np.random.choice(api.site_mask_ids)),
             window_size=100,
             min_cohort_size=1,
             min_snps_threshold=10_000_000,  # far larger than any fixture SNP count (~28k-70k)