feat: add list_taxons and list_species_calls utilities to SampleMetadata

.gitignore

@@ -14,7 +14,7 @@ tests/anoph/fixture/simulated
 
 # emacs
 *~
-
+*.txt
 # nbconvert outputs
 notebooks/*.nbconvert.ipynb
 notebooks/*.html

malariagen_data/anoph/sample_metadata.py

@@ -863,6 +863,36 @@ def sample_metadata(
 
         return df_samples.copy()
 
+    @_check_types
+    @doc(
+        summary="List the unique taxons present in one or more sample sets.",
+        returns="A list of unique taxon names.",
+    )
+    def list_taxons(
+        self, sample_sets: Optional[base_params.sample_sets] = None
+    ) -> List[str]:
+        df_samples = self.sample_metadata(sample_sets=sample_sets)
+        if "taxon" in df_samples.columns:
+            taxons = df_samples["taxon"].dropna().unique().tolist()
+            return sorted([str(t) for t in taxons])
+        else:
+            return []
+
+    @_check_types
+    @doc(
+        summary="List the unique AIM species calls present in one or more sample sets.",
+        returns="A list of unique species call names.",
+    )
+    def list_aim_species_calls(
+        self, sample_sets: Optional[base_params.sample_sets] = None
+    ) -> List[str]:
+        df_samples = self.sample_metadata(sample_sets=sample_sets)
+        if "aim_species" in df_samples.columns:
+            species = df_samples["aim_species"].dropna().unique().tolist()
+            return sorted([str(s) for s in species])
+        else:
+            return []
+
     @_check_types
     @doc(
         summary="""

tests/anoph/test_sample_metadata.py

@@ -1630,3 +1630,33 @@ def test_cohort_geometries_cached(fixture, api):
     g1 = api.cohort_geometries("admin1_month")
     g2 = api.cohort_geometries("admin1_month")
     assert g1 is g2
+
+
+@parametrize_with_cases("fixture,api", cases=".")
+def test_list_taxons(fixture, api: AnophelesSampleMetadata):
+    sample_sets = random.choice(api.releases)
+    taxons = api.list_taxons(sample_sets=sample_sets)
+    assert isinstance(taxons, list)
+    assert all(isinstance(t, str) for t in taxons)
+    assert taxons == sorted(taxons)
+
+    # Check consistency with sample_metadata
+    df_samples = api.sample_metadata(sample_sets=sample_sets)
+    expected_taxons = sorted(df_samples["taxon"].dropna().unique().tolist())
+    assert taxons == expected_taxons
+
+
+@parametrize_with_cases("fixture,api", cases=".")
+def test_list_aim_species_calls(fixture, api: AnophelesSampleMetadata):
+    sample_sets = random.choice(api.releases)
+    species = api.list_aim_species_calls(sample_sets=sample_sets)
+    assert isinstance(species, list)
+
+    # Check consistency with sample_metadata
+    df_samples = api.sample_metadata(sample_sets=sample_sets)
+    if "aim_species" in df_samples.columns:
+        expected_species = sorted(df_samples["aim_species"].dropna().unique().tolist())
+        assert species == expected_species
+        assert all(isinstance(s, str) for s in species)
+    else:
+        assert species == []