Compare State-Epoch Data Between Groups¶

Overview¶

The Compare State-Epoch Data Between Groups workflow compares state-epoch activity, correlation, and modulation metrics across two experimental groups using the CSV/H5 outputs generated by the Compare State Data Across Epochs tool. It ingests the per-group activity_per_state_epoch_data.csv, correlations_per_state_epoch_data.csv (or raw correlation H5 files), and modulation_vs_baseline_data.csv, then produces harmonized group tables, statistical summaries, and publication-ready previews. The comparison can be performed across states or epochs (one dimension per run) and supports trace-only, event-only, or dual-measure analyses.

Key capabilities:

• Validates that both groups share the same baseline state-epoch reference, state list, epoch list, and baseline modulation metadata.
• Supports paired or unpaired comparisons, automatic or user-specified parametric tests, and multiple correction strategies (Bonferroni, FDR, etc.).
• Calculates per-group descriptive statistics, ANOVA-style summaries, pairwise tests, and optional linear mixed-model (LMM) analyses for cell-level metrics.
• Reclassifies modulation significance at a new α threshold when requested, preserving the alpha/2 logic used in the baseline tool.
• Runs either two-group comparisons or a single-group collapse; single-group mode aggregates all provided recordings and reports within-group ANOVA/pairwise statistics while retaining the same output directory layout.

Design Benefits¶

• Structured inputs: By reusing the single-tool outputs (activity, correlation, modulation), each group already shares state/epoch labels, baseline metadata, and scaling, so comparison code can stay focused on higher-level logic.
• Orthogonal flow control: Two explicit branches—trace vs event and state vs epoch—allow users to toggle modalities or comparison axes independently without touching other parameters.
• Targeted statistics: Limiting the engine to 2-way ANOVAs (state-by-group or epoch-by-group) avoids 3-way complexity while matching how the single tool reports per-dimension summaries; multiple-comparison correction is applied within each tested context.

Input Data¶

All input files must come directly from Compare State Data Across Epochs and use the same configuration (states, epochs, baseline definitions, scaling choices). Each run must include at least two activity_per_state_epoch_data.csv files for Group 1 because the statistical tests require more than one subject. You may omit Group 2 entirely to run a single-group analysis; when two groups are supplied, every modality present for Group 1 must also be provided for Group 2 with matching file counts so comparisons remain balanced.

Group consistency requirements¶

• Baseline match: Both groups must share identical baseline_state and baseline_epoch values embedded in their modulation CSVs.
• State/Epoch match: The ordered lists of state names and epoch names must match exactly; otherwise execution stops with an informative error.
• Subject identifiers: Subject IDs (from normalized_subject_id) must follow the standardized format. When data_pairing="paired", subject_matching aligns files using one of the supported strategies: number (match digits in filenames), filename (exact basename), or order (original list order, used as the fallback). At least two matched subjects are required.
• Modality parity: In two-group runs, correlation and modulation inputs must be present for Group 2 whenever they exist for Group 1 so the tool can build balanced statistics.

Correlation inputs options¶

• CSV path: correlations_per_state_epoch_data.csv files for each recording. This is the preferred (future default) format.
• H5 path: pairwise_correlation_heatmaps.h5 files with trace/<state-epoch> and/or event/<state-epoch> datasets. These remain supported for backward compatibility; the tool automatically converts them into the same column structure as the CSV files.

If neither CSV nor H5 correlation data is provided, correlation analyses and previews are skipped.

Parameters¶

Highlights:

• comparison_dimension: choose "states" or "epochs" to drive the aggregation and visualization axis.
• measure_source: "trace", "event", or "both" to control whether analyses run on traces, events, or both modalities independently.
• correlation_statistic: "max", "mean", or "min" selects the per-cell correlation metric that feeds the summaries and previews (positive/negative population averages are always added).
• data_pairing & subject_matching: set "paired" vs "unpaired" plus the matching rule used only in paired mode (number for digits inside filenames, filename/name for exact basename matches, or order to keep the provided ordering). Paired mode requires ≥2 matched subjects.
• multiple_correction & multiple_correction_scope: configure family-wise error control globally or within strata (within_stratum, with per_condition accepted as an alias).
• parametric: "auto" (data-driven parametric/non-parametric selection), "True" (force parametric; raises an error if assumptions fail), or "False" (always use non-parametric tests).
• enable_lmm_analysis: toggles the optional linear mixed-effects pipeline for cell-level measures; save_lmm_outputs adds per-comparison CSVs summarizing model fits.

