Visualization and Plotting Methods


# Task 006: Visualization and Plotting Methods

## Overview

Implement comprehensive visualization capabilities for HTFA results including publication-ready brain plots using nilearn, temporal weight visualizations, and network summary plots. All visualizations should be accessible directly from the HTFAResults container with sensible defaults and customization options.

## Objectives

- Create publication-ready brain visualizations using nilearn's plotting capabilities
- Implement temporal weight plotting with matplotlib/seaborn for time series analysis
- Develop network summary visualizations for factor interpretation
- Provide both quick-view and customizable publication-ready plotting options
- Ensure consistent visual style and professional appearance across all plots

## Scope

### In Scope
- Brain factor visualization using nilearn plotting functions
- Temporal weight time series plots with subject grouping
- Factor network connectivity and summary visualizations  
- Multi-panel figure layouts for comprehensive result presentation
- Export functionality for high-resolution publication figures
- Interactive plotting options where appropriate

### Out of Scope
- Real-time interactive dashboards (future enhancement)
- 3D brain renderings (beyond nilearn capabilities)
- Statistical comparison plotting (future statistical module)
- Custom colormap development (use established scientific colormaps)

## Technical Requirements

### Visualization Methods for HTFAResults Class
```python
class HTFAResults:
    # Brain visualization methods
    def plot_factors(self, factor_idx=None, threshold=None, colorbar=True, 
                    output_file=None, **kwargs) -> matplotlib.figure.Figure
    
    def plot_factor_glassbrain(self, factor_idx=0, threshold='auto',
                              colorbar=True, **kwargs) -> matplotlib.figure.Figure
    
    # Temporal weight visualization  
    def plot_weights(self, factor_idx=0, subjects=None, summary_stat='mean',
                    error_bars=True, **kwargs) -> matplotlib.figure.Figure
                    
    def plot_weight_heatmap(self, subjects=None, normalize=True, 
                           **kwargs) -> matplotlib.figure.Figure
    
    # Network and summary plots
    def plot_factor_summary(self, layout='grid', save_path=None,
                           **kwargs) -> matplotlib.figure.Figure
                           
    def plot_weight_distribution(self, factor_idx=0, **kwargs) -> matplotlib.figure.Figure
    
    # Multi-panel comprehensive visualization
    def plot_results_overview(self, output_dir=None, dpi=300,
                             **kwargs) -> Dict[str, matplotlib.figure.Figure]
```

### Brain Visualization Requirements
- **Nilearn Integration**: Leverage plot_stat_map, plot_glass_brain functions
- **Automatic Thresholding**: Statistical thresholding with multiple correction options
- **Colormap Standards**: Use neuroimaging-appropriate colormaps (cold_hot, RdBu_r)
- **Multi-view Support**: Sagittal, coronal, axial views in single figure
- **Anatomical Overlays**: MNI template integration for spatial context

### Temporal Weight Visualization
- **Time Series Plots**: Line plots with confidence intervals across subjects
- **Heatmap Display**: Subject × time factor weight matrices
- **Summary Statistics**: Mean, median, percentile bands for group analysis
- **Subject Grouping**: Support for subject-specific metadata grouping
- **Interactive Options**: Optional plotly backend for interactive exploration

### Publication Quality Requirements
- **High DPI Export**: 300+ DPI for publication figures
- **Consistent Styling**: Unified color schemes, font sizes, layout spacing
- **Professional Typography**: Science-appropriate fonts and sizing
- **Multi-format Export**: PNG, SVG, PDF export options
- **Figure Legends**: Comprehensive legends with analysis parameters

## Implementation Details

### Brain Plotting Implementation
```python
def plot_factors(self, factor_idx=None, threshold=None, colorbar=True, 
                output_file=None, **kwargs):
    """Plot spatial factors as brain maps using nilearn."""
    
    # Convert factors to NIfTI images
    factor_images = self.factors_to_nifti()
    
    # Handle factor selection
    if factor_idx is None:
        factor_idx = list(range(self.n_factors))
    elif isinstance(factor_idx, int):
        factor_idx = [factor_idx]
    
    # Automatic thresholding if not specified
    if threshold is None:
        threshold = self._compute_threshold(percentile=95)
    
    # Create multi-panel figure
    n_factors = len(factor_idx)
    fig, axes = plt.subplots(n_factors, 1, figsize=(12, 4*n_factors))
    
    for i, idx in enumerate(factor_idx):
        # Use nilearn plotting with consistent styling
        plotting.plot_stat_map(
            factor_images[idx],
            threshold=threshold,
            colorbar=colorbar,
            axes=axes[i] if n_factors > 1 else axes,
            title=f'Factor {idx+1}',
            **kwargs
        )
    
    if output_file:
        plt.savefig(output_file, dpi=300, bbox_inches='tight')
    
    return fig
```

