Skip to content

Compare Neural Activity Across States

Compute Credits

This tool uses 1.0 compute credits per hour.

Overview

The Compare Neural Activity Across States tool analyzes neural population activity modulation across behavioral states by quantifying how calcium traces and calcium events change during user-specified states. The tool computes modulation scores relative to comparison conditions, validates statistical significance through permutation testing, and classifies neurons as significantly up-modulated, down-modulated, or non-modulated. Results include comprehensive data files and visualizations for detailed analysis.

Input Data

This tool requires synchronized neural activity data and behavioral annotations. It can analyze calcium trace data and optionally calcium event data.

Valid Inputs

File Type Required? Description
Cell Set File (.isxd) Yes One or more cell set files containing calcium traces and cell spatial footprints. If multiple are provided, they can be concatenated.
Event Set File (.isxd) No Optional. One or more event set files containing detected calcium events. Must correspond to the cell set files.
Annotations File (.parquet) Yes A single synchronized annotations file (e.g., from sync_csv_to_annotations) containing behavioral state labels aligned with the neural data.

Generating synchronized annotation files

You can generate the synchronized annotation file by running one of these synchronization tools:

Parameters

Parameter Required? Default Description
Cell Set File(s) True N/A ISXD cell set file(s)
Event Set File(s) False N/A ISXD event set file(s)
Annotations File True N/A Experiment Annotations file
Concatenate Files End-to-End True True Whether to concatenate the cell set files end-to-end, or space them according to their original timestamps
Method to Rescale Trace Activity Data False none The trace activity data will be rescaled using the specified method. If 'none' is selected, the original raw calcium trace values will be used without any transformation, preserving the original scale of the measurements.
Method to Rescale Event Rate Data False none If specified, the event rate data will be rescaled using the specified method
Column Name True state Column name in annotations file with states
State Names True N/A Names of states to compare.
State Colors True N/A List of matplotlib compatible colors to represent each state
Method to compare states True state vs not state The method to compare states against each other
Baseline State False N/A Optional parameter to define the baseline state for comparison if method is state vs baseline, or for rescaling if method is standardize to baseline or fractional change
Modulation Colors True tab:red, tab:blue Colors to represent up and down modulation respectively
Number of Shuffles False 1000 Number of shuffles to determine if a neuron is significantly modulated by state
Significance Threshold False 0.05 Significance threshold (alpha) below which p-values are considered significant.

Algorithm Details

The following diagram demonstrates the steps of the tool algorithm.

graph TD Start[Start Workflow] --> LoadData[Load Input Data Cell Sets Annotations Optional Event Sets]; LoadData --> PlotStateTime[Plot State Time Distribution]; PlotStateTime --> TraceAnalysis{Trace Analysis}; style TraceAnalysis fill:#f9f,stroke:#333,stroke-width:1px TraceAnalysis --> PlotRawTraces[Plot Raw Traces Preview]; TraceAnalysis --> AnalyzeTraceMod[Analyze Trace Modulation]; AnalyzeTraceMod --> GenTraceOutputs[Generate Trace Outputs]; style GenTraceOutputs fill:#f9f,stroke:#333,stroke-width:1px GenTraceOutputs --> PlotTraceAvg[Average Activity Plot]; GenTraceOutputs --> PlotTraceFootprints[Modulation Footprints Plot]; GenTraceOutputs --> PlotTraceHistograms[Modulation Histograms Plot]; GenTraceOutputs --> SaveTraceCSV[Trace Results CSV]; PlotStateTime --> CheckEvents{Event Data Provided?}; style CheckEvents fill:#ddd,stroke:#333,stroke-width:1px CheckEvents -- Yes --> EventAnalysis{Event Analysis}; style EventAnalysis fill:#ccf,stroke:#333,stroke-width:1px EventAnalysis --> PlotEventRaster[Plot Event Raster Preview]; EventAnalysis --> AnalyzeEventMod[Analyze Event Rate Modulation]; AnalyzeEventMod --> GenEventOutputs[Generate Event Outputs]; style GenEventOutputs fill:#ccf,stroke:#333,stroke-width:1px GenEventOutputs --> PlotEventAvg[Average Event Rate Plot]; GenEventOutputs --> PlotEventFootprints[Event Modulation Footprints Plot]; GenEventOutputs --> PlotEventHistograms[Event Modulation Histograms Plot]; GenEventOutputs --> SaveEventCSV[Event Results CSV];

The following sections describes the metrics and procedures performed by the algorithm.

Activity Measures

  • Trace Activity: The mean of the calcium trace signal during a given state or period is used. Traces can be optionally rescaled using several methods:

    • none: Original raw calcium trace values are preserved without any transformation, maintaining the original scale and units of measurement
    • normalize: Scales all trace values to the range [0, 1] by applying min-max normalization across the entire recording period
    • standardize: Converts traces to z-scores by subtracting the mean and dividing by the standard deviation across the entire recording, centering data around zero
    • fractional_change: Calculates the ratio of activity to baseline state mean after ensuring non-negative values: activity / baseline_mean
    • standardize_baseline: Computes z-scores relative to the baseline state by subtracting the baseline mean and dividing by baseline standard deviation

  • Event Rate: If event sets are provided, the tool calculates the event rate (events per second) for each cell. These rates can be rescaled using the same methods as trace activity, with the baseline-dependent methods requiring a specified baseline state.

