cicada-tools API Reference¶
Package: cicada-analysis
Base import path: from cicada_analysis.cicada_tools.<module> import <function>
Event Alignment¶
Module: cicada_analysis.cicada_tools.core.event_alignment
Use when you want fixed-length windows of data centered on each event.
from cicada_analysis.cicada_tools.core.event_alignment import (
align_array_to_events,
align_array_to_timestamps,
event_aligned_array_to_long_format_df,
)
align_array_to_events(
data: np.ndarray, # (n_cells, n_times) traces, or (n_frames, H, W) for widefield
event_frames: list, # list of frame indices (int)
window_frames: tuple, # (n_frames_before, n_frames_after)
subtract_baseline: bool = False
)
# → np.ndarray
# If data is 2D (n_cells, n_times): returns (n_cells, n_events, n_t)
# If data is 3D (n_frames, H, W): returns (n_events, n_t, H, W)
align_array_to_timestamps(
data: np.ndarray, # (n_cells, n_times)
event_timestamps: np.ndarray, # (N,) event times in seconds — extract row 0 from (2,N) NWB output
frame_timestamps: np.ndarray, # (n_times,) trace timestamps in seconds
window_s: tuple, # (seconds_before, seconds_after)
subtract_baseline: bool = False,
time_axis: int = 1, # 0: time-first data (n_times,) or (n_times, n_features), e.g. DLC / Facemap
drop_outside: bool = False # True: drop events whose window leaves the recording (default NaN)
)
# → np.ndarray (n_cells, n_events, n_t); with time_axis=0: (n_events, n_t) or (n_events, n_t, n_features)
# Timestamp-based wrapper around align_array_to_events. The only alignment function on event times.
event_aligned_array_to_long_format_df(
array: np.ndarray, # (n_events, n_window_frames, ...) aligned output
time_range: tuple, # (t_before, t_after) in seconds
time_step: float # bin size in seconds
)
# → pd.DataFrame (long format: columns time, cell/feature, trial, value)
PSTH — Calcium Imaging¶
Module: cicada_analysis.cicada_tools.imaging.psth_utils
from cicada_analysis.cicada_tools.imaging.psth_utils import (
build_population_psth,
combine_population_psth,
build_psth_dataframe,
align_single_cell_to_epochs,
)
build_population_psth(
data: np.ndarray, # (n_cells, n_times)
epochs: list, # list of (start_frame, stop_frame) tuples
ref_in_epoch: str, # 'start' | 'end' | 'middle' — reference point within epoch
range_value: tuple, # (n_frames_before, n_frames_after)
fcts_to_apply: list, # callables applied across trials, e.g. [np.mean, np.std]
data_type: str = 'traces', # 'traces' | 'raster'
cell_reduction: str = 'mean', # how to reduce across cells
baseline_subtraction: bool = False
)
# → tuple (frames_indices, psth_values)
# Lightweight summary PSTH — does not produce a DataFrame.
combine_population_psth(
session_data_list: list, # list of (frames_indices, psth_values) tuples
bins_edges: np.ndarray, # common time grid
session_fcts: list | None = None # per-session transforms before combining
)
# → tuple (time_x_values, [central, low, high])
build_psth_dataframe(
data: np.ndarray, # (n_cells, n_times) traces
event_timestamps: np.ndarray, # (N,) event times in seconds
frame_timestamps: np.ndarray, # (n_times,) trace timestamps in seconds
window_s: tuple, # (seconds_before, seconds_after)
subtract_baseline: bool = False,
baseline_event_timestamps: np.ndarray | None = None, # alternative timestamps for baseline
roi_indices: np.ndarray | None = None, # subset of cells to include
session_id: str | None = None,
mouse_id: str | None = None,
trial_type: str | None = None,
extra_metadata: dict | None = None # {col_name: value} added to every row
)
# → pd.DataFrame (long format: one row per cell × trial × timepoint)
# This is NOT a wrapper around build_population_psth — it calls align_array_to_timestamps
# internally and builds a tidy DataFrame (e.g. for stats.line_and_band and plot_psth_lines).
align_single_cell_to_epochs(
cell_data, # 1D array (n_times,)
epochs, # list of (start_frame, stop_frame) tuples
ref_in_epoch, # 'start' | 'end' | 'middle'
range_frames, # (n_frames_before, n_frames_after)
n_total_frames,
filter_consecutive: bool = False,
fcts_to_apply=None,
low_percentile: int = 25,
high_percentile: int = 75,
psth_range_in_ms=None,
verbose: bool = False
)
# → dict per-trial windows and summary stats for a single cell
PSTH — Electrophysiology¶
Module: cicada_analysis.cicada_tools.ephys.psth_utils
from cicada_analysis.cicada_tools.ephys.psth_utils import (
compute_psth,
baseline_indices,
apply_baseline,
unit_psth_table,
spikes_around_events,
)
compute_psth(
spike_times: list[np.ndarray], # list of 1D arrays, one per unit
event_times: np.ndarray, # (N,) event times in seconds — extract row 0 from (2,N) NWB output
window_start: float, # window start relative to the event, s (negative: -0.5 = 0.5 s before)
window_end: float, # window end relative to the event, s
bin_size: float # bin size in seconds
)
# → tuple (psth: np.ndarray (n_events, n_bins, n_units), time: np.ndarray (n_bins,))
# Output is in Hz.
baseline_indices(time: np.ndarray, baseline_duration: float)
# → np.ndarray — indices of bins in [-baseline_duration, 0]
apply_baseline(
peth_matrix: np.ndarray, # (n_events, n_bins, n_units)
time: np.ndarray, # (n_bins,)
baseline_duration: float, # seconds of pre-event baseline to subtract
zscore: bool = False
)
# → tuple (corrected: np.ndarray, bl_std: np.ndarray)
unit_psth_table(
binned: np.ndarray, # (n_events, n_bins, n_units), from compute_psth
time: np.ndarray, # bin right edges, from compute_psth
unit_ids: list,
reduction="median", band="percentiles", low_percentile=25, high_percentile=75, # as stats.line_and_band
baseline_duration=0.0, baseline_correction=False, zscore=False # as apply_baseline, per unit
)
# → pd.DataFrame — one row per unit and bin: unit_id, time, line, low, high (band over the events), n_events
spikes_around_events(spikes: np.ndarray, event_times: np.ndarray, t_before: float, t_after: float)
# → list[np.ndarray] — one unit's spikes in [t - t_before, t + t_after) of each event, relative to it (rasters)
Signal Processing¶
Module: cicada_analysis.cicada_tools.imaging.calcium_signal_processing
from cicada_analysis.cicada_tools.imaging.calcium_signal_processing import (
norm01,
median_normalization,
zscore_normalization,
bleaching_correction,
savitzky_golay_filt,
gauss_blur_1d,
gauss_blur,
detect_small_transients,
give_unique_id_to_each_transient_of_raster_dur,
transient_amplitudes,
)
norm01(data)
# → np.ndarray global min-max normalization to [0, 1]
median_normalization(traces: np.ndarray) # (n_cells, n_frames)
# → np.ndarray (n_cells, n_frames) divide each cell by its median
zscore_normalization(traces: np.ndarray) # (n_cells, n_frames)
# → np.ndarray (n_cells, n_frames) z-score each cell (subtract mean, divide by std)
transient_amplitudes(raster, traces, peak_minus_onset=True, max_negative_fraction=0.05)
# → (cells, onsets, amplitudes): one entry per transient (run of 1s of raster) measured on traces;
# peak_minus_onset: trace at the last two frames minus at the frame before and the onset (transients at frame 0
# left out), else the trace maximum over the transient; negative amplitudes NaN, warning above the fraction
bleaching_correction(traces: np.ndarray) # (n_cells, n_frames)
# → np.ndarray (n_cells, n_frames) polynomial detrend per cell
savitzky_golay_filt(traces: np.ndarray, sr: float)
# → np.ndarray (n_cells, n_frames)
gauss_blur_1d(data, dw, dim)
# → np.ndarray Gaussian blur along one dimension (Fourier domain)
gauss_blur(data, dw)
# → np.ndarray isotropic 2D Gaussian blur (Fourier domain)
detect_small_transients(
traces: np.ndarray, # (n_cells, n_frames)
speed=None,
use_speed: bool = False,
speed_threshold=None,
detection_method: str = 'rolling-window',
window_size=None,
min_small_transient_amp: float = 0,
imaging_rate: float = 10,
frames_mask=None # bool per frame: where transients may be detected (e.g. an epoch); None: all
)
# → tuple (raster: np.ndarray (n_cells, n_frames), activity: list per cell of trace snippets)
# Detects small calcium transients per cell.
give_unique_id_to_each_transient_of_raster_dur(raster_dur: np.ndarray)
# → np.ndarray (n_cells, n_frames) — each transient gets a unique integer ID
Population Burst / SCE Detection¶
Module: cicada_analysis.cicada_tools.imaging.detect_population_burst
from cicada_analysis.cicada_tools.imaging.detect_population_burst import (
get_sce_raster_threshold,
detect_sce_raster,
detect_sce_traces,
)
get_sce_raster_threshold(
rasterdur: np.ndarray, # (n_cells, n_times) binary raster
n_surrogates: int = 100,
percentile: int = 95,
verbose: bool = False,
n_jobs: int = 4,
seed=0 # int or np.random.Generator: same seed, same threshold (whatever n_jobs)
)
# → tuple (rnd_rasters: np.ndarray, cell_threshold: int)
# rnd_rasters: surrogate population activity distributions
# cell_threshold: minimum co-active cells to call an SCE
detect_sce_raster(
raster: np.ndarray, # (n_cells, n_times) raster, active where > 0 (already computed)
n_synchronous_frames: int, # window of co-activity, in frames
sce_n_cells_threshold: int, # min co-active cells (from get_sce_raster_threshold)
sce_min_distance: int, # min frames between SCE peaks ("Peaks")
method: str = "Peaks", # "Peaks": one SCE per peak; "All frames": each run of windows above threshold
frames_mask=None, # bool per frame: where SCEs may start (epoch, immobility); frames stay the raster's
participation_margin: int = 1 # "Peaks": cell in the SCE if active within ± this many frames of the peak
)
# → tuple (cells_in_sce: np.ndarray (n_cells, n_sce), sce_windows: [(start, end), ...] inclusive, threshold)
# Lower-level: use when raster is already available.
detect_sce_traces(
raw_traces: np.ndarray, # (n_cells, n_times)
speed=None,
use_speed: bool = False,
speed_threshold=None,
sce_n_cells_threshold: int = 5,
transient_method: str = 'rolling-window',
window_size: int = 4,
sce_min_distance: int = 4,
n_synchronous_frames: int = 2,
small_transient_amp: float = 0,
imaging_sampling_rate: float = 10,
use_median_norm: bool = True,
use_bleaching_correction: bool = False,
use_savitzky_golay_filt: bool = False,
frames_mask=None # bool per frame: where transients and SCEs may be (e.g. an epoch)
)
# → tuple (sce_cells_matrix, sce_loc (1-D peak frames), raster, small_transients_activity)
# Full pipeline: raw traces → transient detection → SCE detection.
# Use when you do not have a raster yet (calls detect_small_transients internally).
Calcium Imaging — Display¶
Module: cicada_analysis.cicada_tools.imaging.imaging_plots
from cicada_analysis.cicada_tools.imaging.imaging_plots import (
render_traces,
render_traces_heatmap,
plot_small_transients,
)
render_traces(
ax, # matplotlib Axes
traces: np.ndarray, # (n_cells, n_times)
frame_times: np.ndarray, # (n_times,)
traces_lw: float = 0.3,
cell_spikes_color: str = 'white',
use_brewer_colors_for_traces: bool = False,
cells_to_highlight=None, # list of cell indices
cells_to_highlight_colors=None,
scatters_on_traces=None,
show_y_scale: bool = False,
show_x_scale: bool = False,
figure_background_color: str = 'black',
... # additional style kwargs
)
# → float — returns the y-axis offset used (useful when composing multi-panel figures)
render_traces_heatmap(
raster: np.ndarray, # (n_cells, n_times) — 2D array to render as heatmap
path_results=None,
file_name=None,
n_subplots: int = 4,
axes_list=None,
speed_array=None,
fig=None,
show_color_bar: bool = False,
vmin: float = 0.5,
vmax=None,
cmap: str = "hot",
save_formats: str = "pdf",
background_color: str = "black",
first_frame: int = 0, # recording frame of raster's first column (x tick labels of a time slice)
... # extensive style kwargs
)
# → None
plot_small_transients(
small_transients, # transient data from detect_small_transients
window_size,
sampling_rate,
title,
path_results,
filename,
save_formats
)
# → None
Tiff Movie Handling¶
Module: cicada_analysis.cicada_tools.imaging.images_handling
from cicada_analysis.cicada_tools.imaging.images_handling import (
TiffMovieView,
as_sliceable_movie,
load_tiff_movie,
read_tiff_movie_frames,
get_avg_frames_by_epoch,
reduce_image_dimensions,
map_coordinates_to_image,
)
# TiffMovieView — off-memory sliceable view; valid as long as paths exist
# memory-mapped when possible (frames back to back, or at a constant distance as in raw ScanImage tiffs)
tiff_view = TiffMovieView(paths) # paths: str or list of str
frames = tiff_view[0:100] # → np.ndarray (100, H, W)
as_sliceable_movie(session_ci_movie_data)
# → TiffMovieView | np.ndarray — normalizes session movie data to (n_frames, H, W) sliceable
# Use on the dict returned by session.calcium_imaging.get_ci_movies()
load_tiff_movie(tiff_file_name, first_frame=None, last_frame=None)
# → np.ndarray (n_frames, H, W) — loads into memory; use TiffMovieView for large files
read_tiff_movie_frames(tiff_filename)
# → int — number of frames without loading the movie
get_avg_frames_by_epoch(
data_3d: np.ndarray, # (n_frames, H, W)
epoch_frames: list, # list of (start_frame, stop_frame) tuples
subtract_baseline: bool = False,
baseline_end_frame: int | None = None # frame index marking end of baseline within epoch
)
# → tuple (avg_data: np.ndarray, center_frame: int, n_frames_post: int)
reduce_image_dimensions(image: np.ndarray, factor: float = 2.0, anti_aliasing: bool = True)
# → np.ndarray — spatially downsampled
map_coordinates_to_image(image_values: np.ndarray, coords: list)
# → pd.DataFrame — per-ROI values mapped to pixel coordinates
Period Utilities¶
Module: cicada_analysis.cicada_tools.core.period_utils
from cicada_analysis.cicada_tools.core.period_utils import (
get_continous_time_periods,
from_timestamps_to_frame_epochs,
from_timestamps_array_to_list,
get_complementary_frames,
fill_gaps_in_continuous_periods,
extend_invalid_times,
filter_epoch_timestamps,
filter_events_based_on_epochs,
get_epoch_frames,
)
get_continous_time_periods(binary_array: np.ndarray)
# → list[tuple[int, int]] — (start_frame, stop_frame inclusive) for each run of 1s
from_timestamps_to_frame_epochs(
time_stamps_array: np.ndarray, # (2, N) epoch array in seconds (NWB output)
frames_timestamps: np.ndarray, # (n_times,) trace timestamps in seconds
as_list: bool = False
)
# → list[tuple[int, int]] if as_list else np.ndarray (2, N) of frame indices
from_timestamps_array_to_list(
time_stamps_array: np.ndarray, # (2, N)
frames_timestamps: np.ndarray # (n_times,)
)
# → list[tuple[float, float]] — epochs clipped to recording range
get_complementary_frames(
total_frames: int,
active_periods: list[tuple[int, int]] # list of (start, stop) frame pairs
)
# → tuple (bool_array: np.ndarray, int_array: np.ndarray)
# Returns the complement — i.e. frames NOT in any active period.
fill_gaps_in_continuous_periods(
boolean_serie: np.ndarray, # 1D binary
max_gap_size: int # fill gaps shorter than this (frames)
)
# → np.ndarray (bool)
extend_invalid_times(
invalid_times: np.ndarray, # (2, N)
padding: float | tuple[float, float] # seconds; scalar=symmetric, tuple=(before, after)
)
# → np.ndarray (2, N)
filter_epoch_timestamps(
epochs_timestamps: np.ndarray, # (2, N) to filter
extended_invalid_times: np.ndarray | None, # (2, M) regions to exclude
epochs_are_sorted: bool,
invalid_times_are_sorted: bool,
filter_consecutive: bool = False,
use_main_epoch: bool = False,
main_epoch_timestamps: np.ndarray | None = None,
main_epoch_name: str = "",
baseline_length: float = 0.0,
verbose: bool = False,
epoch_name: str = ""
)
# → np.ndarray (2, K) — filtered epochs (K ≤ N)
filter_events_based_on_epochs(
events_ts: np.ndarray, # (N,) event timestamps in seconds
epochs: np.ndarray # (2, M) epoch windows
)
# → np.ndarray — events that fall inside at least one epoch window
get_epoch_frames(
epoch_times: np.ndarray, # (2, n_epochs) start / stop times
reference_ts: np.ndarray, # timestamps of the frames
max_idx: int # frames above it are left out
)
# → np.ndarray — per epoch, the frames from the one nearest its start to the one nearest its stop (excluded)
Array Utilities¶
Module: cicada_analysis.cicada_tools.core.array_utils
from cicada_analysis.cicada_tools.core.array_utils import (
find_nearest,
validate_indices_in_string_format,
extract_indices_from_string,
flatten,
)
find_nearest(array: np.ndarray, value: float, is_sorted: bool = True)
# → int — index of element closest to value
validate_indices_in_string_format(str_indices: str) # e.g. "1-3 25 6"
# → bool
extract_indices_from_string(str_indices: str)
# → list[int]
flatten(lst)
# → list — recursively flattens nested iterables
Table Utilities¶
Module: cicada_analysis.cicada_tools.core.table_utils
Saving the data of results and figures as the core plugins do (tables as .csv, sampled series as .npy), and selecting rows and time columns of trial / epoch tables. Also importable from cicada_analysis.cicada_tools.core.
from cicada_analysis.cicada_tools.core.table_utils import (
save_tables,
save_samples,
flat_columns,
ragged_to_arrays,
intervals_table,
filter_table_with_dict,
table_time_columns,
table_column_times,
)
save_tables(tables: dict[str, pd.DataFrame], folder: str) # {file name without extension: table}; None skipped
# → list[str] — paths of the <folder>/<name>.csv written (no index); folder created if missing
save_samples(
name: str, # common start of the file names, e.g. '<session>_raster'
folder: str,
rows: pd.DataFrame | None = None, # one row per row of the arrays, in their order
**arrays # arrays by key (data=, times=, ...); None skipped
)
# → list[str] — paths written: <name>_<key>.npy per array, <name>_rows.csv for rows
flat_columns(table: pd.DataFrame)
# → pd.DataFrame — grouped table (e.g. groupby(...).agg([...])) as plain columns: index reset, multi-level
# column names joined with '_' (('tau', 'mean') -> 'tau_mean'); a new table
ragged_to_arrays(trains: list[array-like]) # one array per row, e.g. the spike times of each unit
# → tuple (rows: np.ndarray, values: np.ndarray) — row index of each value, and the values; for save_samples
intervals_table(
intervals_by_group: list[list[tuple]], # per group, its (start, stop) intervals
names: list[str] # name of each group
)
# → pd.DataFrame — columns group, start, stop; one row per interval
filter_table_with_dict(table: pd.DataFrame, filtering_dict: dict) # {column: [allowed values]}
# → pd.DataFrame — rows whose value in each column is allowed (any of them for a column with several
# values per row, e.g. tags); filtering_dict is not modified
table_time_columns(table: pd.DataFrame)
# → list — columns holding times (name containing 'time', numbers, one or several per row), 'start_time'
# first: what a PSTH can be aligned on. Align with align_array_to_timestamps(..., table_column_times(table, col), ...)
table_column_times(table: pd.DataFrame, column: str) # a column of table_time_columns
# → np.ndarray (n_rows,) — one time per row: the first value for a row holding several (e.g. Allen
# 'lick_times'), NaN for a row without a time
Display — Figure¶
Module: cicada_analysis.cicada_tools.display.core_plots
Always use save_figure instead of plt.savefig — it handles PDF font embedding, tight layout, safe file
names, and the interactive figure files (.mplfig) shown in the GUI's Interactive viewing tab when the run's "Interactive viewing
of the figures" is ticked.
from cicada_analysis.cicada_tools.display.core_plots import (
save_figure,
style_axes,
FIGURE_STYLE,
split_into_separate_figures,
create_and_configure_plot,
get_colormap,
is_light_color,
add_scale_bar,
)
save_figure(
figure, # matplotlib Figure
results_path: str, # directory
figname: str, # filename without extension
save_formats: tuple | list = ('pdf', 'png'),
dpi: int | str = 300, # or 'figure': the figure's own
tight_layout: bool = True,
close: bool = True,
bbox_inches: str | None = None
)
# → None — saves to results_path/figname.{ext} for each format (+ figname.mplfig with interactive figures on);
# closes this figure by default
style_axes(ax, v_line=False, xlim=None, ylim=None, xlabel=None, ylabel=None, despine=False, **style)
# → None — sets the limits / labels given (None: unchanged), despine: removes top and right borders, then
# applies only the FIGURE_STYLE keys given (background of axes + figure, tick / label sizes and colours,
# borders); v_line: dashed line at 0
split_into_separate_figures(data: pd.DataFrame, columns: list, file_name: str)
# → [(rows of the figure, file name)] — one figure per combination of the values of `columns`
create_and_configure_plot(n_lines, n_cols, size_fig, background_color)
# → tuple (fig, axes)
get_colormap(cmap: str = 'hotcold')
# → matplotlib.colors.Colormap
# Built-in custom colormaps: 'hotcold', 'cyanmagenta', 'whitemagenta'
is_light_color(color)
# → bool — True if perceptual brightness > 0.5
add_scale_bar(ax, length, label, color, fontproperties=None, axis="x", shown=None, loc=2, anchor=(0., 1.),
label_top=True, zorder=None)
# → AnchoredSizeBar | None — `length` data units along 'x' (time) or 'y' (signal), thickness a fixed fraction of
# the axes; None (not drawn, with a message) when longer than `shown` (time window / signal range shown)
Display — Raster¶
Module: cicada_analysis.cicada_tools.display.raster_plots
from cicada_analysis.cicada_tools.display.raster_plots import plot_raster
plot_raster(
spike_nums=None, # (n_cells, n_times) binary raster
title=None,
file_name=None, # without extension
frame_times=None, # (n_times,) timestamps for x-axis
times_format: str = "sec", # 'sec' | 'ms'
spike_train_format: bool = False,
figure_background_color: str = "black",
raster_face_color: str = 'black',
cell_spikes_color: str = 'white',
spike_shape: str = "|",
spike_shape_size: int = 10,
save_raster: bool = False,
save_formats: str = "png",
path_results: str = None, # required if save_raster=True
span_area_coords=None, # list of (start, stop) frame pairs to shade
span_area_colors=None,
span_area_only_on_raster: bool = True,
alpha_span_area: float = 0.5,
span_line_width=None, # pt, lines of spans without duration (start = stop); None: matplotlib's
without_activity_sum: bool = False,
mouse_speed=None,
behavioral_ts_list=None,
axes_list=None, # pre-created axes to embed in a larger figure
size_fig=None,
traces=None,
display_traces: bool = False,
display_spike_nums: bool = True,
traces_lw: float = 0.3,
dpi: int = 100,
... # many additional style kwargs
)
# → None
Display — Distributions¶
Module: cicada_analysis.cicada_tools.display.distribution_plots
from cicada_analysis.cicada_tools.display.distribution_plots import (
plot_box_plots,
plot_hist_distribution,
categorical_plot,
plot_groups,
)
plot_box_plots(
data_dict: dict, # {group_label: array or list of values}
title: str,
filename: str, # without extension
y_label: str,
scatter_text_dict=None,
colors=None,
path_results: str = None,
y_lim=None,
x_label=None,
with_scatters: bool = True,
scatter_size: int = 20,
scatter_alpha: float = 0.5,
background_color: str = "black",
labels_color: str = "white",
link_medians: bool = False,
save_formats: str = "pdf",
with_timestamp_in_file_name: bool = False,
...
)
# → None
plot_hist_distribution(
distribution_data, # array or list of values
filename=None,
values_to_scatter=None,
n_bins=None,
use_log: bool = False,
x_range=None,
labels=None,
background_color: str = "black",
path_results=None,
save_formats: str = "pdf",
ax_to_use=None,
density: bool = False,
...
)
# → None
categorical_plot(
kind: str, # 'strip', 'swarm', 'violin', 'box', 'bar' or 'boxen'
ax, # existing axes (sns.catplot ignores ax: use this instead)
**kwargs, # seaborn arguments: data=, x=, y=, hue=, order=, palette=...
)
# → ax (strip jitter / bar bootstrap seeded: same figure at every run)
plot_groups(
table: pd.DataFrame, # one row per observation (e.g. cell) with the group columns
value: str, y_label: str, # column plotted, its axis label
path: str, file_name: str, # figures suffixed with their groups
x=None, hue=None, # group columns on the x axis / in colour
separate=(), # group columns drawn in separate figures
levels=(), # also one figure per value of these columns, e.g. ('session', 'mouse')
palette=None, # {group: colour} of the hue groups, else of the x groups
representation="box", x_label="", legend_title=None, style=None, # style: style_axes keys
figsize=(10, 8), save_formats="pdf", dpi=100, save=True,
do_stats=False, pvalue=0.05, # compare the x groups within each hue group (stats.compare_groups, printed)
skip_label="all", # group name left out of the titles
)
# → None
Display — PSTH Plots¶
Module: cicada_analysis.cicada_tools.display.psth_plots
from cicada_analysis.cicada_tools.display.psth_plots import (
plot_psth_lines,
plot_raster_and_psth,
common_y_limits,
psth_legend_counts,
)
# split_into_separate_figures, style_axes, FIGURE_STYLE: display.core_plots (any figure)
plot_psth_lines(
summary: pd.DataFrame, # line_and_band table: x, 'line', 'low', 'high' + the row / col / hue / style columns
x='time', row=None, col=None, hue=None, style=None,
palette=None, # {hue level: color}; others from the matplotlib cycle
x_label="Time (s)", y_label="", title="",
labels=None, # {hue level: legend text}
y_lim=None, # (bottom, top) of every panel
width_fig=15, height_fig=8, dpi=300, xkcd_mode=False,
save_path=None, save_formats="pdf", file_name="psth",
share_y="row", # as matplotlib's sharey; False when the panels show different quantities
**figure_style # keys of FIGURE_STYLE (text sizes, ticks, colours, line at 0)
)
# panels (row x col) sharing a width_fig x height_fig figure, one line + band per hue level (colour) and style level
# (line style), legend outside. Lines and bands of each level: stats.line_and_band, then stats.reduce_psth_level
plot_raster_and_psth(
rasters, # [(hue level, style level, [spike times relative to each event])]
summary: pd.DataFrame, # the unit's lines and bands, as for plot_psth_lines
x='time', hue=None, style=None, palette=None, x_label="Time (s)", y_label="", title="", labels=None,
width_fig=15, height_fig=8, dpi=300, xkcd_mode=False, save_path=None, save_formats="pdf", file_name="unit",
**figure_style
)
# width_fig x height_fig figure: raster (one row per event, coloured like its line) above the PSTH
common_y_limits(tables: list[pd.DataFrame])
# → (bottom, top) covering 'line', 'low', 'high' of every table (figures sharing one y scale)
psth_legend_counts(session_rows, figure_rows, hue, separate, group_columns=("cell_group",), count_column="n_cells",
count_name="cells")
# → {hue level: "group\nN=mice, n=sessions\ncells, events"} for plot_psth_lines' labels
Display — Graphs¶
Module: cicada_analysis.cicada_tools.display.graph_plots
from cicada_analysis.cicada_tools.display.graph_plots import (
plot_graph,
plot_connectivity_graphs,
)
plot_graph(
graph, # nx.Graph or nx.DiGraph
with_fa2: bool = False, # use ForceAtlas2 layout (requires fa2 package)
randomized_positions: bool = False,
filename=None,
iterations: int = 2000,
node_color=None,
edge_color=None,
background_color=None,
cmap=None,
node_size: int = 10,
with_labels: bool = False,
title=None,
ax_to_use=None,
figure_size: tuple = (5, 5),
dpi: int = 300,
save_formats=None,
save_fig: bool = False,
path_results=None,
with_timestamp_in_file_name: bool = False
)
# → None
plot_connectivity_graphs(
session_id_list, # list of session IDs
filename_list=None,
graph_files_path=None, # path to saved graph files
background_color=None,
node_color=None,
edge_color=None,
size_fig=None,
dpi: int = 300,
save_formats=None,
save_fig: bool = False,
path_results=None,
with_timestamp_in_file_name: bool = False
)
# → None — grid of graphs, one per session
Display — Connectivity¶
Module: cicada_analysis.cicada_tools.display.connectivity_plots
Figures of the connectivity analyses; the computations they plot are in cicada_analysis.cicada_tools.connectivity (sections below). Not re-exported by cicada_tools.display: import from the module.
from cicada_analysis.cicada_tools.display.connectivity_plots import (
plot_christmas_tree_heatmap,
plot_christmas_tree_crosscorr,
plot_stpr_scatter,
plot_stpr_heatmap,
plot_stpr_heatmap_grid,
plot_pair_ccg,
plot_similarity_matrix,
)
# Peri-SCE triggered average ("Christmas tree"), from compute_triggered_average_raster
plot_christmas_tree_heatmap(mean_psth, time_axis_s, time_lags_dict, cells_list,
data_id: str, path_results: str, save_formats: str = "pdf")
# → None — heatmap of triggered averages, rows sorted/normalized by each unit's preferred time lag
plot_christmas_tree_crosscorr(mean_psth, time_axis_s, time_lags_dict, cells_list,
data_id: str, path_results: str,
cells_groups=None, groups_colors=None, ...)
# → None — per-cell (or per-group mean ± SEM) traces around SCE onset
# Spike-triggered population rate (stPR), from compute_stpr / compute_stpr_cross
# Scatter: coupling strength vs. delay (stPR analogue of the "Christmas tree" scatter above)
plot_stpr_scatter(coupling, delay_s, valid, data_id: str, path_results: str,
cells_groups=None, groups_colors=None, save_formats: str = "pdf", ...)
# → None
# Heatmap: z-scored stPR curves sorted by delay
plot_stpr_heatmap(time_axis_s, stpr, delay_s, valid, coupling, data_id: str, path_results: str,
save_formats: str = "pdf", ...)
# → None
# Grid of heatmaps (one per group / cross-area pair), shared colorbar
plot_stpr_heatmap_grid(
entries: list, # list of (label, stpr, time_axis_s, delay_s, valid) tuples
data_id: str, path_results: str, max_cols: int = 4, save_formats: str = "pdf", ...
)
# → None
# Plot CCG for a single pair (works for both ephys and imaging)
plot_pair_ccg(
ia: int, ib: int, # unit/cell indices
spike_times_list: list, # list of 1D arrays (seconds)
bin_size_ms: float = 0.4,
max_lag_ms: float = 100.0,
hollow_ms: float = 10.0, sigma_ms: float = 20.0,
syn_window: tuple = (1.0, 4.0),
node_label: str = "unit", # 'unit' for ephys; 'cell' for imaging
show_significance: bool = True # False for imaging (different detection criterion)
)
# → matplotlib.Figure
# Pairwise similarity — plot a matrix from compute_similarity_matrix; single matrix or dict of matrices {label: matrix}
plot_similarity_matrix(
data: np.ndarray | dict, # (n_cells, n_cells) or {name: (n_cells, n_cells)}
filename: str | None = None,
background_color: str | None = None,
plt_title: str = ' ',
colormap: str | None = None,
size_fig: tuple = (10, 8),
save_fig: bool = True,
path_results: str | None = None,
save_formats: tuple = ('pdf', 'png')
)
# → None — seaborn heatmap; vmin=0 vmax=1; dict input produces a multi-panel grid
Pairwise Cell Similarity¶
Module: cicada_analysis.cicada_tools.connectivity.pairwise_cell_similarity
Use for any correlation or similarity matrix between neurons. Covers Pearson, Hamming, Jaccard, and Cosine — do not reimplement these with numpy/scipy.
from cicada_analysis.cicada_tools.connectivity.pairwise_cell_similarity import (
compute_similarity_matrix,
build_pearson_adjacency_matrix,
get_pairwise_hamming_similarity,
get_pairwise_jaccard_similarity,
get_pairwise_cosine_similarity,
)
# Main entry point — unified interface for all methods
compute_similarity_matrix(
neuronal_data: np.ndarray, # (n_cells, n_times)
correlation_axis: int = 0, # 0 = cells×cells; 1 = times×times (transposes input)
method: str = None, # 'Pearson' | 'Hamming' | 'Jaccard' | 'Cosine'
verbose: bool = False
)
# → np.ndarray (n_cells, n_cells) symmetric similarity matrix
# Pearson with optional significance thresholding (and optional .npy save)
build_pearson_adjacency_matrix(
neuronal_data: np.ndarray, # (n_cells, n_times)
with_thresholds: bool = True, # False = fast np.corrcoef; True = loop with p-value filter
correlation_threshold: float = 0.1, # entries below this are zeroed
p_value_threshold: float = 0.05, # entries with p > this are zeroed
verbose: bool = False,
data_id: str = "",
results_path: str | None = None # if set, saves matrix as pearson_adjacency_matrix_{data_id}.npy
)
# → np.ndarray (n_cells, n_cells) — diagonal = 1; off-diagonal = rho or 0
# Binary raster measures (input must be 0/1)
get_pairwise_hamming_similarity(neuronal_data: np.ndarray) # (n_cells, n_times) → (n_cells, n_cells)
get_pairwise_jaccard_similarity(neuronal_data: np.ndarray) # (n_cells, n_times) → (n_cells, n_cells)
get_pairwise_cosine_similarity(neuronal_data: np.ndarray) # (n_cells, n_times) → (n_cells, n_cells)
Cross-Correlogram (CCG) Utilities¶
Module: cicada_analysis.cicada_tools.connectivity.connectivity_utils
Ephys monosynaptic connection detection (the time-correlation graph of calcium imaging moved to cicada-cossart).
from cicada_analysis.cicada_tools.connectivity.connectivity_utils import (
bz_detect_connections,
hollow_gaussian_baseline,
ccg_peak_significance,
)
# Ephys: detect putative monosynaptic connections via CCG (English et al. 2017, Neuron)
bz_detect_connections(
spike_times_list: list, # list of 1D arrays, spike times in seconds
unit_ids: list, # unit indices to test (subset of range(len(spike_times_list)))
min_spikes: int = 200, # skip units with fewer spikes
bin_size_ms: float = 0.4,
max_lag_ms: float = 100.0,
hollow_ms: float = 10.0, # hollow window in Gaussian baseline (ms)
sigma_ms: float = 20.0,
syn_window: tuple = (1.0, 4.0) # (lo_ms, hi_ms) synaptic window to test
)
# → pd.DataFrame columns: unit_pre, unit_post, connection_type ('excitatory'|'inhibitory'),
# peak_latency_ms, transmission_probability, peak_bin_pvalue, n_significant_bins
# Returns empty DataFrame if no connections found.
# Lower-level helpers used internally by bz_detect_connections
hollow_gaussian_baseline(counts: np.ndarray, bin_size_ms: float, hollow_ms: float = 10.0, sigma_ms: float = 20.0)
# → np.ndarray — Gaussian-smoothed CCG baseline with a hollow window zeroed around lag 0
ccg_peak_significance(counts: np.ndarray, baseline: np.ndarray, lag_centers: np.ndarray, syn_window: tuple = (1.0, 4.0))
# → dict — {'excitatory': {...}, 'inhibitory': {...}}, each with significant/n_sig/peak_lat/peak_pval/mask/reject
Spike-Triggered Population Rate (stPR)¶
Module: cicada_analysis.cicada_tools.connectivity.connectivity_utils
Leader/follower analysis (Bimbard et al. 2026 style): for each unit/cell, cross-correlates its own activity with the mean-subtracted population rate (excluding itself). Coupling strength = value at lag 0; delay = centre of mass of the (low-passed) curve. Works for both ephys spike times and calcium-imaging rasters.
from cicada_analysis.cicada_tools.connectivity.connectivity_utils import (
compute_stpr,
compute_stpr_cross,
)
# Within-population stPR — one unit's spikes vs. the rest of the population's mean rate
compute_stpr(
spike_times_list: list = None, # list of 1D arrays (seconds); OR pass spike_mat directly
bin_size_s: float = 0.001,
window_s: float = 0.08, # half-window for the cross-correlation
lp_cutoff_hz: float = 20.0,
spike_mat: np.ndarray = None # (n_units, n_bins) binary — alternative to spike_times_list
)
# → (stpr, time_axis, coupling, delay_s, valid)
# stpr: (n_units, n_lags); coupling/delay_s/valid: (n_units,)
# Cross-area stPR — source units' spikes vs. a disjoint target population's rate (no self-exclusion)
compute_stpr_cross(
source_spike_times: list, target_spike_times: list,
bin_size_s: float = 0.001, window_s: float = 0.08, lp_cutoff_hz: float = 20.0
)
# → (stpr, time_axis, coupling, delay_s, valid) — same shapes as compute_stpr
Peri-SCE Triggered Average ("Christmas Tree")¶
Module: cicada_analysis.cicada_tools.connectivity.connectivity_utils
Calcium-imaging counterpart to the time-correlation graph, built around detected SCEs (Synchronous Calcium Events) rather than arbitrary events.
from cicada_analysis.cicada_tools.connectivity.connectivity_utils import (
compute_triggered_average_raster,
estimated_autocorrelation,
)
compute_triggered_average_raster(raster: np.ndarray, sce_centers: list, window_frames: int)
# → (mean_response, time_frames) — peri-SCE triggered average of a binary raster
estimated_autocorrelation(x: np.ndarray)
# → np.ndarray — normalized autocorrelation estimate of a 1-D signal
Graphs & Connectivity¶
Module: cicada_analysis.cicada_tools.graphs.graph_building
Module: cicada_analysis.cicada_tools.graphs.graph_analysis
from cicada_analysis.cicada_tools.graphs.graph_building import (
build_connectivity_graphs,
build_graph_from_adjacency_matrix,
build_graph_from_transition_dict,
)
from cicada_analysis.cicada_tools.graphs.graph_analysis import (
detect_hub_cells,
find_paths_in_a_graph,
welsh_powell,
)
build_connectivity_graphs(
spike_data, # (n_cells, n_times) binary raster or spike times
sampling_rate: float, # Hz
time_delay: float = 500, # ms — lag window for spike-triggered histogram
save_graphs: bool = False,
path_results=None,
filename=None,
verbose=None
)
# → nx.DiGraph — directed graph with edge weights from cross-correlation
build_graph_from_adjacency_matrix(
adjacency_matrix: np.ndarray,
weight_on_edges: bool = True,
directed_graph: bool = True,
symmetric_matrix: bool = False,
save_graphs: bool = False,
path_results=None,
filename=None
)
# → nx.Graph | nx.DiGraph
build_graph_from_transition_dict(
transition_dict,
n_connected_cell_to_add,
use_longest_path: bool = False,
with_weight: bool = True,
cells_to_isolate=None,
transition_dict_2_nd_order=None,
spikes_dist_dict=None,
min_rep_nb=None
)
# → nx.DiGraph
detect_hub_cells(
graphs_to_analyse: dict, # {session_id: nx.DiGraph}
cell_connectivity_threshold: int = 5,
top_connected_cells: int = 20,
verbose: bool = True
)
# → dict {session_id: array_of_hub_cell_indices}
find_paths_in_a_graph(
graph,
shortest_path_on_weight,
with_weight,
use_longest_path: bool = False,
debug_mode: bool = False
)
# → tuple (seq_list, isolates_cell)
welsh_powell(graph)
# → dict — {node: color_int} graph coloring
Ephys Signal Processing¶
Module: cicada_analysis.cicada_tools.ephys.ephys_signal_processing
from cicada_analysis.cicada_tools.ephys.ephys_signal_processing import (
bin_raster,
replace_artifact_spikes,
render_spike_activity_sum,
smooth_causal_half_gaussian,
)
bin_raster(raster: np.ndarray, bin_size: int, keep_same_dimension: bool = True)
# → np.ndarray — binned spike raster (same shape if keep_same_dimension=True)
replace_artifact_spikes(
spike_times: list[np.ndarray], # one array per unit
event_times: np.ndarray, # (N,) event times in seconds
artifact_window: tuple[float, float] = (-0.01, 0.005), # window relative to event to blank
baseline_window: tuple[float, float] = (-0.5, -0.01), # window to sample replacement spikes from
seed=None
)
# → list[np.ndarray] — spike_times with artifact spikes replaced by Poisson surrogates
render_spike_activity_sum(
ax, # matplotlib Axes
spike_nums_for_activity_sum, # (n_cells, n_times)
frame_times,
n_cells,
n_times,
min_time: float = 0,
max_time: float = 0,
show_sum_spikes_as_percentage: bool = False,
activity_threshold=None,
SCE_times=None,
color_peaks_activity: bool = False,
activity_sum_plot_color: str = 'white',
activity_sum_face_color: str = 'black',
bin_size_ms_for_spikes_sum: int = 100,
spike_train_format: bool = False,
...
)
# → None — renders population spike count panel on an axes object
smooth_causal_half_gaussian(
x: np.ndarray, # any array
sigma: float, # smoothing width in seconds
dt: float, # bin size in seconds
axis: int = 1
)
# → np.ndarray same shape as x
Ephys Display¶
Module: cicada_analysis.cicada_tools.ephys.ephys_plots
from cicada_analysis.cicada_tools.ephys.ephys_plots import render_spikes
render_spikes(
ax, # matplotlib Axes
spike_nums: np.ndarray, # (n_cells, n_times) binary raster
frame_times=None,
spike_train_format: bool = False,
spike_shape: str = '|',
spike_shape_size: int = 10,
cell_spikes_color: str = 'white',
plot_with_amplitude: bool = False,
cells_to_highlight=None,
cells_to_highlight_colors=None,
horizontal_lines=None,
display_traces: bool = False,
traces=None,
n_cells=None,
debug_mode: bool = False,
...
)
# → dict — rendering metadata (e.g. scalar_map if amplitude-colored)
Behavior Analysis¶
Module: cicada_analysis.cicada_tools.behavior.behavior_analysis_utils
DLC trace preprocessing and behavior PSTH tables (trial / epoch table helpers: see Table Utilities; the Petersen lab task utilities moved to cicada-petersen).
from cicada_analysis.cicada_tools.behavior.behavior_analysis_utils import (
build_dlc_psth_df,
preprocess_dlc_trace,
preprocess_dlc_series,
remove_outliers_zscore,
interpolate_nans,
)
build_dlc_psth_df(
signals: dict, # {name: (values (n_frames,) or (n_frames, n_columns), timestamps in s)}
trial_timestamps, # times to align on (s)
psth_start_in_sec: float,
psth_stop_in_sec: float,
subtract_baseline: bool = True
)
# → pd.DataFrame — one row per series column and event: 'behavior_movie_data_event' (aligned values), 'bodypart';
# events whose window leaves the recording are dropped; the caller adds its own columns
preprocess_dlc_trace(trace: np.ndarray)
# → np.ndarray — remove_outliers_zscore (threshold 20) → interpolate_nans (no smoothing)
preprocess_dlc_series(values: np.ndarray)
# → np.ndarray (n_frames, n_columns) — preprocess_dlc_trace on each column
remove_outliers_zscore(trace: np.ndarray, threshold: float = 10)
# → np.ndarray — outliers replaced with NaN
interpolate_nans(trace: np.ndarray)
# → np.ndarray — linear interpolation of NaN segments
Clustering¶
Module: cicada_analysis.cicada_tools.clustering
K-means clustering: best of several KMeans runs by silhouette score, and the silhouette plot. Used internally by cell-assembly detection, but usable standalone.
from cicada_analysis.cicada_tools.clustering import (
find_best_kmeans,
plot_silhouettes,
)
find_best_kmeans(
data: np.ndarray, # (n_samples, n_features)
n_cluster: int,
n_tests: int = 100, # number of KMeans re-runs
scoring_fn=np.median, # per-cluster silhouette reduction; use np.mean for Malvache-paper behavior
seed=0 # int or np.random.Generator: same seed, same fit
)
# → (KMeans, float) — best-scoring fitted estimator and its silhouette score
plot_silhouettes(ax, kmeans, data: np.ndarray, n_clusters: int, surrogate_threshold: float = None)
# → None — per-cluster silhouette bar chart; clusters above surrogate_threshold get a white outline
Sequences Detection¶
Module: cicada_analysis.cicada_tools.sequences
PCA-based sequence detection (Malvache), used by the cicada_seq_malvache_analysis plugin. Not re-exported
at package level — import directly from the submodule (the graph-based sequences of Villette et al. 2015
moved to cicada-cossart).
from cicada_analysis.cicada_tools.sequences.malvache.utils_malvache_sequences import (
step1_pca_off_memory,
convert_position_to_distance,
)
step1_pca_off_memory(data: np.ndarray, n_pc_max: int)
# → (data_centralized, pc_time_course) — PCA on the lag-1 temporal covariance matrix, matrix-free (ARPACK):
# the n_times × n_times matrix is never formed
convert_position_to_distance(positions: np.ndarray, loop_length: float)
# → (total_traveled_distance: list, n_laps: int) — circular-track position → cumulative distance
Cell Assemblies¶
Module: cicada_analysis.cicada_tools.cell_assemblies.malvache.utils_malvache_assemblies
SCE-based k-means assembly detection (Malvache et al. 2016), built on clustering and
pairwise_cell_similarity — used by the cicada_assemblies_malvache_analysis plugin:
from cicada_analysis.cicada_tools.cell_assemblies.malvache.utils_malvache_assemblies import (
compute_and_plot_clusters_raster_kmean_version,
compute_kmean,
CellAssembliesStruct,
load_cell_assemblies_data,
)
compute_and_plot_clusters_raster_kmean_version(
labels, activity_threshold, range_n_clusters_k_mean: range, n_surrogate_k_mean: int,
spike_nums_to_use: np.ndarray, cellsinpeak: np.ndarray, data_descr: str, path_results: str,
sliding_window_duration: int, sce_times_numbers, SCE_times, perc_threshold: float,
n_surrogate_activity_threshold: int, ...
)
# → None — top-level entry point: runs clustering + statistical validation, then plots/saves
# cell-assembly figures and data files.
Stats¶
Module: cicada_analysis.cicada_tools.stats.stats
from cicada_analysis.cicada_tools.stats.stats import (
mean_ci_half_width,
line_and_band,
compare_two_distributions,
multiple_comparison_one_factor_effect,
compare_groups,
summarize_by_levels,
bh_reject,
chi_square_uniformity_test,
calculate_statistics,
)
mean_ci_half_width(x: np.ndarray, confidence: float = 0.95, n_resamples: int = 999)
# → float — bootstrap CI half-width; use as symmetric error band in PSTHs
line_and_band(data: pd.DataFrame, value: str, by: list, reduction="median", band="percentiles",
low_percentile=25, high_percentile=75)
# → pd.DataFrame — per group of `by` (e.g. time + groups): 'line' (mean / median) and 'low' / 'high' of the band
# ('SD', 'SEM', '95% CI' of the mean, 'percentiles', 'none'), 'n'; NaN ignored, no band under 2 values
compare_two_distributions(
distribution1: np.ndarray,
distribution2: np.ndarray,
pvalues: float = 0.05,
verbose: bool = True
)
# → None — runs Anderson-Darling, KS, Epps-Singleton, Mann-Whitney; prints results
multiple_comparison_one_factor_effect(
distributions_list: list, # list of arrays (one per group)
pvalues: float = 0.05,
verbose: bool = True,
sessions_ids=None
)
# → None — Kruskal-Wallis or one-way ANOVA (auto-selected) with post-hoc tests
compare_groups(rows: pd.DataFrame, value: str, x: str, hue=None, pvalues=0.05, verbose=True)
# → None — the groups of column x compared within each group of column hue (2: compare_two_distributions,
# more: multiple_comparison_one_factor_effect); NaN left out
summarize_by_levels(table: pd.DataFrame, value: str, group_columns: list,
levels=(("session", ["mouse", "session"]), ("mouse", ["mouse"])))
# → dict — {level: table of count, mean, std, min, median, max of value per group_columns + level columns}
bh_reject(pvals: np.ndarray, q: float = 0.01)
# → np.ndarray (bool) — True where H0 rejected (Benjamini-Hochberg FDR)
chi_square_uniformity_test(observed_data, binsize)
# → tuple (chi2_stat: float, p_value: float, uniformity: bool)
calculate_statistics(distribution)
# → tuple (length, mean, median, sigma, iqr)