### Temporal Weight Visualization
```python  
def plot_weights(self, factor_idx=0, subjects=None, summary_stat='mean',
                error_bars=True, **kwargs):
    """Plot temporal weights with error bars across subjects."""
    
    # Extract weights for specified factor
    weights = self.weights[:, :, factor_idx]  # (n_subjects, n_timepoints)
    
    # Subject selection
    if subjects is not None:
        weights = weights[subjects, :]
    
    # Compute summary statistics
    mean_weights = np.mean(weights, axis=0)
    
    # Create time series plot
    fig, ax = plt.subplots(figsize=(12, 6))
    
    # Plot individual subject traces (optional)
    if kwargs.get('show_subjects', False):
        for i in range(weights.shape[0]):
            ax.plot(weights[i, :], alpha=0.3, color='gray', linewidth=0.5)
    
    # Plot summary statistic
    ax.plot(mean_weights, linewidth=2, color='red', label=f'{summary_stat.title()}')
    
    # Add error bars if requested  
    if error_bars:
        std_weights = np.std(weights, axis=0)
        ax.fill_between(range(len(mean_weights)), 
                       mean_weights - std_weights,
                       mean_weights + std_weights,
                       alpha=0.3, color='red')
    
    # Formatting
    ax.set_xlabel('Time (TRs)')
    ax.set_ylabel('Factor Weight')
    ax.set_title(f'Factor {factor_idx+1} Temporal Weights')
    ax.legend()
    ax.grid(True, alpha=0.3)
    
    return fig
```

### Multi-Panel Overview Visualization
```python
def plot_results_overview(self, output_dir=None, dpi=300, **kwargs):
    """Create comprehensive multi-panel result visualization."""
    
    figures = {}
    
    # Panel 1: All factors as glass brain plots
    fig1 = self.plot_factor_glassbrain(factor_idx=None, **kwargs)
    figures['factors_glassbrain'] = fig1
    
    # Panel 2: Temporal weights for all factors
    fig2, axes = plt.subplots(self.n_factors, 1, figsize=(12, 3*self.n_factors))
    for i in range(self.n_factors):
        self._plot_single_weight(i, ax=axes[i] if self.n_factors > 1 else axes)
    figures['temporal_weights'] = fig2
    
    # Panel 3: Factor weight heatmap
    fig3 = self.plot_weight_heatmap(**kwargs)
    figures['weight_heatmap'] = fig3
    
    # Save all figures if output directory specified
    if output_dir:
        output_dir = Path(output_dir)
        output_dir.mkdir(exist_ok=True)
        
        for name, fig in figures.items():
            fig.savefig(output_dir / f'{name}.png', dpi=dpi, bbox_inches='tight')
            
    return figures
```

## Acceptance Criteria

### Brain Visualization Quality
- [ ] Factor maps rendered with proper anatomical context using MNI templates
- [ ] Statistical thresholding applied with multiple correction options
- [ ] Glass brain plots show clear spatial patterns in all three planes
- [ ] Colormap scaling appropriate for neuroimaging data visualization
- [ ] Publication-quality figures at 300+ DPI resolution

### Temporal Visualization Accuracy
- [ ] Time series plots correctly display factor weights across time
- [ ] Error bars accurately represent across-subject variability
- [ ] Heatmaps show clear temporal patterns with proper scaling
- [ ] Subject grouping functionality works with metadata integration
- [ ] Interactive features (if implemented) provide meaningful data exploration

### Multi-Panel Layout Quality
- [ ] Comprehensive overview figures show all key results in organized layout
- [ ] Consistent styling across all subplot panels
- [ ] Appropriate figure sizing for different display contexts
- [ ] Professional typography and labeling throughout
- [ ] Export functionality produces publication-ready files

### API Usability and Integration  
- [ ] All plotting methods accessible directly from HTFAResults objects
- [ ] Sensible default parameters produce good visualizations without customization
- [ ] Comprehensive customization options available through kwargs
- [ ] Clear error messages for invalid plotting parameters
- [ ] Integration with HTFAResults data without additional data preparation

