Skip to content

Core developers

Core developers work on the CICADA code itself (cicada-nwb, cicada-analysis, cicada-gui), from a clone of the three repositories. Their main material is the CLAUDE.md of each repository and the docs/dev/ folder of cicada-analysis, which are not on this site. To extend CICADA from your own project, see Lab developers.

Working on the CICADA code

The three repositories are on GitLab: cicada_nwb, cicada_analysis and cicada_gui. Clone the ones you work on side by side in one folder, and install them in editable mode.

Install the clones from the bottom up (cicada-nwb, cicada-analysis, cicada-gui): each one then uses the clones installed before it; the packages you did not clone come from PyPI.

Contributing to cicada-gui only (cicada-analysis and cicada-nwb installed from PyPI):

git clone https://gitlab.com/cossartlab/cicada_gui.git /path/to/cicada_gui
conda create -n cicada_env python=3.11
conda activate cicada_env
pip install -e /path/to/cicada_gui

Contributing to cicada-gui and cicada-analysis (cicada-nwb installed from PyPI):

git clone https://gitlab.com/cossartlab/cicada_analysis.git /path/to/cicada_analysis
git clone https://gitlab.com/cossartlab/cicada_gui.git /path/to/cicada_gui
conda create -n cicada_env python=3.11
conda activate cicada_env
pip install -e "/path/to/cicada_analysis[dev]"
pip install -e /path/to/cicada_gui

Contributing to all three repos:

git clone https://gitlab.com/cossartlab/cicada_nwb.git /path/to/cicada_nwb
git clone https://gitlab.com/cossartlab/cicada_analysis.git /path/to/cicada_analysis
git clone https://gitlab.com/cossartlab/cicada_gui.git /path/to/cicada_gui
conda create -n cicada_env python=3.11
conda activate cicada_env
pip install -e "/path/to/cicada_nwb[dev]"
pip install -e "/path/to/cicada_analysis[dev]"
pip install -e /path/to/cicada_gui

To upgrade:

If you only cloned cicada-gui: pull cicada_gui, then update cicada-nwb and cicada-analysis from PyPI.

cd /path/to/cicada_gui && git pull
conda activate cicada_env
pip install -U cicada-analysis cicada-nwb

If you cloned cicada-gui and cicada-analysis: pull both repos, then update cicada-nwb from PyPI.

cd /path/to/cicada_analysis && git pull
cd /path/to/cicada_gui && git pull
conda activate cicada_env
pip install -U cicada-nwb

If you cloned all three repos: pull each repo.

cd /path/to/cicada_nwb      && git pull
cd /path/to/cicada_analysis  && git pull
cd /path/to/cicada_gui       && git pull

Run the tests with pytest from the root of each repository. The plugin tests run on the demo files.

Before contributing, read the development notes of each repository (CLAUDE.md at its root): code conventions, how plugins are structured, how to replace a computation safely, and the changelog rules. For cicada-analysis: CLAUDE.md.

Receiving a plugin proposed for core

A lab developer proposes a lab plugin for core with an issue on cicada-analysis (see Proposing a plugin for core). Once the proposal is accepted, the core team moves it:

  1. Check the conditions: standard NWB types only, read through the cicada-nwb submodules (no session.<lab>); computation in tools; the plugin conventions of CLAUDE.md.
  2. Move the code: the plugin to cicada_analysis/core_analysis/ (keep its class name, so configs written for it still run), and its tools to cicada_tools, generic ones in the existing modules rather than a copy. Plugins in core_analysis/ are found through the core entry point: no registration needed.
  3. Run its matrix on all demo files, default and drawn parameter sets, then plain pytest:

    pytest -m "slow or not slow" -k <PluginClass> tests/test_plugin_matrix.py --basetemp C:\t
    
  4. Add its demo config to tests/core_configs/ and write its reference outputs:

    CICADA_UPDATE_REFERENCES=1 pytest tests/test_demo_figure_configs.py
    
  5. Document it: its section in the plugin catalogue, the API entries of its tools in the cicada-tools pages, and a CHANGELOG line.

  6. Release it, then ask the lab package to remove the plugin and raise its minimum cicada-analysis version to that release: while both copies are installed, only one is loaded (the other is reported as a plugin error).

Building this documentation

The pages of this site are the Markdown files of the three repositories: docs/ of each repository, plus the AI helpers. Edit them there; the site is rebuilt from them.

With the three repositories side by side:

cd cicada_analysis
pip install "zensical==0.0.74" "mkdocstrings[python]>=1.0,<2"
python docs/_tools/assemble.py      # gathers the pages of the 3 repos into _build_docs/
zensical serve                      # local site at http://localhost:8000

Run assemble.py again after editing a page. Text shared with the READMEs is included with --8<-- "<repo>/README.md:<section>", where the README marks the section with <!-- --8<-- [start:<section>] --> and <!-- --8<-- [end:<section>] -->.