Merge pull request #11 from AmandaBirmingham/readable_validation_errors_20260209

make validation errors more readable

Author: AmandaBirmingham

metameq/src/metadata_extender.py

@@ -20,7 +20,7 @@
 from metameq.src.metadata_configurator import update_wip_metadata_dict, \
     build_full_flat_config_dict
 from metameq.src.metadata_validator import validate_metadata_df, \
-    output_validation_msgs
+    format_validation_msgs_as_df, output_validation_msgs
 import metameq.src.metadata_transformers as transformers
 
 
@@ -605,7 +605,7 @@ def _populate_metadata_df(
     metadata_df = _reorder_df(metadata_df, INTERNAL_COL_KEYS)
 
     # Turn the validation messages into a DataFrame of validation messages for easier use downstream.
-    validation_msgs_df = pandas.DataFrame(validation_msgs)
+    validation_msgs_df = format_validation_msgs_as_df(validation_msgs)
 
     return metadata_df, validation_msgs_df
 

metameq/src/metadata_merger.py

@@ -1,3 +1,4 @@
+import numpy
 import pandas
 from typing import List, Optional, Literal
 from metameq.src.util import validate_required_columns_exist
@@ -325,8 +326,8 @@ def _check_for_duplicate_field_vals(
     error_msgs = []
     duplicates_mask = metadata_df.duplicated(subset=col_name)
     if duplicates_mask.any():
-        duplicates = metadata_df.loc[duplicates_mask, col_name].unique()
-        duplicates.sort()
+        duplicates = numpy.sort(
+            metadata_df.loc[duplicates_mask, col_name].unique())
 
         # generate an error message including the duplicate values
         error_msgs.append(

metameq/src/metadata_validator.py

@@ -4,6 +4,7 @@
 from dateutil import parser
 import logging
 import os
+import pandas
 from pathlib import Path
 from metameq.src.util import SAMPLE_NAME_KEY, get_extension, cast_field_to_type
 
@@ -146,6 +147,47 @@ def output_validation_msgs(validation_msgs_df, out_dir, out_base, sep="\t",
         validation_msgs_df.to_csv(out_fp, sep=sep, index=False)
 
 
+def format_validation_msgs_as_df(validation_msgs):
+    """Format validation messages into a more human-readable DataFrame.
+
+    Takes the list of validation message dictionaries (as returned by
+    ``_generate_validation_msg`` or ``validate_metadata_df``) and produces a
+    DataFrame with one row per individual error message, sorted by sample
+    name and field name.
+
+    Parameters
+    ----------
+    validation_msgs : list
+        A list of dictionaries, each containing SAMPLE_NAME_KEY,
+        "field_name", and "error_message" keys, where "error_message"
+        is a list of error strings.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A DataFrame with columns SAMPLE_NAME_KEY, "field_name", and
+        "error_message" (a single string per row), sorted by
+        SAMPLE_NAME_KEY then "field_name" then "error_message".
+    """
+    flattened_rows = []
+    for msg in validation_msgs:
+        for err in msg["error_message"]:
+            flattened_rows.append({
+                SAMPLE_NAME_KEY: msg[SAMPLE_NAME_KEY],
+                "field_name": msg["field_name"],
+                "error_message": err
+            })
+
+    result_df = pandas.DataFrame(
+        flattened_rows,
+        columns=[SAMPLE_NAME_KEY, "field_name", "error_message"])
+    result_df.sort_values(
+        by=[SAMPLE_NAME_KEY, "field_name", "error_message"],
+        inplace=True)
+    result_df.reset_index(drop=True, inplace=True)
+    return result_df
+
+
 def _make_cerberus_schema(sample_type_metadata_dict):
     """Convert a metadata fields dictionary into a cerberus-compatible validation schema.
 

metameq/tests/test_metadata_extender/test_group_entry_points.py

@@ -289,7 +289,8 @@ def test_write_extended_metadata_from_df_with_validation_errors(self):
                         METADATA_FIELDS_KEY: {
                             "restricted_field": {
                                 TYPE_KEY: "string",
-                                ALLOWED_KEY: ["allowed_value"]
+                                ALLOWED_KEY: ["allowed_value"],
+                                "regex": "^allowed_.*$"
                             }
                         },
                         SAMPLE_TYPE_SPECIFIC_METADATA_KEY: {
@@ -323,15 +324,19 @@ def test_write_extended_metadata_from_df_with_validation_errors(self):
             })
             assert_frame_equal(expected_result_df, result_df)
 
-            # Verify validation errors file contains the error
+            # Verify validation errors file contains the errors
+            # (two flattened rows for sample1's restricted_field)
             validation_files = glob.glob(
                 os.path.join(tmpdir, "*_test_output_validation_errors.csv"))
             self.assertEqual(1, len(validation_files))
             validation_df = pandas.read_csv(validation_files[0], sep=",", dtype=str, keep_default_na=False)
             expected_validation_df = pandas.DataFrame({
-                "sample_name": ["sample1"],
-                "field_name": ["restricted_field"],
-                "error_message": ["['unallowed value invalid_value']"]
+                "sample_name": ["sample1", "sample1"],
+                "field_name": ["restricted_field", "restricted_field"],
+                "error_message": [
+                    "unallowed value invalid_value",
+                    "value does not match regex '^allowed_.*$'"
+                ]
             })
             assert_frame_equal(expected_validation_df, validation_df)
 
@@ -648,7 +653,7 @@ def test_write_extended_metadata_with_validation_errors(self):
             expected_validation_df = pandas.DataFrame({
                 "sample_name": ["sample1"],
                 "field_name": ["restricted_field"],
-                "error_message": ["['unallowed value invalid_value']"]
+                "error_message": ["unallowed value invalid_value"]
             })
             assert_frame_equal(expected_validation_df, validation_df)
 

metameq/tests/test_metadata_validator.py

@@ -11,6 +11,7 @@
     _make_cerberus_schema,
     _remove_leaf_keys_from_dict,
     _remove_leaf_keys_from_dict_in_list,
+    format_validation_msgs_as_df,
     MetameqValidator,
     output_validation_msgs,
     validate_metadata_df
@@ -1133,3 +1134,188 @@ def test_validate_metadata_df_custom_check_with_validation(self):
             "error_message": [["Date cannot be in the future"]]
         })
         pd.testing.assert_frame_equal(expected_df, result_df)
+
+
+class TestFormatValidationMsgsAsDf(TestCase):
+    """Tests for format_validation_msgs_as_df function."""
+
+    def test_format_validation_msgs_as_df_empty_list(self):
+        """Test that empty input returns an empty DataFrame with correct columns."""
+        result = format_validation_msgs_as_df([])
+
+        self.assertIsInstance(result, pd.DataFrame)
+        self.assertEqual(
+            ["sample_name", "field_name", "error_message"],
+            list(result.columns))
+        self.assertEqual(0, len(result))
+
+    def test_format_validation_msgs_as_df_single_error(self):
+        """Test formatting a single validation message with one error."""
+        validation_msgs = [
+            {
+                "sample_name": "sample1",
+                "field_name": "age",
+                "error_message": ["must be of integer type"]
+            }
+        ]
+
+        result = format_validation_msgs_as_df(validation_msgs)
+
+        expected = pd.DataFrame({
+            "sample_name": ["sample1"],
+            "field_name": ["age"],
+            "error_message": ["must be of integer type"]
+        })
+        pd.testing.assert_frame_equal(expected, result)
+
+    def test_format_validation_msgs_as_df_multiple_errors_same_field(self):
+        """Test that multiple errors for one field are flattened to separate rows."""
+        validation_msgs = [
+            {
+                "sample_name": "sample1",
+                "field_name": "date_field",
+                "error_message": [
+                    "Must be a valid date",
+                    "value does not match regex '^[0-9]{4}-[0-9]{2}-[0-9]{2}$'"
+                ]
+            }
+        ]
+
+        result = format_validation_msgs_as_df(validation_msgs)
+
+        expected = pd.DataFrame({
+            "sample_name": ["sample1", "sample1"],
+            "field_name": ["date_field", "date_field"],
+            "error_message": [
+                "Must be a valid date",
+                "value does not match regex '^[0-9]{4}-[0-9]{2}-[0-9]{2}$'"
+            ]
+        })
+        pd.testing.assert_frame_equal(expected, result)
+
+    def test_format_validation_msgs_as_df_multiple_fields_same_sample(self):
+        """Test multiple fields with errors for the same sample."""
+        validation_msgs = [
+            {
+                "sample_name": "sample1",
+                "field_name": "age",
+                "error_message": ["must be of integer type"]
+            },
+            {
+                "sample_name": "sample1",
+                "field_name": "count",
+                "error_message": ["must be of integer type"]
+            }
+        ]
+
+        result = format_validation_msgs_as_df(validation_msgs)
+
+        expected = pd.DataFrame({
+            "sample_name": ["sample1", "sample1"],
+            "field_name": ["age", "count"],
+            "error_message": [
+                "must be of integer type",
+                "must be of integer type"
+            ]
+        })
+        pd.testing.assert_frame_equal(expected, result)
+
+    def test_format_validation_msgs_as_df_multiple_samples(self):
+        """Test errors across multiple samples."""
+        validation_msgs = [
+            {
+                "sample_name": "sample1",
+                "field_name": "age",
+                "error_message": ["must be of integer type"]
+            },
+            {
+                "sample_name": "sample2",
+                "field_name": "age",
+                "error_message": ["must be of integer type"]
+            }
+        ]
+
+        result = format_validation_msgs_as_df(validation_msgs)
+
+        expected = pd.DataFrame({
+            "sample_name": ["sample1", "sample2"],
+            "field_name": ["age", "age"],
+            "error_message": [
+                "must be of integer type",
+                "must be of integer type"
+            ]
+        })
+        pd.testing.assert_frame_equal(expected, result)
+
+    def test_format_validation_msgs_as_df_sorted_by_sample_then_field(self):
+        """Test that output is sorted by sample_name then field_name."""
+        validation_msgs = [
+            {
+                "sample_name": "sample_z",
+                "field_name": "beta_field",
+                "error_message": ["error z-beta"]
+            },
+            {
+                "sample_name": "sample_a",
+                "field_name": "gamma_field",
+                "error_message": ["error a-gamma"]
+            },
+            {
+                "sample_name": "sample_a",
+                "field_name": "alpha_field",
+                "error_message": ["error a-alpha"]
+            },
+            {
+                "sample_name": "sample_z",
+                "field_name": "alpha_field",
+                "error_message": ["error z-alpha"]
+            }
+        ]
+
+        result = format_validation_msgs_as_df(validation_msgs)
+
+        expected = pd.DataFrame({
+            "sample_name": [
+                "sample_a", "sample_a", "sample_z", "sample_z"],
+            "field_name": [
+                "alpha_field", "gamma_field", "alpha_field", "beta_field"],
+            "error_message": [
+                "error a-alpha", "error a-gamma",
+                "error z-alpha", "error z-beta"]
+        })
+        pd.testing.assert_frame_equal(expected, result)
+
+    def test_format_validation_msgs_as_df_flattening_and_sorting_combined(self):
+        """Test that flattening and sorting work correctly together."""
+        validation_msgs = [
+            {
+                "sample_name": "sample_b",
+                "field_name": "field_x",
+                "error_message": ["error 2", "error 1"]
+            },
+            {
+                "sample_name": "sample_a",
+                "field_name": "field_y",
+                "error_message": ["error 5", "error 3"]
+            },
+            {
+                "sample_name": "sample_a",
+                "field_name": "field_x",
+                "error_message": ["error 4"]
+            }
+        ]
+
+        result = format_validation_msgs_as_df(validation_msgs)
+
+        expected = pd.DataFrame({
+            "sample_name": [
+                "sample_a", "sample_a", "sample_a",
+                "sample_b", "sample_b"],
+            "field_name": [
+                "field_x", "field_y", "field_y",
+                "field_x", "field_x"],
+            "error_message": [
+                "error 4", "error 3", "error 5",
+                "error 1", "error 2"]
+        })
+        pd.testing.assert_frame_equal(expected, result)