### Code Quality and Documentation
- [ ] Comprehensive docstrings with parameter descriptions and examples
- [ ] Type hints for all public plotting methods  
- [ ] Consistent error handling across all visualization functions
- [ ] Example usage in docstrings demonstrates common use cases

## Testing Strategy

### Visual Regression Testing
- Generate reference plots with synthetic data for comparison
- Automated testing of plot generation without visual inspection
- Validation of plot data accuracy against known ground truth
- Cross-platform rendering consistency checks

### Functionality Testing
- All plotting methods execute without errors on various data shapes
- Parameter validation catches invalid inputs with clear messages  
- Export functionality creates files in specified formats and locations
- Memory usage remains reasonable for large dataset visualization

### Integration Testing
- End-to-end workflow from HTFA results to publication figures
- Compatibility with different HTFAResults configurations
- Performance testing with realistic dataset sizes
- Cross-validation with other neuroimaging visualization tools

## Dependencies

### Required Components
- **Task 005**: HTFAResults container (provides data access methods)

### External Dependencies
- **nilearn**: Primary brain plotting functionality (plot_stat_map, plot_glass_brain)
- **matplotlib**: Base plotting infrastructure and multi-panel layouts
- **seaborn**: Enhanced statistical plotting and color palettes  
- **numpy**: Numerical operations for data preparation
- **scipy**: Statistical functions for thresholding and analysis

### Optional Dependencies
- **plotly**: Interactive plotting capabilities (if implemented)
- **IPython**: Jupyter notebook integration for inline plots

## Risks and Mitigation

### Technical Risks
- **Memory Usage**: Large brain images may consume excessive memory during plotting
  - *Mitigation*: Implement lazy loading and streaming for large datasets
- **Rendering Performance**: Complex multi-panel plots may be slow to generate
  - *Mitigation*: Provide quick-view options and optimize rendering pipelines
- **Cross-Platform Consistency**: Plotting may appear different across operating systems
  - *Mitigation*: Standardize backend settings and test on multiple platforms

### Usability Risks
- **Parameter Complexity**: Too many customization options may overwhelm users
  - *Mitigation*: Provide sensible defaults and progressive disclosure of options
- **Publication Standards**: Figures may not meet specific journal requirements
  - *Mitigation*: Research common requirements and provide templates

## Effort Estimate

**Size**: Large (L) - 2-3 days

### Breakdown
- **Brain Plotting Implementation**: 10 hours
- **Temporal Weight Visualization**: 8 hours
- **Multi-Panel Layout System**: 6 hours
- **Export and Styling Options**: 4 hours
- **Testing and Quality Assurance**: 6 hours  
- **Documentation and Examples**: 4 hours

**Total**: 38 hours (2.4 days)

## Definition of Done

- [ ] All specified plotting methods implemented in HTFAResults class
- [ ] Brain visualizations use nilearn with professional quality output
- [ ] Temporal weight plots accurately represent time series data with statistics
- [ ] Multi-panel overview functionality creates comprehensive result summaries
- [ ] Export functionality produces publication-ready figures in multiple formats
- [ ] Unit tests validate plot generation and data accuracy
- [ ] Visual regression testing ensures consistent output quality
- [ ] Documentation includes usage examples and customization guidance
- [ ] Code passes all linting, type checking, and quality requirements
- [ ] Integration tests confirm compatibility with HTFAResults data structures

Visualization and Plotting Methods #73

Description

Task 006: Visualization and Plotting Methods

Overview

Objectives

Scope

In Scope

Out of Scope

Technical Requirements

Visualization Methods for HTFAResults Class

Brain Visualization Requirements

Temporal Weight Visualization

Publication Quality Requirements

Implementation Details

Brain Plotting Implementation

Temporal Weight Visualization

Multi-Panel Overview Visualization

Acceptance Criteria

Brain Visualization Quality

Temporal Visualization Accuracy

Multi-Panel Layout Quality

API Usability and Integration

Code Quality and Documentation

Testing Strategy

Visual Regression Testing

Functionality Testing

Integration Testing

Dependencies

Required Components

External Dependencies

Optional Dependencies

Risks and Mitigation

Technical Risks

Usability Risks

Effort Estimate

Breakdown

Definition of Done

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions