Cortical Labs Analysis Toolkit
A modular analysis package for computing electrophysiological and network-level metrics from multi-channel neural recordings of CL1.
The library exposes a high-level cl.RecordingView API that coordinates a suite of rigorously implemented metric functions.
Quick Start
cl.RecordingView is the central interface for analysis. It provides a standardised view over a neural recording and exposes convenience methods that internally call the metric functions defined in this package.
from cl import RecordingView
recording_path = "path/to/recording.h5"
with RecordingView(recording_path) as recording:
# To calculate a metric, replace "metric" with one of the implemented metrics
# Each result object is a type of `AnalysisResult`
result = recording.analyse_metric()
# To create a plot
result.plot()
# To save a result
result.save("path/to/result.json")
# Load a previously saved result
result = AnalysisResult.from_file("path/to/result.json")
For pure analysis workflows, starting of background services (such as for visualisations) can be disabled by setting the environment variable CL_SDK_VISUALISATION=0 either at the top of the analysis script or in the .env file:
import os
os.environ["CL_SDK_VISUALISATION"] = "0"
from cl import RecordingView
# Rest of your code
Implemented Metrics
This document describes all public analysis and visualisation functions exposed by RecordingView.
All analysis functions return typed result objects that are sub-classed from AnalysisResult (e.g. AnalysisResultFiringStats). These objects expose metric values and are designed to be inspectable and reusable in downstream analysis.
The table below lists all public analysis and visualisation methods exposed by cl.RecordingView.
| RecordingView method | Short description |
|---|---|
cl.RecordingView.plot_spikes_and_stims |
Raster plot of spikes and optional stimulation events. |
cl.RecordingView.analyse_firing_stats returns AnalysisResultFiringStats |
Basic firing statistics from binned spike activity. |
cl.RecordingView.analyse_network_bursts returns AnalysisResultNetworkBursts |
Detect network-level bursts using population spike-rate thresholding. |
cl.RecordingView.analyse_criticality returns AnalysisResultCriticality |
Detect neuronal avalanches and compute criticality metrics. |
cl.RecordingView.analyse_information_entropy returns AnalysisResultInformationEntropy |
Per-bin Bernoulli entropy from fraction of active channels. |
cl.RecordingView.analyse_lempel_ziv_complexity returns AnalysisResultComplexityLempelZiv |
Per-channel LZ78 complexity of binned spike sequences. |
cl.RecordingView.analyse_dct_features returns AnalysisResultDctFeatures |
Spatial DCT features from per-channel spike counts on the MEA layout. |
cl.RecordingView.analyse_spike_triggered_histogram returns AnalysisResultSpikeTriggeredHistogram |
Spike-triggered histograms for ordered channel pairs. |
cl.RecordingView.analyse_functional_connectivity returns AnalysisResultsFunctionalConnectivity |
Functional connectivity and additional graph summaries. |
Result Objects and Visualisation
All analysis functions described above return typed result objects (e.g. AnalysisResultCriticality, AnalysisResultDctFeatures). These result objects are designed to support standardised visualisation.
Saving and Loading Results
All result objects support persistence and can be saved to disk and reloaded without recomputation.
Typical usage pattern:
result = recording.analyse_criticality(...)
result.save("criticality_result.json")
loaded = AnalysisResultCriticality.from_file("criticality_result.json")
Saved results include:
- Computed metric values
- Analysis parameters
- Metadata required for reproducibility
- (Optional) Metadata required for plotting
Basic Visualisation
cl.RecordingView.plot_spikes_and_stims creates a raster plot of spike events and (optionally) stimulation events for a neural recording, with optional restrictions on the displayed time range and channel subset.
from cl import RecordingView
with RecordingView(recording_path) as recording:
recording.plot_spikes_and_stims()
Figure: Detected spikes and delivered stimulations on sample recorded channels.
Built-in Plotting Interface
Some result objects provide a .plot() method for quick, standardised visualisation of the analysis outcome.
These plotting methods are intended for exploratory analysis, diagnostics, and reporting.
The following result types expose a .plot() interface:
- Network burst analysis
- Discrete Cosine Transform (DCT) features
- Criticality analysis
- Spike-triggered histograms
- Functional connectivity
Network burst analysis
Created with AnalysisResultNetworkBursts.plot().
Figure: Average network firing and detected network bursts.
result = recording.analyse_network_bursts()
result.plot()
Discrete Cosine Transform (DCT)
Created with AnalysisResultDctFeatures.plot().
.png)
Figure: Spatial DCT basis functions (k = 3) defined over the MEA layout.
result = recording.analyse_dct_features(k=3)
result.plot()
Criticality Analysis
Created with AnalysisResultCriticality.plot_avalanche_sizes(), AnalysisResultCriticality.plot_avalanche_durations(), and AnalysisResultCriticality.plot_deviation_from_criticality_coefficient().
.png)
.png)
.png)
Figure: Neuronal avalanche size and duration distributions as well as the DCC estimation.
Created with AnalysisResultCriticality.plot_branching_ratio().
Figure: Branching ratio estimated.
Created with AnalysisResultCriticality.plot_avalanche_shape_collapse_analysis().
.png)
Figure: Neuronal avalanche shape collapse metrics and scaled avalanche profiles.
result = recording.analyse_criticality(...)
result.plot_avalanche_sizes()
result.plot_avalanche_durations()
result.plot_deviation_from_criticality_coefficient()
result.plot_branching_ratio()
result.plot_avalanche_shape_collapse_analysis()
Spike-Triggered Histograms
Created with AnalysisResultSpikeTriggeredHistogram.plot().
Figure: Spike-triggered histogram results visualise selected population responses aligned to trigger spikes from selected high-activity channels.
result = recording.analyse_spike_triggered_histogram(...)
result.plot()
Functional Connectivity
Created with AnalysisResultsFunctionalConnectivity.plot().
Figure: Functional connectivity results support visualisation of derived graph representations, where edge weights encode pairwise correlation strengths and node colours indicate membership in detected Louvain communities. .
result = recording.analyse_functional_connectivity(...)
result.plot()
Notes
- Plotting methods are non-destructive and do not modify stored results.
- Saved result files remain fully compatible with plotting after reload.
cl.analysis
Contains metadata relating to the recording for analysis results.
Base analysis class for one recording.
Burst analysis results for one recording.
Specifies firing rate over time shape (time_bin_count,).
Frames that a spike has occurred (values) for each channel (keys).
Creates a visualisation of the spikes and bursts in this recording, containing:
- Upper: a line plot of the spike rate per channel and time bin, and
- Lower: a raster plot of spikes with bursts as highlighted regions.
Arguments:
- figsize: Size of the plot figure.
- title: Title for the plot, if not provided, a default will be used.
- save_path: Path to the save the plot instead of showing it.
- limit_to_time_range_secs: If provided, limit the time axis as a tuple of
(start_time_secs, end_time_secs).
Criticality analysis results for one recording.
Spike counts for each time bin in each avalanche, also known as "shape".
Calculated as the absolute difference between beta_exponent and scaling_relation_exponent_fitted.
Duration of intervals between avalanches in number of frame bins.
Average spike counts per bin sorted by duration, also known as "profile".
Estimated standard deviation of the beta exponent over n_bootstraps. Could be NaN if there is not enough profiles to consider (min 2).
Minimum value (x0) that minimizes the KS statistic for avalanche spike counts (sizes).
Minimum value (x0) that minimizes the KS statistic for avalanche durations (sizes).
Kolmogorov-Smirnov statistic for avalanche spike counts (sizes).
Exclusion bounds used for calculating ks_statistic_spike_counts.
Exclusion bounds used for calculating ks_statistic_durations.
Deviation from criticality coefficient, i.e. deviation of predicted and fitted scaling relation exponents.
Creates a plot of Avalanche sizes and its fitted PDF.
Arguments:
- figsize: Size of the plot figure.
- title: Title for the plot, if not provided, a default will be used.
- save_path: Path to the save the plot instead of showing it.
- ax: Axes draw the plots. (Defaults to None).
Return:
Axes: Axes on which the plot was drawn.
Creates a plot of Avalanche durations and its fitted PDF.
Arguments:
- figsize: Size of the plot figure.
- title: Title for the plot, if not provided, a default will be used.
- save_path: Path to the save the plot instead of showing it.
- ax: Axes draw the plots. (Defaults to None).
Return:
Axes: Axes on which the plot was drawn.
Creates a plot of Deviation from Criticality Coefficient (DCC).
Arguments:
- figsize: Size of the plot figure.
- title: Title for the plot, if not provided, a default will be used.
- save_path: Path to the save the plot instead of showing it.
- ax: Axes draw the plots. (Defaults to None).
Return:
Axes: Axes on which the plot was drawn.
Creates three plots based on avalanche shape collapse analysis, being:
- Scaled Variance at Optimal Beta
- Collapse Metric vs Scaling Exponent
- Scaled Avalanche Profiles (Shape Collapse)
Arguments:
- figsize: Size of the plot figure.
- title: Title for the plot, if not provided, a default will be used.
- save_path: Path to the save the plot instead of showing it.
- axes: List of three Axes to draw the plots. (Defaults to None).
Returns:
list[Axes]: List of three Axes used to draw the plots.
Discrete Cosine Transform (DCT) analysis results for one recording.
Dictionary mapping DCT coefficients to their values. Keys are formatted as "dct{i}{j}_firing" where i, j are spatial indices for rows / columns respectively.
Creates a (k x k) plot of DCT coefficients.
Arguments:
- figsize: Size of the plot figure.
- title: Title for the plot, if not provided, a default will be used.
- save_path: Path to the save the plot instead of showing it.
- cmap: Colour map override.
Returns:
Figure: The figure used to create the plot.
Firing stat analysis for one recording.
Size of each time bin in seconds which governs time units for value interpretation.
Array of spike count for each channel and time bin with shape (channel_count, bin_count).
Array of spike firing rates in time units for each channel and time bin with shape (channel_count, bin_count).
Mean firing rate in time units for each channel as a list with length channel_count.
Variance in firing rate in time units for each channel as a list with length channel_count.
Variance in firing rate in time units across all channels and time bins.
Maximum firing rate in time units across all channels and time bins.
List of inter-spike intervals (ISI) in time units for each channel, where the outer list has length channel_count.
Mean inter-spike intervals (ISI) in time units for each channel, with length channel_count.
Functional Connectivity (FC) analysis results for one recording.
Absolute correlation threshold in [0, 1] for constructing the FC graph.
Weighted adjacency matrix for the thresholded FC graph, shape (channel_count, channel_count).
Creates a visualisation of functional connectivity where the edges are Pearson correlations and nodes are coloured by Louvain community where applicable.
Arguments:
- figsize: Size of the plot figure.
- title: Title for the plot, if not provided, a default will be used.
- save_path: Path to the save the plot instead of showing it.
- ax: Axes draw the plots. (Defaults to None).
Information entropy analysis results for one recording.
Lempel-Ziv Complexity (LZC) analysis results for one recording.
Spike triggered histogram analysis results for one recording.
Threshold in Hz that defines eligibility of a channel for analysis.
Spike triggered histograms for each pair of top eligible channels by mean firing rate.
Creates a plot of all the histograms.
Arguments:
- figsize: Size of the plot for each histogram.
- title: Title for the plot, if not provided, a default will be used.
- save_path: Path to the save the plot instead of showing it.
- axes: List of Axes (one for each histogram) to draw the plots. (Defaults to None).
Returns:
list[Axes]: List of Axes drawn with the histogram.
Float type that support serialisation of special floats like nan and inf.
A 1D float NumPy array type that serialises to a list.
A 1D integer NumPy array type that serialises to a list.
A 2D integer NumPy array type that serialises to a list.
A 2D float NumPy array type that serialises to a list.
Represents a single burst with start and end times in frames.
A collection of Burst objects.