Compare Neural Activity Across States¶

This tool uses 1.0 compute credits per hour.

Overview¶

The Compare Neural Activity Across States tool calculates the average modulation of neural activity (calcium traces and optionally, calcium events) during user-specified behavioral states. Specifically, this tool calculates the modulation of neurons during each state relative to other states or baseline periods, validates modulation significance using permutation testing, and classifies neurons as up-, down-, or non-regulated during these states. It provides both tabular results and visualizations.

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	Input cell set files (`.isxd`) to analyze.
Event Set File(s)	False	N/A	Optional corresponding input event set files (`.isxd`). If provided, event-based analysis will also be performed.
Annotations File	True	N/A	Synchronized behavior annotations file.
Concatenate Files End-to-End	True	True	If `True` and multiple cell/event sets are provided, concatenate them before analysis. If `False`, analyze each set individually (Not typically used/recommended).
Method to Rescale Trace Activity Data	False	none	Method to scale trace data before analysis: `None`, `Normalize` (to [0, 1]), `Standardize` (z-score), `Fractional change from baseline`, `Standardize to baseline`.
Method to Rescale Event Rate Data	False	none	Method to scale event rate data: `None`, `Normalize`, `Standardize`, `Fractional change from baseline`, `Standardize to baseline`. Ignored if `Event Set File(s)` are not provided.
Column Name	True	state	Name of the column in the `Annotations File` containing the state labels.
State Names	True	N/A	Comma-separated string of state names from the `Column Name` to analyze (e.g., "StateA,StateB").
State Colors	True	N/A	Comma-separated string of colors (matplotlib compatible) for each state specified in `State Names` (e.g., "red,blue"). Must match the number of states.
Method to compare states	True	state vs not state	Comparison method: `State vs Not State` (compare each state to time outside that state), `Pairwise` (compare all pairs), `State vs Baseline` (compare each state to `Baseline State`), `State vs Not Defined` (compare each state to time outside any defined state).
Baseline State	False	N/A	Name of the state to use as baseline. Required if `Method to compare states` is `State vs Baseline`, or `Method to Rescale Trace Activity Data` or `Method to Rescale Event Rate Data` is `Fractional change from baseline`, or `Standardize to baseline`.
Modulation Colors	True	tab:red, tab:blue	Comma-separated string of two colors for up-regulated and down-regulated cells, respectively (e.g., "tab:red,tab:blue").
Number of Shuffles	False	1000	Number of shuffles to perform for permutation testing to determine p-values.
Significance Threshold	False	0.05	Significance level threshold for determining modulation (p-value cutoff).

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 CheckEvents -- No --> EndWorkflow; 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]; GenTraceOutputs --> JoinEvent[ ] style JoinEvent stroke-width:0, fill:transparent GenEventOutputs --> JoinEvent JoinEvent --> EndWorkflow[Workflow Complete Outputs Generated];

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 methods like normalization, standardization, or fractional change relative to a baseline state (Method to Rescale Trace Activity Data).
Event Rate: If event sets are provided, the tool calculates the event rate (events per second) for each cell. These rates can also be rescaled (Method to Rescale Event Rate Data).

Modulation Score¶

The modulation score quantifies the change in activity between two conditions (e.g., State A vs. State B, or State A vs. Not State A). The specific calculation depends on the Method to compare states:

State vs Not State method: Compares activity during the state vs. activity outside the 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, State vs Baseline, State vs Not Defined methods: Compare activity between two specific states (or state vs. baseline/not defined period).

\[ \text{Modulation} = \frac{ \text{mean activity state 1} - \text{mean activity state 2} }{ \text{mean activity state 1} + \text{mean activity state 2} } \]

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.

The time labels corresponding to the states being compared are randomly shifted (rolled) Number of Shuffles times.
For each shuffle, a surrogate modulation score is calculated.
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 Number of Shuffles (e.g., 1000 shuffles give a resolution of 0.001). A cell's modulation is considered significant if p_value < alpha.

Cell Statuses¶

The tool uses the cell statuses (accepted, undecided, rejected) from the input cell set(s) to determine which cells to include:

If there are accepted cells, only accepted cells are used.
If there are no accepted cells but there are undecided cells, only undecided cells are used.
If all cells are rejected, the workflow raises an error.

Outputs¶

The tool generates CSV files containing detailed modulation data and several preview plots.

Data Files¶

population_data.csv: Contains results based on calcium traces.
event_population_data.csv: Contains results based on calcium event rates (only generated if 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-regulated, 1 for significantly up-regulated, 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 population_data.csv (for Method to compare states='State vs Not State', Method to Rescale Trace Activity Data='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	mean Activity (a.u.) in StateB
C000	-0.0575	0.256	0	8.013	0.0559	0.204	10.882
C001	0.3215	0.006	1	14.862	0.1402	0.058	8.404
C002	-0.2183	0.002	-1	-3.857	-0.0204	0.240	0.290

Note

Column names vary slightly based on the Method to compare states parameter

Previews¶

Multiple SVG plots are generated for quick visualization:

State Time Plot (state_times.svg): Shows the duration and fraction of time spent in each analyzed state.
Trace Preview (trace_preview.svg): Displays traces of all analyzed neurons over time, with background colored by state.
Activity Average Preview (activity_average_preview.svg): Bar plot showing the mean population activity (traces) for each state.
Modulation Footprints (modulation_preview.svg): Cell maps showing spatial footprints. Cells significantly up- or down-regulated (based on trace modulation) are highlighted with specified colors. Separate plots generated for each state comparison.
Modulation Histogram (modulation_histogram_preview.svg): Histograms of modulation scores (traces) for each state comparison, overlaid with markers for significantly modulated cells.
Event Raster Preview (event_preview.svg, Optional): Raster plot showing detected calcium events for all cells over time, with background colored by state.
Event Rate Average Preview (event_average_preview.svg, Optional): Bar plot showing the mean population event rate for each state.
Event Modulation Footprints (event_modulation_preview.svg, Optional): Cell maps highlighting cells significantly modulated based on event rates.
Event Modulation Histogram (event_modulation_histogram_preview.svg, Optional): Histograms of event rate modulation scores.

Note

Optional plots are only generated if Event Set File(s) are provided