Update CMIP6 variable filtering and error handling (#124)

* Update Emon variable filtering to include only compatible variables from the CMIP6 table

* Fix dimensions mapping for specific_humidity in ACCESS-ESM1.6

* Add error handling for CMIP6Vocabulary initialization and enhance VariableNotFoundError with suggestions

* pre-commit

Author: rbeucher

src/access_moppy/driver.py

@@ -72,16 +72,24 @@ def __init__(
 
         self.parent_info = {**_default_parent_info, **(parent_info or {})}
 
-        # Create the CMIP6Vocabulary instance
-        self.vocab = CMIP6Vocabulary(
-            compound_name=compound_name,
-            experiment_id=experiment_id,
-            source_id=source_id,
-            variant_label=variant_label,
-            grid_label=grid_label,
-            activity_id=activity_id,
-            parent_info=self.parent_info,
-        )
+        # Create the CMIP6Vocabulary instance with error handling
+        try:
+            self.vocab = CMIP6Vocabulary(
+                compound_name=compound_name,
+                experiment_id=experiment_id,
+                source_id=source_id,
+                variant_label=variant_label,
+                grid_label=grid_label,
+                activity_id=activity_id,
+                parent_info=self.parent_info,
+            )
+        except Exception as e:
+            # For VariableNotFoundError, just re-raise as-is (it already has good messaging)
+            # For other exceptions, add context about the compound name
+            if "VariableNotFoundError" in str(type(e)):
+                raise
+            else:
+                raise type(e)(f"Error processing '{compound_name}': {str(e)}") from e
 
         # Initialize the CMORiser based on the compound name
         table, _ = compound_name.split(".")  # cmor_name now extracted internally

src/access_moppy/mappings/ACCESS-ESM1.6_mappings.json

@@ -152,7 +152,7 @@
         },
         "huss": {
             "CF standard Name": "specific_humidity",
-            "dimensions": {"time": "time", "lat_v": "lat", "lon_u": "lon"},
+            "dimensions": {"time": "time", "lat": "lat", "lon": "lon"},
             "units": "1",
             "positive": null,
             "model_variables": ["fld_s03i237"],

src/access_moppy/vocabulary_processors.py

@@ -3,11 +3,38 @@
 import uuid
 from datetime import datetime, timezone
 from importlib.resources import as_file, files
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional
 
 from access_moppy import _creator
 
 
+class VariableNotFoundError(ValueError):
+    """
+    Exception raised when a requested variable is not found in the specified CMIP6 table.
+
+    Provides helpful suggestions for alternative tables or similar variables.
+    """
+
+    def __init__(
+        self,
+        variable_name: str,
+        table_name: str,
+        suggestions: Optional[List[str]] = None,
+    ):
+        self.variable_name = variable_name
+        self.table_name = table_name
+        self.suggestions = suggestions or []
+
+        message = f"Variable '{variable_name}' not found in CMIP6 table '{table_name}'."
+
+        if self.suggestions:
+            message += "\n\nSuggestions:\n" + "\n".join(
+                f"  • {s}" for s in self.suggestions
+            )
+
+        super().__init__(message)
+
+
 class CMIP6Vocabulary:
     cv_dir = "access_moppy.vocabularies.cmip6_cmor_tables.CMIP6_CVs"
     table_dir = "access_moppy.vocabularies.cmip6_cmor_tables.Tables"
@@ -140,9 +167,94 @@ def _get_variable_entry(self) -> Dict[str, Any]:
 
             return var_entry
         except KeyError:
-            raise ValueError(
-                f"Variable '{self.cmor_name}' not found in table {self.table}."
+            # Generate helpful suggestions
+            suggestions = self._get_variable_suggestions()
+            raise VariableNotFoundError(self.cmor_name, self.table, suggestions)
+
+    def _get_variable_suggestions(self) -> List[str]:
+        """
+        Generate helpful suggestions when a variable is not found.
+
+        Returns:
+            List of suggestion strings for the user.
+        """
+        suggestions = []
+
+        # Check if variable exists in other CMIP6 tables
+        common_tables = ["Amon", "Lmon", "Omon", "Emon", "day", "6hrLev", "3hr"]
+        found_in_tables = []
+
+        for table in common_tables:
+            if table == self.table:
+                continue  # Skip current table
+
+            try:
+                table_file = f"CMIP6_{table}.json"
+                table_resource = files(self.table_dir) / table_file
+
+                with as_file(table_resource) as table_path:
+                    with open(table_path, "r", encoding="utf-8") as f:
+                        table_data = json.load(f)
+
+                    if self.cmor_name in table_data.get("variable_entry", {}):
+                        found_in_tables.append(table)
+
+            except (FileNotFoundError, KeyError):
+                continue  # Table doesn't exist or has no variable_entry
+
+        if found_in_tables:
+            table_list = ", ".join(found_in_tables)
+            suggestions.append(
+                f"Variable '{self.cmor_name}' is available in table(s): {table_list}"
             )
+            suggestions.append(f"Try using: {found_in_tables[0]}.{self.cmor_name}")
+
+        # Check for similar variable names in current table
+        try:
+            current_table_data = self._load_table()
+            available_vars = list(current_table_data.get("variable_entry", {}).keys())
+
+            # Find variables with similar names (simple string similarity)
+            similar_vars = []
+            for var in available_vars:
+                if len(var) > 2 and (
+                    self.cmor_name.lower() in var.lower()
+                    or var.lower() in self.cmor_name.lower()
+                    or
+                    # Check for common root (first 3 characters)
+                    (
+                        len(self.cmor_name) >= 3
+                        and len(var) >= 3
+                        and self.cmor_name[:3].lower() == var[:3].lower()
+                    )
+                ):
+                    similar_vars.append(var)
+
+            if similar_vars:
+                similar_list = ", ".join(similar_vars[:5])  # Limit to 5 suggestions
+                suggestions.append(
+                    f"Similar variables in {self.table} table: {similar_list}"
+                )
+
+            # Show a sample of available variables if no similar ones found
+            elif available_vars:
+                sample_vars = ", ".join(available_vars[:10])  # Show first 10
+                total_count = len(available_vars)
+                if total_count > 10:
+                    sample_vars += f" (and {total_count - 10} more)"
+                suggestions.append(
+                    f"Available variables in {self.table} table: {sample_vars}"
+                )
+
+        except Exception:
+            pass  # Don't fail if we can't load suggestions
+
+        # Add general guidance
+        suggestions.append(
+            "Visit https://clipc-services.ceda.ac.uk/dreq/index.html to browse CMIP6 variables"
+        )
+
+        return suggestions
 
     def _get_axes(self) -> Dict[str, Any]:
         # Resolve resource inside the module path

tests/conftest.py

@@ -228,13 +228,14 @@ def _filter_variables_by_test_data(variables, table_name):
             "mrso",  # Total Soil Moisture Content (if soil data available)
         ],
         "Emon": [
-            # Subset of atmosphere and land variables that work
-            "tas",
-            "pr",
-            "uas",
-            "vas",
-            "psl",
-            "huss",
+            # Only variables that actually exist in the Emon CMIP6 table
+            # AND are compatible with the test data (aiihca.pa-101909_mon.nc)
+            # From atmosphere component:
+            "hus",  # Specific Humidity
+            "ps",  # Surface Air Pressure
+            "ua",  # Eastward Wind
+            "va",  # Northward Wind
+            # Note: co23D and cSoil exist in Emon but have dimension issues with test data
         ],
     }