Skip to content

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:

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:

  1. Copy the cicada_ai_helpers/ folder into your project root.
  2. 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_tools with it;
  • it follows the plugin conventions of the plugin template: super() first in setup_parameters() and run_analysis(), invalid_data_help set when check_data() refuses a file, parameter dependencies declared with set_parameter_rules(), seeded randomness, no plt.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.