Modulation Score

The modulation score quantifies the change in activity between two conditions. The specific calculation depends on the comparison method:

State vs Not State Method

Compares activity during each specified state against activity during all time periods outside that state.

\[ \text{Modulation} = \frac{ \text{mean activity during state} - \text{mean activity not during state} }{ \text{mean activity during state} + \text{mean activity not during state} } \]

Pairwise Method

Compares activity between every possible pair of specified states.

\[ \text{Modulation} = \frac{ \text{mean activity state A} - \text{mean activity state B} }{ \text{mean activity state A} + \text{mean activity state B} } \]

State vs Baseline Method

Compares activity during each specified state against activity during the designated baseline state.

\[ \text{Modulation} = \frac{ \text{mean activity during state} - \text{mean activity during baseline} }{ \text{mean activity during state} + \text{mean activity during baseline} } \]

State vs Not Defined Method

Compares activity during each specified state against activity during time periods not assigned to any defined state.

\[ \text{Modulation} = \frac{ \text{mean activity during state} - \text{mean activity not defined} }{ \text{mean activity during state} + \text{mean activity not defined} } \]

Note

Before calculation, a minimum value subtraction is applied to ensure activity values are non-negative, bounding the score between -1 and 1

Significance Level (p-value)

The significance of the calculated modulation score is determined using a circular permutation test.

  1. The time labels corresponding to the states being compared are randomly shifted (rolled) for the specified number of shuffles.
  2. For each shuffle, a surrogate modulation score is calculated.

  3. The p-value is calculated as the minimum of:

    a. The proportion of shuffled scores greater than the original score. b. The proportion of shuffled scores less than the original score.

This yields a two-tailed p-value. The resolution of the p-value depends on the number of shuffles (e.g., 1000 shuffles give a resolution of 0.001). A cell's modulation is considered significant if p-value < significance threshold.

Cell Selection Criteria

The tool uses cell status information from the input cell set(s) to determine which cells to include in the analysis:

  • Accepted cells: When present, only accepted cells are analyzed
  • Undecided cells: Used when no accepted cells are available
  • Rejected cells: If all cells are rejected, the tool terminates with an error

Outputs

The tool generates CSV files containing detailed modulation data and comprehensive visualization previews.

Data Files

  • trace_population_data.csv: Contains modulation analysis results based on calcium traces
  • event_population_data.csv: Contains modulation analysis results based on calcium event rates (generated only when Event Set File(s) are provided)

Each row corresponds to a single cell. Columns include:

  • name: Cell identifier.
  • modulation scores in {state} or modulation scores in {s1} vs {s2}: The calculated modulation score.
  • p-values in {state} or p-values in {s1} vs {s2}: The p-value from the permutation test.
  • modulation in {state} or modulation in {s1} vs {s2}: Modulation identity (-1 for significantly down-modulated, 1 for significantly up-modulated, 0 for non-significant).
  • mean {unit} in {state}: The average activity (trace or event rate, potentially scaled) for the cell during that state. The {unit} depends on the scaling method used (e.g., "Activity (a.u.)", "Normalized event rate", "z-score").

Example trace_population_data.csv (for comparison method 'state vs not state', rescaling method 'none'):

name modulation scores in StateA p-values in StateA modulation in StateA mean Activity (a.u.) in StateA modulation scores in StateB p-values in StateB modulation in StateB mean Activity (a.u.) in StateB
C000 -0.0575 0.256 0 8.013 0.0559 0.204 0 10.882
C001 0.3215 0.006 1 14.862 0.1402 0.058 0 8.404
C002 -0.2183 0.002 -1 -3.857 -0.0204 0.240 0 0.290

Note

Column names vary slightly based on the comparison method parameter

Previews

The tool generates comprehensive SVG visualizations for data interpretation:

State Time Analysis

Displays the duration and fractional time spent in each analyzed behavioral state.

State Time Plot

Neural Trace Preview

Shows calcium traces for the first 50 analyzed neurons over time, with background shading indicating behavioral states.

Trace Preview

Population Activity Summary

Box plots displaying mean population activity (calcium traces) for each behavioral state with individual cell data points overlaid.

Activity Average Preview

Spatial Modulation Map

Spatial footprint visualization showing significantly up-modulated and down-modulated cells using specified colors, with significantly modulated cells indicated by a dark outline. Generated for each state comparison.

Modulation Footprints

Modulation Distribution

Histograms showing modulation score distributions for each state comparison, with color-coded regions indicating the range of modulation scores.

Modulation Histogram

Event Raster Display

Raster plot visualizing detected calcium events across all cells over time, with background shading indicating behavioral states.

Event Raster Preview

Event Rate Summary

Box plots showing mean population event rates for each behavioral state with individual cell data points.

Event Rate Average Preview

Event-Based Spatial Modulation

Spatial footprint maps showing cells with significant event rate modulation using specified colors, with significantly modulated cells indicated by a dark outline.

Event Modulation Footprints

Event Modulation Distribution

Histograms displaying event rate modulation score distributions with color-coded regions indicating the range of modulation scores.

Event Modulation Histogram

Note

Event-based visualizations are generated only when Event Set File(s) are provided in the analysis