Fix Overlapping Labels in Feat vs Anno Heatmap with Enhanced Axis Controls

[zhan4329]

Description

This PR enhances the Feature vs Annotation heatmap visualization with improvements to UI/UX, code quality, and maintainability following contributing guidelines.

This PR fixes the issue of overlapping labels in heatmap.

Related Issue/PR

This work is based on student contributions in PR #51
This PR closes Issue Saran-Nag#22

Key Changes

1. Enhanced Axis Customization

• Font Size Controls: Numeric inputs for precise axis label font sizing (3-24pt range)
• Y-Axis Label Rotation: Added rotation functionality for Y-axis labels (previously only X-axis supported)
• Label Abbreviation: Configurable character limits to prevent overlapping labels and improve readability

2. UI/UX Redesign

Reorganized control panel into three collapsible sections for better usability:

• Core Parameters: Annotation and layer selection for primary analysis configuration
• Plot Configuration: Color maps, dendrograms, min/max value controls (collapsible to reduce clutter)
• Axis Settings: Rotation angles, font sizing, and label abbreviation options (collapsible)

3. Accessibility & Performance

• Accessibility: alt attributes for screen readers, accessible CSS with focus states, semantic HTML structure
• Performance: Replaced renderUI/uiOutput with conditionalPanel for reduced reactivity overhead
• Consistency: Reactive adata object, standardized hm1 naming convention

4. Code Quality & Standards

• Documentation: NumPy-style docstrings with examples, updated contributor information
• Error Handling: Logging with specific exception handling
• Code Organization: Extracted utilities to utils/plot_utils.py
• Validation: Input validation with req() and defensive checks
• Testing: Unit tests covering edge cases (6 test methods)
• PEP 8 Compliance: Line lengths, formatting, clean imports

Files Modified

• server/feat_vs_anno_server.py
  • The 3 new axis controls (font size, y-axis rotation, abbreviation)
  • Error handling, validation, docstrings and PEP 8 formatting
• ui/feat_vs_anno_ui.py
  • UI restructuring (new control panel aligning with nearest_neighbor tab)
  • Accessibility, naming consistency, performance
  • Docstrings and PEP 8 formatting
• utils/plot_utils.py - New utility functions (22 new lines, abbreviate_labels and apply_axis_style)
• tests/test_utils/test_plot_utils.py - Test suite (73 lines, new file, 6 tests for the above two utillity functions)
• TECHNICAL_DETAILS.md - Updated contributor information

Verification Results

• New layout renders correctly
• All new controls functional
• 508 Compliance satisfied
• All unit tests passing
• PEP 8 compliant satisfied
• NumPy-style docstrings added
• All changes follow the contributing guide
• All issues from code review fixed

Ready for Review

[zhan4329]

Final Code Review for PR #66: Feature vs Annotation Axis Settings Improvements

Generated by Copilot (with Claude Sonnet 4.5) with minor manul editions.

This is the final code review after resolving 20 issues arising from the initial review (also generated by copilot, referring to the contributing guides). See the hidden comment above for more details: #66 (review)).

Overview

This PR enhances the Feature vs Annotation heatmap visualization with significant improvements to UI/UX, code quality, and maintainability.

Changes Summary

• Restructured UI with collapsible sections for better organization
• Added Y-axis rotation and font size controls
• Implemented label abbreviation functionality
• Extracted reusable utility functions to utils/plot_utils.py
• Added comprehensive error handling and logging
• Created unit tests for utility functions
• Achieved full PEP 8 compliance
• Added NumPy-style docstrings throughout

Files Modified

• server/feat_vs_anno_server.py - 63 lines changed
• ui/feat_vs_anno_ui.py - 50 lines changed
• utils/plot_utils.py - 22 lines added
• tests/test_utils/test_plot_utils.py - 73 lines added (new file)

---

✅ Strengths

Code Quality

• Excellent documentation: All functions have comprehensive NumPy-style docstrings with parameters, returns, and examples
• Robust error handling: Proper exception handling with specific ValueError catches and logging
• Input validation: Appropriate use of req() to prevent null reference errors
• Defensive programming: Added None checks in get_adata() to prevent crashes
• Code reusability: Extracted abbreviate_labels() and apply_axis_style() to utilities module

Testing

• Unit tests created: 6 comprehensive test methods covering:
  • Basic abbreviation logic
  • Edge cases (empty lists, zero limits)
  • Unicode handling
  • Style application
  • Error prevention

Standards Compliance

• PEP 8 compliant: All line lengths ≤79 characters, no trailing whitespace
• Consistent formatting: Proper spacing, indentation, and code structure
• Convention commits: Clear, descriptive commit messages following project standards

UI/UX Improvements

• Better organization: Collapsible sections for plot and axis settings
• Enhanced controls: Y-axis rotation, font size, and label abbreviation options
• Responsive design: Proper scrolling with 85vh height containers
• Consistent styling: Follows patterns from nearest_neighbor_ui.py

---

📊 Review Checklist

Critical Requirements ✅

• ✅ Module docstrings added to both server and UI files
• ✅ Function docstrings follow NumPy style
• ✅ All helper functions properly documented
• ✅ Error handling with logging implemented
• ✅ Input validation with req() added

Code Quality ✅

• ✅ Utility functions extracted and reusable
• ✅ Defensive programming practices implemented
• ✅ Code duplication eliminated
• ✅ Magic numbers documented with constants
• ✅ Unused imports removed

Documentation ✅

• ✅ Function return values documented
• ✅ Usage examples included in docstrings
• ✅ Clear parameter descriptions
• ✅ TODO comments removed

Testing ✅

• ✅ Unit tests created for utility functions
• ✅ Edge cases covered
• ✅ Tests follow project patterns

Style Compliance ✅

• ✅ PEP 8 line length compliance (79 chars)
• ✅ No trailing whitespace
• ✅ Consistent spacing and formatting
• ✅ Proper import organization

---

💡 Optional Enhancements

Future Improvements (Not Blocking)

1. ARIA Labels: Consider adding explicit aria-label attributes to input elements for enhanced screen reader support

   ui.input_numeric(
       "hm1_x_label_rotation",
       "Rotate X Axis Labels (degrees)",
       **{"aria-label": "X axis label rotation angle in degrees"}
   )

---

🎯 Recommendation

Status: ✅ APPROVED - READY TO MERGE

Completion: 19/20 items (95%)

This PR demonstrates excellent code quality and professionalism:

• All critical contributing guidelines requirements met
• Comprehensive documentation throughout
• Robust error handling and validation
• Full test coverage for new utilities
• Complete PEP 8 compliance
• Clean, maintainable code structure

The only remaining item (ARIA labels) is an optional accessibility enhancement that can be tracked as a future improvement if desired.

What This PR Delivers

✅ Enhanced user experience with improved axis controls
✅ Professional, maintainable codebase
✅ Reusable utility functions for the project
✅ Comprehensive test coverage
✅ Full compliance with contributing guidelines

Great work! This is a solid, production-ready contribution. 🎉

---

📝 Commits

1. test(fva): add unit tests for plot utilities - bcca35c
2. docs(plot_utils): add examples to utility functions - 70b033c
3. fix(fva): code clean-up for better readability - 16c5a49
4. style(fva): enforce PEP 8 compliance across feature vs annotation files - 61b0435

---

Reviewed on: February 10, 2026
Review based on: CONTRIBUTING.md and Copilot Instructions