Workflow¶

Processing steps¶

1. Validation & metadata alignment
2. Ensures required CSV/H5 files exist and share the same states, epochs, baseline, and color metadata.

3. Normalizes group names/colors (or generates defaults) and records them for output labeling.

4. Subject matching & pairing

5. Aligns subjects across groups using the configured subject_matching rule (number, filename, or order) whenever data_pairing="paired".

6. Handles paired vs. unpaired scenarios and logs dropped or unmatched subjects.

7. Measure selection

8. Builds unified column sets (activity, per-cell correlations, population correlations, modulation counts) based on measure_source and correlation_statistic.

9. For modulation data, can reclassify neurons at a custom significance threshold while respecting alpha/2 directionality.

10. Statistical testing

11. Produces ANOVA-style summaries and pairwise test tables for each metric.
12. Optional LMM analysis (when enabled and data are cell-level) uses subject and cell IDs as random effects to detect subtle group-by-state/epoch interactions.

13. Multiple-comparison corrections (Bonferroni, FDR, etc.) are applied either globally or within each stratum.

14. Visualization

15. Generates per-group boxplots/CDFs for activity and correlations, modulation distributions, and comparison-level summaries for the selected dimension.
16. Preview SVGs are stored alongside the CSV outputs in .previews/ subdirectories.

Outputs¶

All outputs are organized under the chosen output_dir with descriptive subfolders. Key artifacts include:

1. Per-group combined data
2. <group>_combined_activity_data/<comparison>_<group>_combined_activity_data.csv
3. <group>_combined_trace_correlation_data/<comparison>_<group>_combined_trace_correlation_data.csv
4. <group>_combined_modulation_data/<comparison>_<group>_combined_modulation_data.csv

5. Each folder contains matching preview SVGs inside .previews/, including <group>_{trace|event}_activity_boxplot.svg, <stat>_{trace|event}_correlation_{boxplot|cdf}.svg for every requested correlation_statistic, <positive|negative>_{trace|event}_population_boxplot.svg, and <group>_{trace|event}_modulation_distribution.svg (event variants appear only when event data are analyzed).

6. Trace statistical summaries

7. trace_aov_comparisons/<comparison>_trace_aov_comparisons.csv

8. trace_pairwise_comparisons/<comparison>_trace_pairwise_comparisons.csv

9. Event statistical summaries (when event data are available)

10. event_aov_comparisons/<comparison>_event_aov_comparisons.csv

11. event_pairwise_comparisons/<comparison>_event_pairwise_comparisons.csv

12. Optional LMM outputs

13. Saved only when enable_lmm_analysis and save_lmm_outputs are True; file names follow the same <comparison>_<measure>_lmm_results.csv convention.

14. Comparison previews

15. Trace comparisons: states_comparison_trace_activity.svg, states_comparison_trace_correlation.svg, states_comparison_trace_positive_correlation.svg, states_comparison_trace_negative_correlation.svg, states_comparison_trace_modulation.svg, states_comparison_trace_up_modulated_counts.svg, and states_comparison_trace_down_modulated_counts.svg (automatically switched to the epochs_ prefix when comparison_dimension="epochs").
16. Event comparisons: the same set of filenames with _event_ instead of _trace_ are generated whenever event measures are part of the analysis.

All CSVs include metadata columns for state/epoch identifiers, group labels, subject IDs, source filenames, and the statistical annotations (test type, effect size, corrected p-values) needed for downstream reporting.

Example Combined Activity Output¶

Example Combined Correlation Output¶

Example Combined Modulation Output¶

Example Trace ANOVA Output¶

Example Trace Pairwise Output¶

Example LMM Output (optional)¶

Previews¶

The preview examples below correspond to the epochs comparison mode (Group 1 vs. Group 2 across epochs) using trace metrics. When comparison_dimension="states" or when measure_source includes events ("event" or "both"), the tool generates the same family of figures with state-level layouts and/or event-specific data, following the exact styling shown here.

Additional per-group previews for positive/negative population correlations and the event-based activity/correlation/modulation plots are produced automatically when those modalities are analyzed. Similarly, comparison-level modulation prevalence figures (states/epochs_comparison_{trace|event}_modulation.svg) accompany the up/down count charts even though only the trace-based epoch examples are illustrated below.

Group-level activity and correlation¶

Modulation distributions¶

Comparison summaries¶