Lab developers¶
Lab developers pip-install CICADA and extend it from a project of their own: analysis plugins, and a lab package holding a lab's NWB conventions, tools and plugins. Their material is this site, the templates and, with an AI assistant, the AI helpers. To work on the CICADA code itself, see Core developers.
Writing an analysis plugin¶
A new analysis is a plugin class. Start from
how plugins are structured and the
annotated plugin template; the
plugin catalogue shows the existing plugins and their
parameters, and cicada-tools the functions to reuse. The template runs as
it is: while you write it, keep it in a plugin folder given to CICADA (GUI Manage plugins, --plugin-dir,
extra_plugin_dirs). Once it works, put it in a lab package (next section), so it is found everywhere
without a folder to give, and version-checked. See
where plugins come from.
Writing a lab package¶
A lab's own code (its NWB conventions, analysis tools and plugins) lives in a package of its own, installed next
to the core packages and found by them through entry points: start from the
lab package template (one working example of each part,
with tests). A lab's NWB conventions are a
lab submodule, attached to every session as
session.<lab>.
Existing lab packages¶
Below are already existing lab packages that can be installed and use in addition to the template to create your own:
- Carl Petersen lab, EPFL: cicada-petersen
- Rosa Cossart lab, INMED: cicada-cossart
Using CICADA with an AI assistant¶
The folder cicada_ai_helpers/
of cicada-analysis holds three files that give an AI coding assistant (written for Claude
Code) what it needs to write correct CICADA code: the exact signatures, parameter names and
return shapes, and rules on which tool to use for what.
| File | Content |
|---|---|
| cicada_claude.md | What CICADA is, rules, a router to the right API section, how to write a plugin and use the headless runner |
| cicada_nwb_api.md | NWBSession and the getters of each submodule |
| cicada_tools_api.md | The cicada-tools functions |
To use them with Claude Code:
- Copy the
cicada_ai_helpers/folder into your project root. -
Add these lines to your project's
CLAUDE.md(create it if absent), in this order:@cicada_ai_helpers/cicada_claude.md @cicada_ai_helpers/cicada_nwb_api.md @cicada_ai_helpers/cicada_tools_api.md
Proposing a plugin for core¶
A plugin written in a lab package can join the core collection of cicada-analysis: it is then shipped with every install, listed in the plugin catalogue, and tested on every change. A plugin can be proposed when:
- it reads only standard NWB types, through the cicada-nwb submodules: no
session.<lab>, no lab-specific columns or extensions. It then runs on any NWB file holding the data it needs; - its computation is in tools, not in the plugin: tools take arrays and tables, never a session, and the ones it
needs move to
cicada_toolswith it; - it follows the plugin conventions of the plugin template:
super()first insetup_parameters()andrun_analysis(),invalid_data_helpset whencheck_data()refuses a file, parameter dependencies declared withset_parameter_rules(), seeded randomness, noplt.show().
Before proposing it, run the plugin matrix of your lab package
(tests/test_plugin_matrix.py in the
template): each plugin on every demo file, with its default parameters and with values drawn from its parameter
schema. A run passes when the plugin refuses the file, refuses the parameters with a message, or saves non-empty
outputs.
To propose it, open an issue on cicada-analysis naming the plugin, its lab package and a demo file it runs on. Once it is accepted, the core team moves it with its tools, adds its reference outputs and catalogue section, and releases it. Your lab package then removes the plugin and raises its minimum cicada-analysis version to that release. Configs written for the plugin keep running: the runner finds a plugin by its class name.