chore: improve user-facing error messages

Make internal validation errors more actionable by avoiding private variable names, clarifying required inputs (e.g. AIM palette order), and suggesting filing a GitHub issue for invariants that should never fail.

Made-with: Cursor

Author: khushthecoder

malariagen_data/anoph/aim_data.py

@@ -254,21 +254,24 @@ def plot_aim_heatmap(
             gn = np.take(gn, ix_sorted, axis=1)
             samples = np.take(samples, ix_sorted, axis=0)
 
+        species = aims.split("_vs_")
+
         # Set up colors for genotypes
         if palette is None:
             if self._aim_palettes is None:
                 raise RuntimeError(
-                    "AIM palettes have not been configured. "
-                    "Please provide a 'palette' parameter or configure AIM_PALETTES."
+                    "AIM palettes are not available for this data resource. "
+                    "Please provide the 'palette' parameter explicitly (4 colors)."
                 )
             palette = self._aim_palettes[aims]
             if len(palette) != 4:
                 raise RuntimeError(
-                    f"Expected AIM palette to have 4 colors, got {len(palette)}"
+                    "Expected AIM palette to have 4 colors "
+                    f"(missing, {species[0]}/{species[0]}, {species[0]}/{species[1]}, {species[1]}/{species[1]}), "
+                    f"got {len(palette)}"
                 )
             # Expect 4 colors, in the order:
             # missing, hom taxon 1, het, hom taxon 2
-        species = aims.split("_vs_")
 
         # Create subplots.
         fig = go_make_subplots(

malariagen_data/anoph/cnv_frq.py

@@ -599,8 +599,8 @@ def _gene_cnv_frequencies_advanced(
             else:
                 if nobs_mode != "fixed":
                     raise RuntimeError(
-                        f"Internal error: expected nobs_mode='fixed', "
-                        f"got {nobs_mode!r}"
+                        f"Internal error: expected nobs_mode='fixed', got {nobs_mode!r}. "
+                        "This should not happen; please open a GitHub issue."
                     )
                 nobs[:, cohort_index] = cohort.size
 

malariagen_data/anoph/h1x.py

@@ -405,13 +405,14 @@ def _moving_h1x(ha, hb, size, start=0, stop=None, step=None):
 
     if ha.ndim != 2 or hb.ndim != 2:
         raise ValueError(
-            f"Expected ha and hb to be 2-dimensional, "
-            f"got ha.ndim={ha.ndim} and hb.ndim={hb.ndim}"
+            "Expected both haplotype arrays to be 2-dimensional "
+            "(n_variants, n_haplotypes), "
+            f"got ndim=({ha.ndim}, {hb.ndim})"
         )
     if ha.shape[0] != hb.shape[0]:
         raise ValueError(
-            f"ha and hb must have the same number of variants, "
-            f"got ha.shape[0]={ha.shape[0]} and hb.shape[0]={hb.shape[0]}"
+            "Expected both haplotype arrays to have the same number of variants "
+            f"(axis 0), got ({ha.shape[0]}, {hb.shape[0]})"
         )
 
     # Construct moving windows.

malariagen_data/anoph/sample_metadata.py

@@ -595,9 +595,15 @@ def _parse_aim_metadata(
         self, sample_set: str, data: Union[bytes, Exception]
     ) -> pd.DataFrame:
         if self._aim_metadata_columns is None:
-            raise RuntimeError("AIM metadata columns have not been configured.")
+            raise RuntimeError(
+                "Internal error: AIM metadata columns are not configured. "
+                "This should not happen; please open a GitHub issue."
+            )
         if self._aim_metadata_dtype is None:
-            raise RuntimeError("AIM metadata dtype has not been configured.")
+            raise RuntimeError(
+                "Internal error: AIM metadata dtypes are not configured. "
+                "This should not happen; please open a GitHub issue."
+            )
         if isinstance(data, bytes):
             # Parse CSV data but don't apply the dtype yet.
             df = pd.read_csv(io.BytesIO(data), na_values="")

malariagen_data/util.py

@@ -1580,21 +1580,25 @@ 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, got {type(v).__name__}")
+        raise TypeError(
+            f"Expected input array 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, got {type(mapping).__name__}"
         )
     if v.ndim != 2:
-        raise ValueError(f"Expected v to be 2-dimensional, got {v.ndim} dimensions")
+        raise ValueError(
+            f"Expected input array to be 2-dimensional, got {v.ndim} dimensions"
+        )
     if mapping.ndim != 2:
         raise ValueError(
             f"Expected mapping to be 2-dimensional, got {mapping.ndim} dimensions"
         )
     if v.shape[0] != mapping.shape[0]:
         raise ValueError(
-            f"v and mapping must have same first dimension, "
-            f"got v.shape[0]={v.shape[0]} and mapping.shape[0]={mapping.shape[0]}"
+            "Expected input array and mapping to have the same first dimension, "
+            f"got {v.shape[0]} and {mapping.shape[0]}"
         )
     v = v.rechunk((v.chunks[0], -1))
     mapping = da.from_array(mapping, chunks=(v.chunks[0], -1))
@@ -1619,33 +1623,39 @@ def _genotype_array_map_alleles(gt, mapping):
             f"Expected mapping to be a numpy.ndarray, got {type(mapping).__name__}"
         )
     if gt.ndim != 3:
-        raise ValueError(f"Expected gt to be 3-dimensional, got {gt.ndim} dimensions")
+        raise ValueError(
+            f"Expected genotype calls array to be 3-dimensional, got {gt.ndim} dimensions"
+        )
     if mapping.ndim != 3:
         raise ValueError(
             f"Expected mapping to be 3-dimensional, got {mapping.ndim} dimensions"
         )
     if gt.shape[0] != mapping.shape[0]:
         raise ValueError(
-            f"gt and mapping must have same first dimension, "
-            f"got gt.shape[0]={gt.shape[0]} and mapping.shape[0]={mapping.shape[0]}"
+            "Expected genotype calls array and mapping to have the same first dimension, "
+            f"got {gt.shape[0]} and {mapping.shape[0]}"
         )
     if gt.shape[1] <= 0:
-        raise ValueError(f"Expected gt.shape[1] > 0, got {gt.shape[1]}")
+        raise ValueError(f"Expected genotype calls axis 1 to be > 0, got {gt.shape[1]}")
     if gt.shape[2] != 2:
-        raise ValueError(f"Expected gt.shape[2] == 2 (diploid), got {gt.shape[2]}")
+        raise ValueError(
+            f"Expected genotype calls axis 2 to be 2 (diploid), got {gt.shape[2]}"
+        )
     if gt.size > 0:
         # Block is not empty, can pass through to GenotypeArray.
         if gt.shape[0] <= 0:
             raise RuntimeError(
-                f"Internal error: gt.size > 0 but gt.shape[0] = {gt.shape[0]}"
+                f"Internal error: non-empty genotype block but axis 0 is {gt.shape[0]}. "
+                "Please open a GitHub issue."
             )
         m = mapping[:, 0, :]
         out = allel.GenotypeArray(gt).map_alleles(m).values
     else:
         # Block is empty so no alleles need to be mapped.
         if gt.shape[0] != 0:
             raise RuntimeError(
-                f"Internal error: gt.size == 0 but gt.shape[0] = {gt.shape[0]}"
+                f"Internal error: empty genotype block but axis 0 is {gt.shape[0]}. "
+                "Please open a GitHub issue."
             )
         out = gt
     return out