Fix visualization reshape error with descriptive error messages and validation

[Copilot]

Problem

The plot_evaluation_results function in deeplabcut/utils/visualization.py was failing with cryptic reshape errors when the input data didn't match expected dimensions:

ValueError: cannot reshape array of size 8 into shape (2,4,2)

This error provided no context about what data was being processed or why the reshape failed, making it difficult for users to debug data structure issues.

Root Cause

The function performed direct .reshape() operations without validating that the array size matched the target dimensions:

# Lines 517-518 (before fix)
ground_truth = df_gt.to_numpy().reshape((individuals, bodyparts, 2))
predictions = df_predictions.to_numpy().reshape((individuals, bodyparts, 3))

When the actual data didn't contain the expected number of individuals, bodyparts, or coordinates, these reshapes would fail with uninformative error messages.

Solution

Added a safe_reshape function that:

1. Validates array sizes before attempting reshape operations
2. Provides descriptive error messages with context about what data is being processed
3. Suggests actionable debugging steps for users
4. Maintains full backward compatibility for valid data

Example Error Message Improvement

Before:

ValueError: cannot reshape array of size 8 into shape (2,4,2)

After:

ValueError: Cannot reshape array of size 8 into shape (2, 4, 2) for ground truth data with 2 individuals and 4 bodyparts. Expected 16 elements but got 8. This may indicate missing data or inconsistent data structure. Please verify that all expected individuals, bodyparts, and coordinates are present in the data.

Changes Made

1. Added safe_reshape function with comprehensive validation and error reporting
2. Updated all reshape calls in plot_evaluation_results to use safe_reshape with meaningful context
3. Added comprehensive unit tests covering valid operations, various error scenarios, and edge cases

Validation

• ✅ All existing valid data scenarios continue to work unchanged
• ✅ Invalid data now provides clear, actionable error messages
• ✅ Added 15+ test cases covering various data mismatch scenarios
• ✅ Maintains the exact same API - no breaking changes
• ✅ Minimal code footprint - only 49 lines added, 10 lines modified

This fix transforms frustrating debugging sessions into clear guidance for users when their data doesn't match expected structure, while ensuring robust validation prevents silent failures.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.