Add demo script for CAR method comparison

[abuzarmahmood]

Summary

Implements demos/car_improvement.py that calculates and saves correlations between channels before and after Common Average Reference (CAR) for three cases:

1. No scaling (original): User-specified CAR groups, simple averaging without channel normalization
2. With scaling: User-specified CAR groups, channels normalized by median/MAD before averaging
3. Clustering + scaling: Automatic clustering based on correlation matrix, with channel normalization

Outputs

The script generates comparison plots and statistics saved to QA_output/car_demo/:

• car_comparison_heatmaps.png: Side-by-side correlation matrices for all methods
• car_comparison_paired_plot.png: Paired points showing correlation changes per channel pair
• car_comparison_summary.png: Bar plot of mean correlations by method
• car_comparison_summary.txt: Text summary with statistics
• NetCDF files with correlation matrices for further analysis

Usage

python demos/car_improvement.py <data_dir> [--n_samples 10000] [--max_clusters 10]

Closes #735

Ref: #730

[abuzarmahmood]

Solution Explanation

This demo script addresses issue #735 by implementing a standalone comparison tool for the three CAR approaches discussed in PR #730.

Implementation Details

Method 1 - No Scaling (Original blech_clust)

• Simply averages all channels within each user-specified CAR group
• Subtracts this average from each channel
• This was the original approach and doesn't account for differences in channel impedance/scale

Method 2 - With Scaling

• Normalizes each channel by subtracting median and dividing by MAD (Median Absolute Deviation)
• Computes CAR on normalized channels
• Converts back to original scale after subtraction
• This accounts for impedance differences between channels

Method 3 - Clustering + Scaling

• Uses PCA on the pre-CAR correlation matrix to extract features
• Applies K-Means clustering with BIC model selection to find optimal groupings
• Applies scaled CAR within each cluster
• This automatically groups channels with similar noise characteristics

Key Design Decisions

1. Subsampling: Uses configurable n_samples (default 10000) for correlation calculation to balance accuracy and speed

2. Correlation calculation: Uses Pearson correlation on z-scored data, consistent with the existing channel_corr.py utilities

3. Output format: Saves both plots and NetCDF files for downstream analysis, matching the existing QA output conventions

4. Standalone operation: The script can be run independently on any processed data directory without modifying the main pipeline

Testing

The script requires a data directory with:

• HDF5 file with raw electrode data
• Electrode layout CSV with CAR_group assignments

Run with: python demos/car_improvement.py <data_dir>