CICADA — Claude Code Context¶
How to use the API reference files¶
cicada_nwb_api.md and cicada_tools_api.md are loaded into your context alongside this file. They are the authoritative source for all method signatures, parameter names, and return shapes. Before writing any CICADA code:
- Look up the exact signature in the relevant API file — never rely on memory or inference.
- Use the router below to identify which file and which section to consult.
- If a method name or parameter is not found in the API files, check the full API reference generated from the code (cicada-nwb: https://cicada-analysis.readthedocs.io/en/latest/nwb/api/nwb_session/ , one page per submodule) or the source (see Source code fallback); if it is still not found, say so explicitly rather than guessing.
Preference rule: Before writing any custom numeric/statistical/display code:
1. Check the Level 3 table and cicada_tools_api.md for a matching function.
2. If not found there, grep the installed cicada_tools source before concluding nothing exists — the API doc may be incomplete. Locate the source via the Source code fallback section below, then Grep inside cicada_tools/ for relevant terms (e.g. correlation, similarity, psth, detect, cluster, raster, connectivity).
3. Only proceed with a custom implementation if the source grep also finds nothing.
Source code fallback¶
If the API files don't cover a method or you need to verify a signature, follow this sequence:
Step 1 — detect active Python / conda env:
where python # PowerShell / cmd
# or
which python # bash
envs/<name>/ or envs\<name>\, the conda env name is <name>.
Step 2 — get the package location:
- If an env name was found: conda run -n <env_name> pip show cicada-analysis
- Otherwise: pip show cicada-analysis
Look at the Location: line — the source is at <Location>/cicada_analysis/. Claude Code can then Read, Grep, or Glob inside that path like any local directory.
Step 3 — only if Step 2 gives no clear Location: ask the user: "What is your conda environment name?"
What is CICADA¶
CICADA is a neuroscience analysis pipeline for NWB files, in three core packages plus one package per lab:
cicada-nwb— read-only data access. Entry point:NWBSession. Never computes, never writes.cicada-analysis—cicada_tools(computation and display functions), theCicadaAnalysisplugin system, the core plugins, the headless runner and the demo data.cicada-gui— the graphical interface (optional).- Lab packages (
cicada-cossart,cicada-petersen, yours from the template) — a lab's NWB conventions (session.<lab>), tools and plugins. The core packages find them through entry points once installed.
Dependency chain: cicada-gui → cicada-analysis → cicada-nwb → PyNWB + HDF5; a lab package depends on cicada-nwb and cicada-analysis.
Package layout (installed code):
cicada_nwb/
├── nwb_session.py # NWBSession (opens local files and DANDI assets)
├── submodules/ # NWBCalciumImaging, NWBBehavior, NWBElectrophysiology,
│ # NWBWidefield, NWBMetadata, NWBOptogenetic
├── lab_submodules/base.py # NWBLabSubmodule: base class of the lab submodules, which live in the lab packages
├── dandi.py, cli.py # DANDI access; `cicada-dandi` command
└── testing/ # synthetic NWB files for tests
cicada_analysis/
├── base/cicada_analysis.py # CicadaAnalysis ABC
├── base/cicada_groups_base.py, cicada_events_base.py, cicada_psth_base.py # family bases (groups, events, PSTH)
├── base/argument_schema.py # AnalysisArgument, AnalysisArgumentsHandler
├── base/plugin_registry.py # finds the plugins (entry points + extra folders)
├── config/runner.py # run_from_config(), run_from_combined(), generate_config()
├── config/cli.py # `cicada-run`, `cicada-config` commands
├── core_analysis/ # core plugins (standard NWB data only)
├── cicada_tools/ # computation + display functions — see cicada_tools_api.md
└── demo/ # 9 small real NWB files (demo.names(), demo.path(name)) and the configs that run on them
cicada_<lab>/ # a lab package (template: cicada_lab_package_template)
├── nwb/ # NWB<Lab>(NWBLabSubmodule) → session.<lab> (entry-point group cicada_nwb.lab_submodules)
├── tools/ # the lab's computations, arrays in / results out
└── plugins/ # the lab's CicadaAnalysis plugins (entry-point group cicada_analysis.plugins)
Critical invariants¶
NWBSessionmust always be closed after use. Choose the pattern based on the requirements:
Default — process one session at a time and aggregate (memory-efficient; use whenever per-session results can be merged after the loop):
from cicada_nwb import NWBSession
results = []
for path in nwb_paths:
with NWBSession(path) as session:
results.append(session.calcium_imaging.get_roi_response_serie_data(keys=[...]))
# merge results after the loop
All sessions open simultaneously — use only when the computation cannot be decomposed per session, e.g. cross-session normalization, computing a common reference across all sessions at once:
from cicada_nwb import NWBSession
sessions = [NWBSession(path) for path in nwb_paths]
try:
# work across all open sessions
...
finally:
for s in sessions:
s.close()
(2, N): row 0 = start times, row 1 = stop times. However, many cicada-tools functions expect event timestamps as a flat (N,) array. Extract the relevant row before passing:
epochs = session.behavior.get_behavioral_epochs_times("running") # (2, N)
events = session.behavior.get_behavioral_events_times("reward") # (2, N)
# cicada-tools that take full epoch intervals: pass (2, N) as-is
# e.g. from_timestamps_to_frame_epochs, filter_epoch_timestamps, filter_events_based_on_epochs
# cicada-tools that take a list of event times: extract row 0 (start times)
# e.g. align_array_to_timestamps, compute_psth
event_times = events[0] # (N,)
cicada_tools_api.md to confirm expected shape.
3. The keys argument for calcium imaging methods is a 3-element list [module_name, interface_name, rrs_name]. Always discover valid keys first with session.calcium_imaging.get_roi_response_series().
4. Do not store get_widefield_dff0_mmap() results outside the with block — the HDF5 handle closes.
5. A lab submodule (session.cossart, session.petersen, session.<lab>) is attached to every NWBSession when that lab package is installed (entry-point group cicada_nwb.lab_submodules); no import needed, but check the package is installed (pip show cicada-<lab>) before relying on it. Core plugins must not use them.
Router — top-down resolution protocol¶
Always resolve top-down. At each level, if the needed information is missing or ambiguous, ask one clarifying question before proceeding. If the request is specific enough that modality and data type are clear, skip directly to the relevant level. If a clarifying answer changes a previous assumption, restart from Level 1.
Level 0 — Classify the request by intent¶
Classify by what the user is trying to accomplish, not by the verb used:
| Request type | Indicators | How to proceed |
|---|---|---|
| Conceptual / design | Describes a scientific goal without naming data types or methods | Ask targeted questions to gather the minimum context needed: (1) what type of neural recording? (2) what behavioral or experimental variable? (3) what output is expected? Then resolve each component through Levels 1–3. |
| Data extraction | Wants to retrieve specific data from NWB files | Level 1 → Level 2 |
| Computation / analysis / display | Wants to process, transform, or visualize data | Level 1 (confirm modality) → Level 3 |
| Compound | Involves both extraction and computation, or neural + behavioral data together | Resolve each component independently. For neural + behavioral: establish neural modality and behavioral modality separately at Level 1, extract each at Level 2, then compose at Level 3. Extraction always before computation. |
Level 1 — Establish data modality¶
Principle: a term is modality-ambiguous if it could plausibly apply to more than one row in the table below. When in doubt, treat it as ambiguous. Do not infer modality from surrounding context alone — only a term that directly maps to a unique row below counts as unambiguous.
Ambiguous terms include but are not limited to: timestamps · traces · data · signal · activity · recording · frames · rate · events · response · onset · baseline · population · epoch-aligned · trial-averaged
| If the description unambiguously refers to… | Modality → Submodule |
|---|---|
| Fluorescence, dF/F0, calcium, ROI, optically imaged cells, two-photon, one-photon, GCaMP | Calcium imaging → session.calcium_imaging |
| Running, licking, reward, movement, trial, stimulus, locomotion, position, speed, behavioral state | Behavior → session.behavior |
| Spikes, units, electrodes, LFP, extracellular, multi-unit, Neuropixels, tetrode | Electrophysiology → session.electrophysiology |
| Widefield, mesoscale, dorsal cortical imaging | Widefield → session.widefield |
| Optogenetic stimulation, light pulses, opto trials | Optogenetics → session.optogenetic |
| Animal info, age, genotype, sex, weight, experimenter, lab, session description | Metadata → session.metadata (properties: age, age_unit, genotype, sex, species, subject_id, session_id, weight, lab, experimenter, session_description; get_sessions_info() for a dict) |
| Lab-specific conventions (a lab's own tables, labels, naming) | Lab submodule → session.<lab> (only with the lab package installed, see invariant 5) |
If still ambiguous: "Is this data from calcium imaging, electrophysiology, behavior, widefield imaging, or optogenetic stimulation?"
Level 2 — Identify specific data within the modality¶
When names are unknown, always run discovery first and show the results to the user to confirm which to use before calling any data accessor.
Calcium imaging
Discovery:
session.calcium_imaging.get_roi_response_series()
# → nested dict {module: {interface: [rrs_name, ...]}}
# If multiple series exist, present the options and ask which to use.
keys = [module_name, interface_name, rrs_name] from the chosen series, then:
| User wants… | Method | Returns |
|---|---|---|
| Fluorescence / activity values | get_roi_response_serie_data(keys) |
(n_cells, n_times) |
| What kind of activity a series holds (traces, raster dur, binary raster, spike counts, event amplitudes) | get_roi_response_serie_kind(keys), or the questions is_traces(keys), is_raster_dur(keys), is_binary_raster(keys), is_spike_counts(keys), is_sparse_activity(keys); get_roi_response_series_by_kind(kind) lists the series of a kind |
str / bool / [[module, interface, name], ...] |
| Time axis for traces | get_roi_response_serie_timestamps(keys) |
(n_times,) |
| Sampling rate | get_rrs_sampling_rate(keys) |
float Hz |
| Cell types or indices per type | get_cell_indices_by_cell_type(keys) |
{type: indices} |
Cells passing quality control (good_cells / suite2p iscell column) |
has_good_cells(keys), get_good_cells(keys) |
bool / (n_cells,) bool array or None |
| Per-cell SNR (if present in ROI table) | get_cell_snr(keys) |
[float, ...] or [] |
| Spatial footprints / masks | get_segmentations() → build seg_info, then get_pixel_mask(seg_info) or get_image_mask(seg_info) |
list of arrays |
| Raw movie frames or movie info | get_ci_movies(only_2_photons), get_ci_movie_dimension(only_2_photons=False, ci_movie_name=None), get_ci_movie_sampling_rate(only_2_photons=False, ci_movie_name=None), get_ci_movie_time_stamps(ci_movie_name=None) |
— |
Behavior
Discovery:
session.behavior.get_behavioral_epochs_names() # on/off state periods with duration (BehavioralEpochs)
session.behavior.get_behavioral_events_names() # discrete point timestamps (BehavioralEvents, ndx-events)
session.behavior.get_behavioral_time_series_names() # continuous signals (speed, position, pupil...)
session.behavior.get_intervals_names() # interval tables: trials, epochs, stimulus presentations...
session.behavior.has_trial_table() # structured trial table
| User wants… | Method | Returns |
|---|---|---|
| On/off state periods (duration) | get_behavioral_epochs_times(name) |
(2, N) |
| Discrete timestamps (no duration) | get_behavioral_events_times(name) |
(2, N), both rows identical |
| Times of a name of any of these kinds (interval table, epoch, event, epoch-table label), looked up in that order | get_event_times(name) |
(2, N) or None |
| Continuous signal | get_behavioral_time_series_data(name, in_unit=False), get_behavioral_time_series_timestamps(name), get_behavioral_time_series_unit(name); shortcuts get_mouse_speed_info() / get_mouse_position_info() |
(n_samples,) or (n_samples, n_columns); (data, timestamps) for the shortcuts |
| Structured trials with metadata | get_trial_table(), get_trials_names_from_table() (selectable columns and their values) |
DataFrame / {column: values} |
Epoch table (epochs with labels) |
has_epoch_table(), get_epoch_table(), get_epochs_names_from_table() |
DataFrame / {column: values} |
| Any interval table | get_interval_times(name), get_interval_as_data_frame(name), get_table_choices(name) |
(2, N) / DataFrame / {column: values} |
Electrophysiology
| User wants… | Method | Returns |
|---|---|---|
| Is there a units table, how many, their ids | has_units(), get_n_units(), get_unit_ids() |
bool / int / list |
| Spike times for one unit | get_single_unit_spike_times(unit_id) |
(n_spikes,) seconds |
| Spike trains of all units, filtered on quality labels | get_spike_times(col_name, labels=['all'], label_col=None, return_ids=False); col_name from get_spiketimes_col(), label columns from get_unit_label_columns() / get_unit_labels(label_col) |
array of arrays (units table order), or (trains, unit_ids) |
| Spike trains of the units of a brain region | get_spiketimes_group(spkst_col='spike_times', col_name=None, target=None, labels=['all'], label_col=None, return_ids=False) |
array of arrays, or (trains, unit_ids) |
| All units + metadata | get_units_table(extra_columns=None) |
DataFrame |
| Brain region per unit | get_units_location(col_name=None) → unique locations; get_units_location_map(col_name=None) → per unit |
(locs, col_name) / ({unit_id: location}, col_name) |
| Cell type per unit (if a cell-type column exists) | get_unit_cell_types(), get_unit_cell_type_map() |
list / {unit_id: type} |
| Electrode geometry | get_electrode_info(), get_units_coordinates() |
DataFrame |
| LFP / raw signals (ElectricalSeries) | discovery get_electrical_series() → {location: {container: [series, ...]}}, keys [location, container, series]; then get_electrical_series_data(keys, start=None, stop=None, channels=None) (window in seconds, only those samples read), get_electrical_series_rate(keys), get_electrical_series_channels(keys), get_electrical_series_locations(keys) |
(data (n_channels, n_times) in volts, times (n_times,)) / float Hz / DataFrame / (locations, col_name) |
Optogenetics
| User wants… | Method | Returns |
|---|---|---|
Is there a stimulation record (acquisition ogen_stim) |
has_opto_stimulation() |
bool |
| Stimulation periods | get_opto_stimulation_times() |
(2, N) start/stop of each run of non-zero values, or None |
| The raw stimulation signal | get_opto_stimulation_time_serie() |
(data, timestamps) or None |
Widefield
Discovery:
session.widefield.get_wf_acquisition_dict()
# → {module: [acquisition_name, ...]}
# If multiple acquisitions exist, show options and ask which to use.
keys = [module_name, interface_name], then:
| User wants… | Method | Returns |
|---|---|---|
| dF/F0 pixel data (slice) | get_widefield_dff0(keys, start, stop) |
(n_frames, H, W) |
| dF/F0 lazy full access | get_widefield_dff0_mmap(keys) — inside session context only |
H5 dataset |
| Time axis | get_widefield_timestamps(keys) |
(n_frames,) |
Level 3 — Computation and display (cicada-tools)¶
Carry the modality from Level 1. Full signatures in cicada_tools_api.md — section references given below for direct lookup.
Modality-dependent tools:
| Goal | Calcium imaging | Electrophysiology | Widefield | Section in cicada_tools_api.md |
|---|---|---|---|---|
| Extract fixed windows around events | events in seconds → align_array_to_timestamps(data, event_timestamps, frame_timestamps, window_s, subtract_baseline=False) / events as frame indices → align_array_to_events(data, event_frames, window_frames, subtract_baseline=False); data is (n_cells, n_frames) → (n_cells, n_events, n_t) |
compute_psth() (spike times) |
same functions on (n_frames, H, W) data → (n_events, n_t, H, W), or slice get_widefield_dff0(keys, start, stop) per event window |
§Event Alignment |
| PSTH | build_psth_dataframe() or build_population_psth() |
compute_psth() |
— | §PSTH — Calcium Imaging / §PSTH — Electrophysiology |
| Detect transients in neural signal | detect_small_transients() |
— | — | §Signal Processing |
| Detect population synchrony (SCE) | detect_sce_traces() (from raw traces) / detect_sce_raster() (from raster) |
— | — | §Population Burst / SCE Detection |
| Render traces / heatmap | render_traces() / render_traces_heatmap() |
render_spikes() |
— | §Calcium Imaging — Display / §Ephys Display |
| Load / slice movie frames | as_sliceable_movie(), TiffMovieView |
— | get_widefield_dff0_mmap() (NWB) |
§Tiff Movie Handling |
| Average frames by epoch | get_avg_frames_by_epoch() |
— | — | §Tiff Movie Handling |
Modality-independent tools:
| Goal | Function | Section in cicada_tools_api.md |
|---|---|---|
| Convert epoch timestamps (s) → frame indices | from_timestamps_to_frame_epochs(time_stamps_array_2N, frames_timestamps_1D, as_list, keep_if="whole") (as_list is required: True → list[(start, stop)], False → (2, N) array) |
§Period Utilities |
| Filter epochs by invalid/artifact periods | filter_epoch_timestamps() |
§Period Utilities |
| Keep only events inside epoch windows | filter_events_based_on_epochs(events_1D, epochs_2N) |
§Period Utilities |
| Nearest index in array | find_nearest() |
§Array Utilities |
| Save a figure | save_figure() |
§Display — Figure |
| Custom colormaps (hotcold, cyanmagenta…) | get_colormap() |
§Display — Figure |
| Raster visualization | plot_raster() |
§Display — Raster |
| Box plot / categorical (strip, swarm, violin, box, bar) / histogram | plot_box_plots() / categorical_plot() / plot_hist_distribution() |
§Display — Distributions |
| PSTH visualization | plot_psth_lines() / plot_raster_and_psth() |
§Display — PSTH Plots |
| Graph visualization | plot_graph() / plot_connectivity_graphs() |
§Display — Graphs |
| Pairwise similarity / correlation matrix between neurons | compute_similarity_matrix() (Pearson/Hamming/Jaccard/Cosine), build_pearson_adjacency_matrix(), plot_similarity_matrix() |
§Pairwise Cell Similarity, §Display — Connectivity |
| Spike-based connectivity graph | build_connectivity_graphs() |
§Graphs & Connectivity |
| Hub cell detection | detect_hub_cells() |
§Graphs & Connectivity |
| Putative monosynaptic connections (spike CCGs) | bz_detect_connections(), plot_pair_ccg() |
§Cross-Correlogram (CCG) Utilities, §Display — Connectivity |
| Leader/follower coupling (spike-triggered population rate) | compute_stpr() / compute_stpr_cross() (cross-area), plot_stpr_scatter(), plot_stpr_heatmap() |
§Spike-Triggered Population Rate (stPR), §Display — Connectivity |
| Peri-SCE triggered-average / "Christmas tree" plots | compute_triggered_average_raster(), plot_christmas_tree_heatmap(), plot_christmas_tree_crosscorr() |
§Peri-SCE Triggered Average ("Christmas Tree"), §Display — Connectivity |
| K-means clustering | find_best_kmeans(), plot_silhouettes() |
§Clustering |
| Sequence detection (Malvache, PCA-based) | step1_pca_off_memory(), covnorm_vectorized() |
§Sequences Detection |
| Statistical tests, FDR | compare_two_distributions(), bh_reject(), multiple_comparison_one_factor_effect() |
§Stats |
| Trial / epoch table utilities, saving tables | filter_table_with_dict(), table_time_columns(), save_tables() |
§Table Utilities |
| DLC trace preprocessing / PSTH | preprocess_dlc_trace(), build_dlc_psth_df() |
§Behavior Analysis |
| SCE k-means cell assemblies (Malvache) | compute_and_plot_clusters_raster_kmean_version() |
§Cell Assemblies |
When to offer plugin conversion¶
If a script or analysis session shows two or more of the following signals, proactively offer to convert it into a CicadaAnalysis plugin:
| Signal | Examples |
|---|---|
| Multiple cicada-tools calls chained together | alignment → PSTH → display |
| Parameters the user is iterating or tuning | "let me try threshold=0.3 instead", "what if I change the window?" |
| Running the same logic across multiple sessions | loop over NWB files, aggregating results |
| Interest in saving or reproducing the result | "save this", "I want to rerun this later" |
| Exploration of a parameter space | varying bin size, comparing methods |
| Script is growing beyond ~40 lines of analysis logic |
How to offer:
"This is getting complex enough that a CicadaAnalysis plugin would be a better fit — it gives you GUI parameter tuning, headless batch execution, and automatic reproducibility via combined YAML. Want me to convert the current script into a plugin?"
If the user agrees, use the plugin shell in the section below. Map every tunable value to the appropriate parameter helper (add_int_values_arg_for_gui, add_bool_option_for_gui, etc.), and wrap the existing analysis logic inside run_analysis. Do not change the logic itself — only restructure it into the plugin pattern.
Writing a CicadaAnalysis plugin¶
File placement (the templates are in the cicada-analysis repository, not in the pip package: https://gitlab.com/cossartlab/cicada_analysis/-/tree/master/templates):
- Your own: any folder given to CICADA (GUI Manage plugins → Add plugin folder, cicada-run --plugin-dir, extra_plugin_dirs= of the runner). Start from templates/new_plugin_template.py, which runs as it is on the demo files.
- A lab package: cicada_<lab>/plugins/cicada_<name>_analysis.py, declared once under the entry-point group cicada_analysis.plugins in its pyproject.toml (start from templates/cicada_lab_package_template/, one working example of each part). Installed, it is found everywhere without a folder to give, and its version is recorded in every run.
- Core (cicada-analysis developers only): cicada_analysis/core_analysis/cicada_<name>_analysis.py; standard NWB data only.
Any concrete CicadaAnalysis subclass found in those places is a plugin: the file and class names are free (by convention cicada_<name>_analysis.py and Cicada<Name>Analysis), no registration needed. Lab-specific data (session.<lab>) belongs in the lab package's plugins, never in a core plugin.
Plugin shell¶
from cicada_analysis import CicadaAnalysis
class CicadaMyAnalysis(CicadaAnalysis):
def __init__(self, config_handler=None):
super().__init__(
name="My Analysis", # GUI display name
short_description="Brief description",
accepted_data_formats=["CI_DATA"],
family_id="Category", # GUI grouping; None = standalone
long_description="<p>HTML for GUI tooltip</p>",
config_handler=config_handler
)
def copy(self):
# Required: a fresh instance with the same data (the runner and the GUI call it)
analysis_copy = CicadaMyAnalysis(config_handler=self.config_handler)
self.transfer_attributes_to_tabula_rasa_copy(analysis_copy=analysis_copy)
return analysis_copy
def check_data(self):
# super() first; return False + set self.invalid_data_help to grey the plugin out in the GUI
super().check_data()
for session in self._data_to_analyse:
if not session.calcium_imaging.get_roi_response_series():
self.invalid_data_help = f"No ROI response series in {session.identifier}"
return False
return True
def setup_parameters(self):
super().setup_parameters() # REQUIRED — registers results_path parameter
# Data selectors (auto-populated from loaded sessions; the kwargs value is {session identifier: choice})
self.add_roi_response_series_arg_for_gui(short_description="ROI Series", family_widget="Data",
kinds=None, optional=False) # kinds=("traces",) to offer traces only
self.add_good_cells_arg_for_gui() # 'keep_good_cells' when a ROI table has a quality column
self.add_spiketimes_series_arg_for_gui(short_description="Spike times", family_widget="Data")
self.add_unit_label_args_for_gui() # 'unit_label_column', 'unit_labels' (quality filter of units)
self.add_electrical_series_arg_for_gui(short_description="LFP") # [location, container, series]
self.add_segmentation_arg_for_gui()
self.add_ci_movie_arg_for_gui()
self.add_epoch_dict_arg_for_gui(short_description="Epochs", arg_name="epoch_names")
self.add_trial_dict_arg_for_gui(short_description="Trials", family_widget="Data") # groups built in the GUI
self.add_intervals_arg_for_gui(short_description="Intervals", arg_name="interval_names")
self.add_widefield_acquisitions_dict_for_gui(short_description="WF acquisition", family_widget="Data")
# Scalar parameters
self.add_int_values_arg_for_gui(
arg_name="window_size", min_value=1, max_value=1000, default_value=50,
short_description="Window (frames)", family_widget="Parameters"
)
self.add_field_float_option_for_gui(
arg_name="threshold", default_value=0.5, mandatory=False, min_value=0, max_value=1,
short_description="Threshold", family_widget="Parameters"
)
self.add_bool_option_for_gui(
arg_name="normalize", true_by_default=True,
short_description="Normalize", family_widget="Parameters"
)
self.add_field_text_option_for_gui(
arg_name="label", default_value="",
short_description="Label", family_widget="Parameters"
)
self.add_choices_arg_for_gui(arg_name="method", choices=["a", "b", "c"], default_value="a",
multiple_choices=False, short_description="Method", family_widget="Parameters")
self.add_color_arg_for_gui(arg_name="color", default_value=(1, 0, 0, 1),
short_description="Color")
self.add_open_file_dialog_arg_for_gui(arg_name="mapping_file", extensions=["csv"], mandatory=False,
short_description="Mapping file") # also add_open_dir_dialog_arg_for_gui
# Generic (use when no dedicated helper exists)
self.add_argument_for_gui(
arg_name="my_param",
value_type="str", # 'str' (one line) | 'text' (multi-line) | 'int' | 'float' | 'bool' | 'file' | 'dir' | 'color' | 'color_with_alpha'
default_value=None,
short_description="My param",
mandatory=True,
choices=["a", "b", "c"], # optional — restricts to a dropdown (multiple_choices=True: check list)
multiple_choices=False,
family_widget="Group"
)
# Group/color selection (named groups of choices, each with a colour)
self.add_choices_for_groups_for_gui(
arg_name="groups", choices=["cond_a", "cond_b"],
with_color=True, short_description="Groups", family_widget="Group"
)
# Output helpers
self.add_image_format_package_for_gui() # = add_save_formats_arg_for_gui + add_dpi_arg_for_gui
self.add_verbose_arg_for_gui()
self.add_analysis_description_for_gui("Optional annotation saved with results")
# Figures with a style preset, sizes, fonts, colours (read with self.figure_style(**kwargs)):
# self.add_figure_style_args_for_gui()
# Parameter dependencies are declared, not handled silently: the GUI greys the parameter out and
# the parameter files record why it is unused. Declare them after the parameters are added.
self.set_parameter_rules("threshold", enabled_if={"normalize": True})
self.set_parameter_rules("window_size", requires_data=["roi_response_series"])
def validate_parameters(self, **kwargs):
# Optional: checks across parameters, run before the analysis (GUI and headless); one message per problem
problems = super().validate_parameters(**kwargs)
if kwargs.get("window_size", 50) > 500 and kwargs.get("normalize"):
problems.append("Normalisation needs a window under 500 frames")
return problems
def run_analysis(self, **kwargs):
super().run_analysis(**kwargs) # REQUIRED — sets self._results_path
roi_series = kwargs.get('roi_response_series', {})
window_size = kwargs.get('window_size', 50)
save_formats = kwargs.get('save_formats', ['pdf'])
for session in self.get_data_to_analyse():
sid = session.identifier
if sid in roi_series:
keys = roi_series[sid]
traces = session.calcium_imaging.get_roi_response_serie_data(keys)
good = self.good_cells(session, keys, **kwargs) # bool mask from 'keep_good_cells', or None
# ... analysis code: read the data here, compute with cicada_tools functions on arrays ...
# Save figures (always through save_figure: it also writes the .mplfig file the GUI's Interactive viewing
# tab shows when "Interactive viewing of the figures" is ticked, a checkbox added with save_formats):
# from cicada_analysis.cicada_tools.display.core_plots import save_figure
# save_figure(fig, self._results_path, "figname", save_formats=save_formats)
# Anything random (surrogates, shuffles, random cells): declare the seed in setup_parameters with
# self.add_random_seed_arg_for_gui(used_for="the surrogates"), then draw from
# rng = self.random_generator(**kwargs) (or self.random_generators(n, **kwargs): one per random step)
# and pass it on (cicada_tools functions take seed=rng). Never np.random.* or random.* directly.
self.selected_series(kwargs.get("roi_response_series"))gives[(session, keys), ...]for the sessions with a series selected: use it instead of testing the dict by hand.requires_data=keys (set_parameter_rules):units,spike_times,roi_response_series,traces,sparse_activity,raster_like,spike_raster,rows_of_cells,cell_types,good_cells,imaging_movie,background_image,electrical_series,behavioral_time_series,trial_table,epoch_table,intervals,epochs,speed,position(cicada_analysis/base/data_requirements.py). A parameter whose data no loaded session has is hidden.- Family base classes (
cicada_analysis.base), to inherit from instead ofCicadaAnalysiswhen the plugin compares groups or aligns on events, so that it shares the parameters and figures of the core plugins of the same family:CicadaGroupsBase(epoch, session, cell-type, cell-index and area groups, group figures),CicadaEventsBase(adds trial groups of a table at one of its time columns and optogenetic stimulations as event sources),CicadaPsthBase(adds the PSTH events, window, reduction and figure parameters). Read their docstrings before writing a PSTH or a group-comparison plugin. plt.xkcd()only as a context manager; noplt.show()in a plugin.
Headless runner¶
Every task exists as a command (cicada-run, cicada-config, installed with cicada-analysis), as Python, and in the GUI; the command and the Python call take the same options.
cicada-config sessions /data/mouse1 -o sessions.yaml [-r] # list the .nwb files of a folder (or a DANDI address)
cicada-config params CicadaMyAnalysis -s sessions.yaml -o params.yaml --results-path /results [--plugin-dir DIR]
cicada-run -s sessions.yaml -p params.yaml [params2.yaml ...] [--results-path DIR] [--plugin-dir DIR]
cicada-run --replay combined_CicadaMyAnalysis_2026-06-14T10-30-00.yaml
from cicada_analysis.config.runner import run_from_config, run_from_combined, generate_config
# 1. Generate a filled parameter YAML (defaults, and the choices available in the sessions: the files are opened)
generate_config(
analysis_class=CicadaMyAnalysis, # subclass, not an instance (cicada-config params takes the class name)
output_yaml_path="params.yaml",
sessions_yaml="sessions.yaml",
result_path="/results", # written as results_path (created if needed; None: set it before the run)
overrides={"window_size": 100} # optional: pre-fill specific parameters
)
# 2a. Run from one params file — returns a single CicadaAnalysis instance
result = run_from_config(
sessions="sessions.yaml",
params="params.yaml",
save_combined=True, # default: True — writes combined_*.yaml in the results folder
extra_plugin_dirs=None, # list of folders with your own plugins (not needed for installed lab packages)
results_path=None, # overrides results_path from the YAML if set
hash_inputs=False, # True: sha256 of the local input files in the combined YAML (slow on large files)
dandi_mode=None # DANDI files: "stream" (default), "download" or "auto"; dandi_download_dir=...
)
# 2b. Run from multiple params files — sessions loaded ONCE, analyses run sequentially
# Returns a list of CicadaAnalysis instances (one per params file)
results = run_from_config(
sessions="sessions.yaml",
params=["params_analysis1.yaml", "params_analysis2.yaml"]
)
# 2c. Alternative: pass a combined YAML directly (equivalent to run_from_combined)
result = run_from_config(combined_config="combined_CicadaMyAnalysis_2026-06-14T10-30-00.yaml")
# 3. Replay an exact previous run from its combined YAML (same options as run_from_config)
result = run_from_combined(
"combined_CicadaMyAnalysis_2026-06-14T10-30-00.yaml",
save_combined=True, # default: True
extra_plugin_dirs=None, # the same folders as the original run
results_path="/new/output/path" # redirect outputs without editing YAML
)
sessions.yaml (top-level sessions: key; a relative path is resolved against the folder of the YAML file; a DANDI address such as dandi://000728/sub-.../file.nwb is accepted; identifier is a label for the reader only, the runs name the sessions by the identifier stored in each NWB file):
sessions:
- identifier: mouse1_day1
path: /data/mouse1_day1.nwb
- identifier: mouse2_day1
path: ../data/mouse2_day1.nwb
Demo data to try a plugin or a config: from cicada_analysis import demo; demo.names() lists the 9 trimmed real NWB files shipped with cicada-analysis (Allen, IBL, DANDI, Cossart, Giocomo, Petersen...), demo.path(name) gives one, demo.paths() all of them, demo.SESSIONS is a sessions YAML listing them all, and demo.figure_config(class_name, session_path) returns the shipped Figure 3 config of a core plugin on a demo file (demo/figure_configs/), to replay or to start from.
params.yaml:
analysis_class: "CicadaMyAnalysis"
analysis_module: "cicada_my_analysis" # module of the class (here a file of an extra_plugin_dirs folder)
results_path: "/results"
roi_response_series: {}
window_size: 50
normalize: true
save_formats: ["pdf", "png"]
The *combined_.yaml is written in the results folder after every run (filename: combined_{ClassName}_{timestamp}.yaml). It embeds the sessions, the class, all final parameter values, the run duration and the provenance: version, git commit and "uncommitted changes" flag of each CICADA package and lab package installed (plus the sha256 of the inputs with hash_inputs=True). Replay warns when the installed versions differ. Use run_from_combined() / cicada-run --replay to replay exactly. analysis_module is optional in params.yaml — the runner finds the class by name among the installed plugins (entry-point group cicada_analysis.plugins: core and lab packages) and the extra_plugin_dirs / --plugin-dir folders.
Key constraints¶
- No parallel execution on the same NWB files —
NWBSessionholds HDF5 file handles open. Run analyses sequentially. super().setup_parameters()must be called first insetup_parameters— it registers the mandatoryresults_pathparameter.super().run_analysis()must be called first inrun_analysis— it resolvesself._results_pathfrom kwargs.copy()must return a fresh independent instance — the headless runner calls it to create isolated instances per session group.