Merge branch 'master' into GH-1054-add-vcf-export

Author: adilraza99

README.md

@@ -49,6 +49,7 @@ To get setup for development, see [this video if you prefer VS Code](https://you
 For detailed setup instructions, see:
 - [Linux setup guide](LINUX_SETUP.md)
 - [macOS setup guide](MACOS_SETUP.md)
+- [Windows setup guide](WINDOWS_SETUP.md)
 - [Google Colab (TPU) setup guide](docs/source/colab_tpu_runtime.rst)
 Detailed instructions can be found in the [Contributors guide](https://github.com/malariagen/malariagen-data-python/blob/master/CONTRIBUTING.md).
 

WINDOWS_SETUP.md

@@ -0,0 +1,90 @@
+# Windows Setup Guide
+
+To get setup for development on Windows, see
+[this video if you prefer VS Code](https://youtu.be/zddl3n1DCFM),
+or [this older video if you prefer PyCharm](https://youtu.be/QniQi-Hoo9A),
+and the instructions below.
+
+## 1. Fork and clone this repo
+```bash
+git clone https://github.com/[username]/malariagen-data-python.git
+cd malariagen-data-python
+```
+
+## 2. Install Python
+
+Download and install Python 3.10 from the official website:
+https://www.python.org/downloads/windows/
+
+During installation, check the box that says Add Python to PATH
+before clicking Install.
+
+Verify the installation worked:
+```bash
+python --version
+```
+
+## 3. Install pipx and poetry
+```bash
+python -m pip install --user pipx
+python -m pipx ensurepath
+pipx install poetry
+```
+
+After running ensurepath, close and reopen PowerShell before continuing.
+
+## 4. Create and activate development environment
+```bash
+poetry install
+poetry shell
+```
+
+## 5. Install pre-commit hooks
+```bash
+pipx install pre-commit
+pre-commit install
+```
+
+## 6. Add upstream remote and get latest code
+```bash
+git remote add upstream https://github.com/malariagen/malariagen-data-python
+git pull upstream master
+```
+
+Note: On Windows the default branch is called master, not main.
+
+## 7. Verify everything works
+```bash
+python -c "import malariagen_data; print('Setup successful!')"
+```
+
+## Common Issues on Windows
+
+**poetry not found after install**
+
+Close and reopen PowerShell, then try again.
+
+**git not recognized**
+
+Install Git from https://git-scm.com/download/win
+and restart PowerShell.
+
+**python not recognized**
+
+Reinstall Python and make sure to check
+Add Python to PATH during installation.
+
+**fatal: not a git repository**
+
+Make sure you are inside the malariagen-data-python
+folder before running any git commands.
+```bash
+cd malariagen-data-python
+```
+
+**error: pathspec main did not match**
+
+On Windows use master instead of main.
+```bash
+git checkout master
+```

malariagen_data/ag3.py

@@ -212,6 +212,7 @@ def __init__(
             taxon_colors=TAXON_COLORS,
             aim_species_colors=AIM_SPECIES_COLORS,
             virtual_contigs=VIRTUAL_CONTIGS,
+            gene_names=GENE_NAMES,
             inversion_tag_path=INVERSION_TAG_PATH,
             unrestricted_use_only=unrestricted_use_only,
             surveillance_use_only=surveillance_use_only,

malariagen_data/anoph/heterozygosity.py

@@ -399,6 +399,27 @@ def _sample_count_het(
     def _roh_hmm_cache_name(self):
         return "roh_hmm_v1"
 
+    def _get_roh_hmm_cache_name(self):
+        """Safely resolve the ROH HMM cache name.
+
+        Supports class attribute, property, or legacy method override.
+        Falls back to the default "roh_hmm_v1" if resolution fails.
+
+        See also: https://github.com/malariagen/malariagen-data-python/issues/1151
+        """
+        try:
+            name = self._roh_hmm_cache_name
+            # Handle legacy case where _roh_hmm_cache_name might be a
+            # callable method rather than a property or class attribute.
+            if callable(name):
+                name = name()
+            if isinstance(name, str) and len(name) > 0:
+                return name
+        except NotImplementedError:
+            pass
+        # Fallback to default.
+        return "roh_hmm_v1"
+
     @_check_types
     @doc(
         summary="Infer runs of homozygosity for a single sample over a genome region.",
@@ -420,7 +441,7 @@ def roh_hmm(
 
         resolved_region: Region = _parse_single_region(self, region)
 
-        name = self._roh_hmm_cache_name
+        name = self._get_roh_hmm_cache_name()
 
         params = dict(
             sample=sample,

malariagen_data/anoph/pca.py

@@ -399,9 +399,9 @@ def plot_pca_coords(
 
         # Apply jitter if desired - helps spread out points when tightly clustered.
         if jitter_frac:
-            np.random.seed(random_seed)
-            data[x] = _jitter(data[x], jitter_frac)
-            data[y] = _jitter(data[y], jitter_frac)
+            rng = np.random.default_rng(seed=random_seed)
+            data[x] = _jitter(data[x], jitter_frac, random_state=rng)
+            data[y] = _jitter(data[y], jitter_frac, random_state=rng)
 
         # Convenience variables.
         # Prevent lint error (mypy): Unsupported operand types for + ("Series[Any]" and "str")
@@ -503,10 +503,10 @@ def plot_pca_coords_3d(
 
         # Apply jitter if desired - helps spread out points when tightly clustered.
         if jitter_frac:
-            np.random.seed(random_seed)
-            data[x] = _jitter(data[x], jitter_frac)
-            data[y] = _jitter(data[y], jitter_frac)
-            data[z] = _jitter(data[z], jitter_frac)
+            rng = np.random.default_rng(seed=random_seed)
+            data[x] = _jitter(data[x], jitter_frac, random_state=rng)
+            data[y] = _jitter(data[y], jitter_frac, random_state=rng)
+            data[z] = _jitter(data[z], jitter_frac, random_state=rng)
 
         # Convenience variables.
         # Prevent lint error (mypy): Unsupported operand types for + ("Series[Any]" and "str")

malariagen_data/anopheles.py

@@ -138,6 +138,7 @@ def __init__(
         taxon_colors: Optional[Mapping[str, str]] = None,
         aim_species_colors: Optional[Mapping[str, str]] = None,
         virtual_contigs: Optional[Mapping[str, Sequence[str]]] = None,
+        gene_names: Optional[Mapping[str, str]] = None,
         inversion_tag_path: Optional[str] = None,
         unrestricted_use_only: Optional[bool] = None,
         surveillance_use_only: Optional[bool] = None,
@@ -175,6 +176,7 @@ def __init__(
             taxon_colors=taxon_colors,
             aim_species_colors=aim_species_colors,
             virtual_contigs=virtual_contigs,
+            gene_names=gene_names,
             inversion_tag_path=inversion_tag_path,
             unrestricted_use_only=unrestricted_use_only,
             surveillance_use_only=surveillance_use_only,

malariagen_data/util.py

@@ -570,6 +570,9 @@ def __eq__(self, other):
             and (self.end == other.end)
         )
 
+    def __repr__(self):
+        return f"Region({self._contig!r}, {self._start!r}, {self._end!r})"
+
     def __str__(self):
         out = self._contig
         if self._start is not None or self._end is not None:
@@ -897,14 +900,50 @@ def _hash_params(params):
     return h, s
 
 
-def _jitter(a, fraction):
-    """Jitter data in `a` using the fraction `f`."""
+def _jitter(a, fraction, random_state=np.random):
+    """Jitter data by adding uniform noise scaled by the data range.
+
+    Parameters
+    ----------
+    a : array-like
+        Input data to jitter. Can be a numpy array or pandas Series.
+    fraction : float
+        Controls the amplitude of the jitter relative to the data range.
+    random_state : numpy.random.Generator or module, optional
+        Random number generator to use. Accepts a ``numpy.random.Generator``
+        (from ``np.random.default_rng()``) or the ``numpy.random`` module.
+        Defaults to ``np.random`` (global RNG) for backward compatibility.
+
+    Returns
+    -------
+    array-like
+        Jittered copy of the input data with the same shape and type.
+
+    Notes
+    -----
+    Prefer passing a local ``np.random.default_rng(seed=...)`` to avoid
+    mutating global RNG state and to ensure reproducibility.
+
+    """
     r = a.max() - a.min()
-    return a + fraction * np.random.uniform(-r, r, a.shape)
+    return a + fraction * random_state.uniform(-r, r, a.shape)
 
 
 class CacheMiss(Exception):
-    pass
+    """Raised when a requested item is not present in the cache."""
+
+    def __init__(self, key=None):
+        self.key = key
+        if key is not None:
+            message = f"Cache miss for key: {key!r}"
+        else:
+            message = "Cache miss: requested item not found in cache."
+        super().__init__(message)
+
+    def __repr__(self):
+        if self.key is not None:
+            return f"CacheMiss({self.key!r})"
+        return "CacheMiss()"
 
 
 class LoggingHelper:
@@ -1508,12 +1547,10 @@ def _apply_allele_mapping(x, mapping, max_allele):
 
 def _dask_apply_allele_mapping(v, mapping, max_allele):
     if not isinstance(v, da.Array):
-        raise TypeError(
-            f"Expected v to be a dask.array.Array, " f"got {type(v).__name__}"
-        )
+        raise TypeError(f"Expected v to be a dask.array.Array, got {type(v).__name__}")
     if not isinstance(mapping, np.ndarray):
         raise TypeError(
-            f"Expected mapping to be a numpy.ndarray, " f"got {type(mapping).__name__}"
+            f"Expected mapping to be a numpy.ndarray, got {type(mapping).__name__}"
         )
     assert v.ndim == 2
     assert mapping.ndim == 2
@@ -1535,12 +1572,10 @@ def _genotype_array_map_alleles(gt, mapping):
     # N.B., scikit-allel does not handle empty blocks well, so we
     # include some extra logic to handle that better.
     if not isinstance(gt, np.ndarray):
-        raise TypeError(
-            f"Expected gt to be a numpy.ndarray, " f"got {type(gt).__name__}"
-        )
+        raise TypeError(f"Expected gt to be a numpy.ndarray, got {type(gt).__name__}")
     if not isinstance(mapping, np.ndarray):
         raise TypeError(
-            f"Expected mapping to be a numpy.ndarray, " f"got {type(mapping).__name__}"
+            f"Expected mapping to be a numpy.ndarray, got {type(mapping).__name__}"
         )
     assert gt.ndim == 3
     assert mapping.ndim == 3
@@ -1562,11 +1597,11 @@ def _genotype_array_map_alleles(gt, mapping):
 def _dask_genotype_array_map_alleles(gt, mapping):
     if not isinstance(gt, da.Array):
         raise TypeError(
-            f"Expected gt to be a dask.array.Array, " f"got {type(gt).__name__}"
+            f"Expected gt to be a dask.array.Array, got {type(gt).__name__}"
         )
     if not isinstance(mapping, np.ndarray):
         raise TypeError(
-            f"Expected mapping to be a numpy.ndarray, " f"got {type(mapping).__name__}"
+            f"Expected mapping to be a numpy.ndarray, got {type(mapping).__name__}"
         )
     assert gt.ndim == 3
     assert mapping.ndim == 2

tests/anoph/test_fst.py

@@ -346,8 +346,16 @@ def test_pairwise_average_fst_with_sample_query(fixture, api: AnophelesFstAnalys
         n_jack=random.randint(10, 200),
     )
 
-    # Run checks.
-    check_pairwise_average_fst(api=api, fst_params=fst_params)
+    # Run checks - skip if random parameter selection results in insufficient cohorts.
+    try:
+        check_pairwise_average_fst(api=api, fst_params=fst_params)
+    except ValueError as e:
+        if "No cohorts remain" in str(e):
+            pytest.skip(
+                f"Skipping: random parameter selection produced insufficient "
+                f"cohorts for taxon={taxon!r}: {e}"
+            )
+        raise
 
 
 @parametrize_with_cases("fixture,api", cases=".")

tests/anoph/test_hap_frq.py

@@ -187,7 +187,12 @@ def test_hap_frequencies_with_str_cohorts(
         return
 
     # Run the function under test.
-    df_hap = api.haplotypes_frequencies(**params)
+    try:
+        df_hap = api.haplotypes_frequencies(**params)
+    except ValueError as e:
+        if "No SNPs available for the given region" in str(e):
+            pytest.skip("Random region contained no SNPs")
+        raise
 
     check_plot_frequencies_heatmap(api, df_hap)
 

tests/anoph/test_heterozygosity.py

@@ -185,6 +185,19 @@ def test_roh_hmm(fixture, api: AnophelesHetAnalysis):
         assert col in df_roh.columns
 
 
+@parametrize_with_cases("fixture,api", cases=".")
+def test_roh_hmm_cache_name_resolution(fixture, api: AnophelesHetAnalysis):
+    """Regression test for GH#1151: _roh_hmm_cache_name must resolve to a string.
+
+    Verifies that the cache name resolver handles class attributes, properties,
+    and legacy method overrides without raising NotImplementedError.
+    """
+    # The resolver should always return a non-empty string.
+    name = api._get_roh_hmm_cache_name()
+    assert isinstance(name, str), f"Expected str, got {type(name)}"
+    assert len(name) > 0, "Cache name must be non-empty"
+
+
 @parametrize_with_cases("fixture,api", cases=".")
 def test_plot_roh(fixture, api: AnophelesHetAnalysis):
     # Set up test parameters.