Merge branch 'master' into docs/plot-frequencies-time-series-params

Author: jonbrenas

.github/actions/setup-python/action.yaml

@@ -19,4 +19,4 @@ runs:
       shell: bash
       run: |
         poetry env use ${{ inputs.python-version }}
-        poetry install --extras dev
+        poetry install --with dev,test,docs

.gitignore

@@ -1,8 +1,10 @@
 .idea
 .vscode
 __pycache__
+.mypy_cache
 *.pyc
 dist
+.venv/
 .coverage
 coverage.xml
 .ipynb_checkpoints/

CONTRIBUTING.md

@@ -12,7 +12,7 @@ This package provides Python tools for accessing and analyzing genomic data from
 
 You'll need:
 
-- [pipx](https://python-poetry.org/) for installing Python tools
+- [pipx](https://pipx.pypa.io/) for installing Python tools
 - [git](https://git-scm.com/) for version control
 
 Both of these can be installed using your distribution's package manager or [Homebrew](https://brew.sh/) on Mac.
@@ -52,9 +52,13 @@ Both of these can be installed using your distribution's package manager or [Hom
 
    ```bash
    poetry env use 3.12
-   poetry install --extras dev
+   poetry install --with dev,test,docs
    ```
 
+   This installs the runtime dependencies along with the `dev`, `test`, and `docs`
+   [dependency groups](https://python-poetry.org/docs/managing-dependencies/#dependency-groups).
+   If you only need to run tests, `poetry install --with test` is sufficient.
+
    **Recommended**: Use `poetry run` to run commands inside the virtual environment:
 
    ```bash

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)
+- [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).
 
 ## AI use policy and guidelines

docs/source/colab_tpu_runtime.rst

@@ -0,0 +1,111 @@
+Google Colab Installation Guide
+===============================
+Prerequisites
+-------------
+
+Before installing the package, configure the runtime environment
+correctly:
+
+1. Open a new notebook in Google Colab.
+2. Navigate to ``Runtime → Change runtime type``.
+3. Set the runtime configuration as follows:
+
+   - **Runtime type:** Python 3
+   - **Hardware accelerator:** TPU
+   - **TPU type:** v2-8
+
+4. Click **Save** to apply the configuration.
+
+Using the recommended TPU configuration ensures compatibility with
+workflows that may require TPU-based computation.
+
+
+Installation Procedure
+----------------------
+
+In a new notebook cell, install the package:
+
+.. code-block:: bash
+
+   !pip install malariagen_data
+
+After installation completes, verify that the package is available:
+
+.. code-block:: python
+
+   import malariagen_data
+
+If the import executes without errors, the installation was successful.
+
+If dependency-related warnings or conflicts occur, follow one of the
+resolution options described below.
+
+
+Resolution Options
+------------------
+
+Resolution Option 1: Uninstall Panel
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your notebook does not require ``panel``, uninstall it before
+installing ``malariagen_data``.
+
+.. code-block:: bash
+
+   !pip uninstall -y panel
+   !pip install malariagen_data
+
+Verify installation:
+
+.. code-block:: python
+
+   import malariagen_data
+
+
+Resolution Option 2: Install Compatible Panel Version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your workflow depends on ``panel``, install a compatible version:
+
+.. code-block:: bash
+
+   !pip install panel==1.7.0
+   !pip install malariagen_data
+
+Restart the runtime:
+
+``Runtime → Restart runtime``
+
+Then verify:
+
+.. code-block:: python
+
+   import malariagen_data
+
+
+Resolution Option 3: Install Required Blinker Version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If a ``blinker`` version conflict occurs:
+
+.. code-block:: bash
+
+   !pip install blinker==1.9.0 --ignore-installed
+   !pip install malariagen_data
+
+Restart the runtime and verify:
+
+.. code-block:: python
+
+   import malariagen_data
+
+
+Final Verification
+------------------
+
+After completing any of the procedures above:
+
+- Ensure that ``malariagen_data`` installs without dependency errors.
+- Confirm that ``import malariagen_data`` runs successfully.
+- Restart the runtime whenever core dependencies are modified.
+- Avoid mixing incompatible package versions within the same Colab session.

malariagen_data/anoph/aim_data.py

@@ -341,6 +341,4 @@ def plot_aim_heatmap(
 
         if show:  # pragma: no cover
             fig.show(renderer=renderer)
-            return None
-        else:
-            return fig
+        return fig

malariagen_data/anoph/base.py

@@ -607,9 +607,9 @@ def _read_sample_sets_manifest(self, *, single_release: str):
             # Get today's date in ISO format
             today_date_iso = date.today().isoformat()
             # Add an "unrestricted_use" column, set to True if terms-of-use expiry date <= today's date.
-            df["unrestricted_use"] = df[terms_of_use_expiry_date_column].apply(
-                lambda d: True if pd.isna(d) else (d <= today_date_iso)
-            )
+            # Vectorized operation: True if NaN, else (d <= today_date_iso)
+            s = df[terms_of_use_expiry_date_column]
+            df["unrestricted_use"] = s.isna() | (s <= today_date_iso)
             # Make the "unrestricted_use" column a nullable boolean, to allow missing data.
             df["unrestricted_use"] = df["unrestricted_use"].astype(pd.BooleanDtype())
 

malariagen_data/anoph/base_params.py

@@ -69,7 +69,10 @@
     str,
     """
     A pandas query string to be evaluated against the sample metadata, to
-    select samples to be included in the returned data.
+    select samples to be included in the returned data. E.g.,
+    "country == 'Uganda'". If the query returns zero results, a warning
+    will be emitted with fuzzy-match suggestions for possible typos or
+    case mismatches.
     """,
 ]
 
@@ -186,6 +189,14 @@ def _validate_sample_selection_params(
     "Random seed used for reproducible down-sampling.",
 ]
 
+gene: TypeAlias = Annotated[
+    str,
+    """
+    Gene identifier. Can be either a gene ID or gene name.
+    Gene names are matched case-insensitively.
+    """,
+]
+
 transcript: TypeAlias = Annotated[
     str,
     "Gene transcript identifier.",

malariagen_data/anoph/cnv_data.py

@@ -810,9 +810,7 @@ def plot_cnv_hmm_coverage_track(
 
         if show:
             bkplt.show(fig)
-            return None
-        else:
-            return fig
+        return fig
 
     @_check_types
     @doc(
@@ -884,9 +882,7 @@ def plot_cnv_hmm_coverage(
 
         if show:
             bkplt.show(fig)
-            return None
-        else:
-            return fig
+        return fig
 
     @_check_types
     @doc(
@@ -1028,9 +1024,7 @@ def plot_cnv_hmm_heatmap_track(
 
         if show:
             bkplt.show(fig)
-            return None
-        else:
-            return fig
+        return fig
 
     @_check_types
     @doc(
@@ -1100,6 +1094,4 @@ def plot_cnv_hmm_heatmap(
 
         if show:
             bkplt.show(fig)
-            return None
-        else:
-            return fig
+        return fig

malariagen_data/anoph/cnv_frq.py

@@ -90,7 +90,11 @@ def _gene_cnv(
         inline_array,
     ):
         # Sanity check.
-        assert isinstance(region, Region)
+        if not isinstance(region, Region):
+            raise TypeError(
+                f"Expected region to be a Region object, "
+                f"got {type(region).__name__}: {region!r}"
+            )
 
         # Access genes within the region of interest.
         df_genome_features = self.genome_features(region=region)
@@ -260,7 +264,11 @@ def _gene_cnv_frequencies(
         debug = self._log.debug
 
         debug("sanity check - this function is one region at a time")
-        assert isinstance(region, Region)
+        if not isinstance(region, Region):
+            raise TypeError(
+                f"Expected region to be a Region object, "
+                f"got {type(region).__name__}: {region!r}"
+            )
 
         debug("get gene copy number data")
         ds_cnv = self.gene_cnv(
@@ -504,7 +512,11 @@ def _gene_cnv_frequencies_advanced(
         debug = self._log.debug
 
         debug("sanity check - here we deal with one region only")
-        assert isinstance(region, Region)
+        if not isinstance(region, Region):
+            raise TypeError(
+                f"Expected region to be a Region object, "
+                f"got {type(region).__name__}: {region!r}"
+            )
 
         debug("access gene CNV calls")
         ds_cnv = self.gene_cnv(