cicada_tools.display.distribution_plots.plot_scatter_family is removed: used by no plugin, and it crashed with its default arguments (label_to_legend=None, with_timestamp_in_file_name=False).
Connectivity graph: the segmentation parameter is removed. With use_imaging_pos, an imaging graph places the cells using the segmentation its activity series refers to (one mask per row of the series), as the pairwise similarity does. Before, the segmentation was chosen separately: if it was left empty, the layout silently had no cell positions; if it did not match the series, the positions were wrong or the run crashed (e.g. the widefield grid series with the brain-areas segmentation). With the series' own segmentation, the positions are the same as before. A config that still has segmentation: runs with a warning that the parameter is ignored.
Lab package template: tests/test_plugin_matrix.py, the plugin matrix of the core plugins run on the package's own plugins (every demo file; default parameters with plain pytest, drawn parameter sets with pytest -m slow).
Docs, "Proposing a plugin for core": how a lab plugin that uses standard NWB types only can join the core collection (lab developers page), and how the core team moves it (core developers page).
Replay: the combined YAML records a hash of its analysis, parameters and session identifiers (config_sha256), and a replay warns when they were edited after the run. Moving the input files or the results folder is not an edit; files written before have no hash and are not checked.
Provenance of lab plugins: the combined YAML records the version, commit and uncommitted-changes flag of the lab package a plugin comes from, and a replay warns on a difference, as for the core packages, or when that package is not installed. The commit of a package installed with pip from a git address (direct_url.json) is recorded too, core packages included.
Spike-triggered population rate (stPR): about 6 to 8 times faster on full ephys files (IBL, 1970 units over 81 min: about 30 min, now 4.3 min; MH031, 1904 units over 49 min: 18 min, now 2.3 min). The cross-correlation of each unit with the population rate is computed only at the lags that are kept (the window and the filter pad: 461 lags with the ephys defaults), as a sum over the unit's spikes, instead of over the whole recording with an FFT. Same values as before, within the output-regression tolerance (differences of the order of 1e-14), for spike times, imaging events and the cross-area stPR.
Connectivity graph: the cross-correlogram figures of the pairs are about 10 times faster. With the default 500 ms window there are 2501 bars per figure. They are now drawn as one artist instead of one rectangle each, which took about 4 s per pair to draw and save. The figures are identical, pixel for pixel, to the ones made before.
Imaging movies in TIFF files are read with tifffile only, so scanimage-tiff-reader is no longer installed. That package's last release (1.4.1.4, 2023) has no wheel for Python 3.11+ or macOS, so pip built it from source. Raw ScanImage tiffs, which store a header before each frame, are now memory-mapped in TiffMovieView. Their frames sit at a constant distance from each other in the file, and the map skips the headers. Before, every slice was read again through ScanImageTiffReader. Frame ranges are now read about 2x faster (200 frames of 512 x 512: 0.02-0.03 s, was 0.05 s). read_tiff_movie_frames, load_tiff_movie and TiffMovieView return the same frames, dtype and shapes as before, checked on raw ScanImage and suite2p registered tiffs. Loading a whole file that is already in the system cache is slightly slower (0.11 s instead of 0.07 s for 250 MB). The first read over a network drive takes the same time with both readers.
Replay: a results_path that does not exist on this machine (a combined YAML sent by someone else) falls back to <Downloads folder>/cicada/results, with a message, instead of stopping the run; --results-path / results_path= still choose the folder.
Docs: the home page title and description name what CICADA is (Python analysis of NWB neurophysiology data) for search engines, with a link to the CICADA page of the NWB community tools; the site description is reworded the same way, and the main pages (get started, plugin catalogue, cicada-tools reference, lab developers, cicada-nwb) have their own description.
The PyPI page links to the documentation, the repository and the issues ([project.urls]).
Docs: the Developers page is split into "Lab developers" (overview/developers/lab/: plugins, lab packages, AI helpers) and "Core developers" (overview/developers/core/: working on the code, building the docs). Links to overview/developers/#... anchors move to overview/developers/lab/#....
Plugin templates (templates/new_plugin_template.py and the lab package template's plugin): with "Plotted data and intermediate files" on (save_figure_data), the per-cell values of the figure are saved as a CSV next to it, as the core plugins do.
PSTH ephys, artifact correction: default artifact window 10 ms before to 5 ms after the onset (was 1 ms before to 4 ms after), as proposed by Myriam Hamon; the baseline still runs from 'Time before the event' to the start of the artifact window. replace_artifact_spikes defaults to the same window, with a baseline from 500 ms to 10 ms before (was 200 ms to 1 ms). Runs with the correction on and the default window change; configs keep the values they record.
cicada_tools.ephys.psth_utils.compute_psth: its window arguments are renamed window_start, window_end (were t_before, t_after): times relative to the event, the start negative before it, while t_before is a positive duration everywhere else. Same computation; positional calls are unchanged, calls by the old keyword names fail.
Sequences detection: the output folder and files of a session are named after its identifier made a valid file name, for every identifier. Before, an identifier containing / (e.g. a path) was replaced by <subject>_<session>, and other characters invalid in file names (:, \ on Linux...) were kept.
Fewer dependencies: scikit-posthocs and statsmodels are no longer installed (statsmodels was only there for scikit-posthocs, and capped below 0.15 for it). The post-hoc tests printed by the statistics (Dunn's test with Bonferroni correction after Kruskal-Wallis, t-tests with Holm correction after an ANOVA) are now in cicada_tools.stats.stats (posthoc_dunn, posthoc_ttest, adjust_p_values), with the same p-values as scikit-posthocs (compared on artificial data).
Docs, cicada-tools reference: the entries marked "draft" are checked against the code (parameters, defaults, return values) and completed; the functions of ephys.signal_psth (PSTH of LFP / ECoG) are documented.
Docs, install pages: user install only, the install from a clone moves to the Core developers page; the clone recipes of the READMEs install the test dependencies ([dev]). The replay docs say that a run from the GUI records only the size of local input files: exact replication needs --hash-inputs.
stPR and connectivity graph, GUI: the parameter boxes have readable titles instead of internal names: "Cross-correlation: ephys" and "Cross-correlation: imaging" (stPR), "Connections", "Graph figures", "Saved graphs" and "Epochs" (connectivity graph); their colours are in the "Figure style" box.
cicada_tools.imaging.get_avg_frames_by_epoch: an epoch starting at frame 0 (the first frames of the movie) was skipped as out of bounds, and is now averaged with the others. Only an epoch starting before the movie or ending after it is skipped. This changes the averages of the cicada-petersen widefield plugins (movie average, time courses) when a window starts exactly at the first frame.
display.core_plots.save_figure crashed on a seaborn grid (FacetGrid, returned by relplot, catplot, lmplot...) with an AttributeError since 0.4.0: a grid is now saved through its figure. Matplotlib figures are saved as before.
Docs site: each page's canonical link and the sitemap pointed to the site root without /en/latest/, where the pages are not served (404), so search engines were sent to missing pages; they now point to the pages' real address.
Docs, plugin catalogue: the PSTH on electrical series (LFP, ECoG) plugin had no entry; added, with its parameters.
Docs, plugin catalogue: the links to the four PSTH plugins under "PSTH plugins: shared parameters" pointed to their former headings.
TIFF movie, frame range: the whole range was read into memory before being written, so a long range of a real recording crashed (e.g. 78,000 frames of 512 x 512: 38 GiB). The frames are now read and written 1 GiB at a time (new tool imaging.images_handling.write_tiff_frames; same TIFF file as before: one series, BigTIFF past 4 GB), whatever the length of the range.
PSTH behavior (outputs change): sessions at different frame rates were never averaged together (each kept its own time values), and the time of each value was stretched over the window (np.linspace from -before to after) instead of the samples' own times. Each value now has the time of its sample (build_dlc_psth_df returns a time column), and the sessions are put on the common time grid of the population PSTHs (below) before the mice and groups (new tool imaging.psth_utils.psth_rows_on_grid).
Imaging and behavior population PSTHs (outputs change): the common time grid had its edges from -before in steps of the lowest rate, so when before x rate was a whole number (e.g. 10 Hz and 1.5 s, frequent) the samples fell on the edges and rounding put two samples in one bin and none in another, also inside the window (200 of 882 rate and window combinations tried): a value averaged with its neighbour, and an empty bin set to 0. The grid now has one bin per sample of the lowest rate, centred on it (core.event_alignment.psth_grid_edges): a session at that rate keeps its own values at its own sample times; faster sessions are averaged within each bin. The times of the tables are these sample times.
Population PSTHs (outputs can change): a time bin of the common grid without any sample of a session was 0 for that session, a value it never had (e.g. a dF/F or a position of 0); it is now NaN, left out of the reductions over sessions and mice, and a gap in the figure.
Connectivity graph: a graph saved by an earlier run (Connectivity_graphs/ next to the results, or force_path_to_graph) was loaded whenever a file of the same name existed, even if it had been built from other data, other parameters or older code. Each saved graph now has a key file (<graph>.graphml.json: a hash of the data the graph is built from, the build parameters, the cicada-analysis version and the build date), and is loaded only if that key matches; otherwise it is rebuilt (graphs saved before have no key file: rebuilt once). Each run prints, for each graph, whether it was built or loaded and why, and saves it in graphs_built_or_loaded.json. New parameter "Rebuild the graphs" (rebuild_graphs). New tools graph_building.graph_key, cached_graph, save_graph_key.
PSTHs (outputs can change): an event whose window starts exactly on the first frame of the recording was left out (NaN or dropped) though the window fits; it is now kept. At most one more event per session. In align_array_to_events, align_array_to_timestamps(drop_outside=True) and align_single_cell_to_epochs.
Connectivity graph: session identifiers and epoch group names that are not valid file names (e.g. paths) broke the names of the saved graphs (.graphml) and monosynaptic connections tables; they are now made valid file names, as for the figures.
Figures (cells map, Display activity, connectivity graph, Malvache assemblies, grids of core_plots): fig.set_layout_engine("tight", ...) in place of fig.set_tight_layout, deprecated in matplotlib (same layout).
Sequences detection: no more division-by-zero warning for cells with a constant trace (covnorm_vectorized; results unchanged).
Cells map: the group outlines (convex_hull) no longer use np.cross on 2-D vectors, deprecated in numpy 2 (results unchanged).
Behavior traces cleaning (DLC PSTH, Display behavior, Display activity: preprocess_dlc_trace): a series without any value was replaced by zeros, drawn as a flat 0 line; it now stays NaN (a gap). A constant series no longer gives a division warning (remove_outliers_zscore; unchanged).
PSTH imaging, surrogates: the band of the surrogates is computed only where it exists, without the "All-NaN slice" warning when there is no band (band 'none', or a single event). A band asked for with a single event now says it is not drawn ("1 event, no SEM band (it needs 2 events)").
Cells map, background image from a movie: pixels without value in every frame (e.g. outside the brain in widefield dF/F) no longer give a "Mean of empty slice" warning; their number is printed, and they are still drawn with the darkest value.
Epoch helpers (cicada_tools.core.period_utils, outputs change): get_epoch_frames left out frame 0, so an epoch starting at the first frame lost it; it is kept. get_epoch_transition_list left out the start of the last epoch when the first epoch starts at 0; only that first start is left out (nothing before it: not a transition).
Combined config (combined_*.yaml): a parameter not used in the run (e.g. the journal columns with a custom figure width) was written with the value left in the GUI, so its replay warned that the value was ignored. It is now written with its default, the value the run used, still labelled NOT USED in this run.
Sequences detection, speed panel under the heatmap (imaging_plots.render_traces_heatmap): a speed of 0 (or missing) throughout gave matplotlib identical limits, with a warning and the line in the middle of the panel; the panel now goes from 0 to 1, the line at the bottom.
Sequences detection: the rank correlation of the cell orders (Kendall's tau) on fewer than 2 cells printed a scipy warning; it is now NaN without calling scipy (same values as before).
cicada_tools: functions that CICADA no longer calls are removed. sequences.malvache.utils_malvache_sequences: xcov and covnorm (use covnorm_vectorized, all cells at once), step1_pca (use step1_pca_off_memory, the same lag-1 PCA without forming the n_times × n_times matrix). cell_assemblies.malvache.utils_malvache_assemblies.give_significant_sce_clusters. clustering.find_significant_kmeans. behavior.behavior_analysis_utils.smooth_trace (it was scipy.ndimage.gaussian_filter1d). display.cells_map_utils: get_coords_extracted_from_fiji, get_coords_from_caiman_format_file, get_coords_from_suite2p_format_file (cell contours come from the segmentation in the NWB file). display.core_plots.make_color_map. ephys.anatomy_utils: get_custom_area_groups, get_area_group_colors (import the constants AREA_GROUPS, AREA_GROUP_COLORS). The module display.videos (video reader classes).
mat73 and read-roi are no longer installed with cicada-analysis: only the Fiji and CaImAn contour readers above used them.
cicada_tools.core.table_io is renamed cicada_tools.core.table_utils (same functions), and the trial / epoch table helpers filter_table_with_dict, table_time_columns, table_column_times move there from cicada_tools.behavior.behavior_analysis_utils (same code). All are also importable from cicada_tools.core, which the plugin templates now use.
select_cells (the cells of a cell group: cell types and typed indices) moves from cicada_tools.imaging.psth_utils to cicada_tools.core.parameter_utils (same code), also importable from cicada_tools.core: it serves the imaging and the ephys plugins.
Spike binning and smoothing move from cicada_tools.ephys.psth_utils to cicada_tools.ephys.ephys_signal_processing (same code): count_active_units_per_bin, compute_rolling_binned_activity, binarize_activity, smooth_causal_half_gaussian. psth_utils keeps the PSTH building. count_active_units_per_bin and smooth_causal_half_gaussian are still importable from cicada_tools.ephys.
Connectivity figures move to a new module cicada_tools.display.connectivity_plots (same code): plot_christmas_tree_heatmap, plot_christmas_tree_crosscorr, plot_stpr_scatter, plot_stpr_heatmap, plot_stpr_heatmap_grid, plot_pair_ccg from cicada_tools.connectivity.connectivity_utils, and plot_similarity_matrix, plot_similarity_vs_distance from cicada_tools.connectivity.pairwise_cell_similarity. The computations stay in cicada_tools.connectivity.
Behavior tools split (same code): the legend of the bands drawn over a display, add_bands_legend and bands_legend_handles, moves from cicada_tools.behavior.behavior_analysis_plots to cicada_tools.display.core_plots; the epoch helpers get_epoch_frames and get_epoch_transition_list move from cicada_tools.behavior.behavior_analysis_utils to cicada_tools.core.period_utils (also importable from cicada_tools.core). plot_with_point_and_strip, used only by the Petersen lab, moves to the cicada-petersen package.
demo/sessions_demo.yaml: the demo files as a group of sessions (paths relative to it), shipped with the package (demo.SESSIONS). demo.figure_config(analysis_class, session_path): the Figure 3 config of a plugin on a demo file (the same file: path and recorded size), or None; used by the GUI to load the plot's parameters.
The Figure 3 demo configs save the data of their figures (save_figure_data: true), which the output regression below compares with references.
Output regression: cicada_analysis.testing.regression (output_numbers, save_reference, load_reference, compare_numbers) reads the numbers a run saved (csv columns, npy, txt, tiff movies; arrays of more than 20,000 values as shape, sums and a sample) and compares them with a reference (rtol 1e-9). tests/test_demo_figure_configs.py replays every demo config and compares its numbers with tests/references/ (repo only); CICADA_UPDATE_REFERENCES=1 rewrites them. The release tests require a reference for every config that replays offline.
"Plotted data and intermediate files" (save_figure_data), a parameter of every plugin in the "Figure saving" group, the only switch of the files other than figures: the result tables, the values each figure is drawn from (tables as .csv, series drawn sample by sample as .npy with a .csv of their rows) and the other files (TIFF movies, .graphml graphs, cell assemblies .txt). On by default in the plugins whose tables are their result (the 5 PSTHs, TIFF movie, stPR, transient frequency and amplitude, pairwise similarity, sequences, assemblies, connectivity graph), off in Display activity, Display behavior and the cells map. With it on, the displays also save what they draw: Display activity the rows (raster_<session>_data.npy and _times.npy, or _spike_rows.npy and _spike_times.npy for spikes; _rows.csv: row, id and what the id is; _activity_sum.npy when computed), each behavioural series under it (_behavior_<name>_data.npy / _times.npy) and the event, epoch and stimulation bands (_events.csv: group, start, stop); Display behavior each series as drawn, the list of series (_series.csv) and the bands (_events.csv); the cells map one row per cell (<session>_cells.csv: centre, shown, groups, colour, number of transients with 'firing rate'); the Malvache assemblies on traces the traces with their small transients and the SCEs (<id>_sces.csv), also when no assembly is found; the connectivity graph its nodes and edges (<graph>_nodes.csv, _edges.csv) in the run folder. New tools cicada_tools.core.save_tables, save_samples, ragged_to_arrays, intervals_table, display.cells_map_utils.cells_table, graphs.graph_analysis.graph_tables (the tables written before through them: files identical on the demo files). The plugin matrix runs with the option on and fails a run that saves figures without any data file.
cicada_analysis.testing.matrix: runs a plugin on a session with its default parameters or with values drawn from its parameter schema (seeded, so a set always draws the same values), and reports crashes and empty outputs saved without a message. Used by the core tests on every core plugin and demo file (pytest: default parameters; pytest -m slow: 20 sets each), and usable by lab packages on their own plugins (matrix.plugins("<entry point>")).
Demo figure configs: the combined configs of Figure 3 of the paper, one folder per panel and one file per plot (demo/figure_configs/A1/A1_cellmap.yaml, ... 14 plots of panels A1, A2, B1, C1, D1; described in docs/overview/demo.md), replacing the 3 earlier ones. Sessions are the demo files, relative to the YAML, except D1 (Giocomo, full file on DANDI 001361 at a fixed version, streamed on replay); results go to the current folder. A1_graph computes its graph instead of loading saved graph files.
New core plugin "PSTH ephys - electrical series" (CicadaSignalPsth): an LFP, ECoG or raw electrical series aligned on events, reduced over the channels at each event, then over events, sessions and mice, as the imaging population PSTH. Channel groups by electrode group (e.g. shanks, ECoG grids), location or typed channel indices; a Butterworth filter (band-pass, high-pass, low-pass, order); frequency bands as groups (presets delta to high gamma, or typed '4-8'), each as its filtered signal, amplitude envelope (Hilbert) or power; time bins, baseline subtraction or z-score. Only the signal around the events is read. Tools in cicada_tools/ephys/signal_psth.py; the end of the population PSTHs (common grid, levels, tables, figures) is shared in CicadaPsthBase.save_population_psths (imaging PSTH outputs unchanged, checked on 4 configurations).
Sequences detection: option to plot only a time slice of the sequences (time_slice, slice_start, slice_end, in s of the NWB file). The sequences are still detected on the whole recording; the heatmaps keep the recording's frame numbers and colour scale. render_traces_heatmap takes first_frame for the x tick labels.
Command line, each command a thin wrapper of a runner function with the same options: cicada-config sessions <folder or DANDI address> -o sessions.yaml [-r] (generate_sessions_config, new: lists the .nwb files of a local folder, optionally recursive, or of a DANDI dandiset / folder of it with version-pinned addresses, without opening them), cicada-config params <AnalysisClass> -s sessions.yaml -o params.yaml [--results-path] (generate_config), cicada-run -s sessions.yaml -p params.yaml [more params...] (run_from_config) and cicada-run --replay combined.yaml (run_from_combined), with --results-path, --hash-inputs, --no-combined, --plugin-dir, --dandi-mode, --dandi-download-dir. The headers of the parameters and combined YAMLs give the command (and still the Python call); the headless workflow page shows the command of each step. After updating, reinstall cicada-analysis (pip install -e ./cicada_analysis --no-deps) so the commands are installed.
DANDI files in headless runs: dandi_mode= and dandi_download_dir= arguments of generate_config, run_from_config and run_from_combined (stream / download / auto; downloads by default in <Downloads folder>/cicada), DANDI_MODE and DANDI_DOWNLOAD_DIR in the config and run templates.
templates/generate_sessions_yaml.py renamed templates/generate_sessions_config_template.py; it calls generate_sessions_config (same YAML written, checked on the demo files) and its LOCATION (was NWB_DIR) may be a DANDI address.
More replay warnings, printed by run_from_combined and the GUI, never blocking: an installed package outside a version range declared by cicada-nwb, cicada-analysis or cicada-gui (dependency_range_warnings()); parameters in the YAML the plugin does not have (ignored; before: skipped silently) and plugin parameters missing from the YAML (default used) (AnalysisArgumentsHandler.config_name_warnings(), also for params files in run_from_config). plugin_registry.incompatible_requirements(dist, names=None) checks every requirement. The headless workflow page describes what the combined YAML records and what replay checks (it said a replay "reproduces the run exactly").
The combined YAML records the environment of the run in an environment: block: Python version and, for cicada-analysis, cicada-nwb and cicada-gui, version, git hash and dirty (uncommitted changes; hash and flag only for development installs from a clone). It replaces the top-level cicada_*_version / cicada_*_git_hash keys. Each run also writes the installed packages next to the YAML, combined_<class>_<timestamp>_environment.txt (pip freeze, with the commit of editable and git installs; versions only if pip fails), named in the block; replay ignores it. At replay (run_from_combined, the GUI when loading a combined YAML), warnings for a different Python version, CICADA version or commit, and for uncommitted changes in the recorded run or now. Combined YAMLs written before 0.4 still replay, with one warning (versions not checked, parameter names may have changed). New: current_environment(), save_environment_file().
The combined YAML records each input file: every sessions: entry gets the file size, its sha256 and, for DANDI files, dandi: {dandiset_id, version, asset_id}. DANDI files always get the archive's sha256; local files only with hash_inputs=True (run_from_config, run_from_combined, save_combined_config; one full read of each file, off by default). At replay, check_input_files(config, sessions) compares the files opened with the recorded ones (identifier, size, sha256, DANDI version and asset ID, matched by path) and run_from_combined prints a warning for each difference, never blocking; without a recorded sha256, a note says the content was not checked (a file edited in place can keep its size).
Figure style for every plugin (the 15 core plugins, the lab plugins to follow): CicadaAnalysis.add_figure_style_args_for_gui(elements=..., defaults=..., standard=...) and figure_style(**kwargs), the style itself in cicada_tools/display/figure_style.py (FigureStyle, PRESETS, FIGURE_ELEMENTS). Sizes in mm, fonts and lines in pt; presets default (journal: 7 pt text, 0.8 pt lines) and presentation (10 pt text, 1.5 pt lines, larger ticks and axes), one or two journal columns wide (89 or 183 mm, figure_columns, 2 by default for the long or dense figures), or custom values (the options a preset sets, including the tick direction, number of ticks and top / right axes, typed only with custom). Two GUI groups: "Figure style" (preset first; size, text, axes, lines and markers, colours, legend) and "Figure saving" (formats, interactive viewing, transparency, dpi, rasterizing, timestamp). Every figure of a run takes the style (FigureStyle.applied in AnalysisArgumentsHandler.run_analysis: matplotlib settings, xkcd sketch mode, and core_plots.finish_figure on every saved figure: number of ticks, titles, rasterized dense layers); the plugins pass the other values (width, panel shape, colours, sizes) to their figures. Each plugin offers only the options its figures use (elements: panel shape, axes, titles, lines, panels, legend, annotations, scale bars, markers, bands, reference lines, colormaps, colour bar), some of them only with the plugin parameters that draw them (e.g. the cells map colormap with "firing rate"), with its own defaults (e.g. a dark theme for Display activity, connectivity graph, stPR, cells map and assemblies; the hot colormap and pale yellow text of the sequences). Colours: theme light / dark / custom (background and text colours), reference line colour, every colormap a plugin offered before, the categories always in the Okabe-Ito colourblind-safe colours. New: core_plots.add_colorbar (a colour bar of a width in mm), add_scale_bar(thickness=...) in pt.
Display activity saves the IDs of the rows it shows, in the order of the figure, with "Plotted data and intermediate files": raster_<session>_rows.csv (imaging: row of the ROI response series; spikes: unit id of the units table; LFPs: channel position in the series; column id_kind). The cells drawn at random can be read without a rerun.
SCE detection with a mask of allowed frames (Malvache assemblies rework): detect_sce_raster(..., method="Peaks" | "All frames", frames_mask=None, participation_margin=1) (one function for the raster SCEs of the assemblies plugin and of detect_sce_traces; vectorized window sum) and frames_mask in detect_small_transients / detect_sce_traces: SCEs and transients only in an epoch or during immobility, frame numbers staying those of the recording. detect_sce_raster returns (cells_in_sce, sce_windows, threshold) (before: peak frames and the input raster); detect_sce_traces still returns the peak frames. Results without a mask: identical, except the two fixes below (proofs in the revision scratchpad).
CicadaAnalysis.behavioral_series_at_frames(session, name, frame_times, n_times) and NO_SERIES: a behavioral time series at the imaging frames (moved from seq Malvache, unchanged), used by seq Malvache and the Malvache assemblies.
Connectivity graph: "Node size (points²)" (node_size, 1–500, default 20) for the single graphs and the figure with all graphs (before, fixed at 20 and 10). The edges' width and the arrows grow with the dots' diameter, and are twice as large relative to the dots as before (width 0.8, arrows 8 at size 20).
Cells map: "firing rate" colouring works with traces too: the transients are detected from the traces (peaks more than 3 SD of the noise above the baseline, as in Transient frequency) and counted. Before, traces were refused. A colour bar (number of transients, or of spikes for spike counts) is drawn right of the map; the figure is widened for it, the map keeps its size.
Display activity: "Show Y-axis scale" now works on rasters and heatmaps too, with a bar of a number of cells (units for spike times) set by "Length of the Y-axis scale bar on rasters (cells)" (y_scale_n_cells, 1–1000, default 10; shown only when a loaded session has data drawn as rows of cells: spike times, binary rasters, spike counts or event amplitudes, new data requirement rows_of_cells). Before, the y scale bar was drawn only on traces. The scale bars are outside the data, on rasters, heatmaps and traces (LFPs too): the time bar above the top left corner, the y bar left of it, its label written along it (before, on traces: both inside, the y bar top right).
Demo figure configs cicada_analysis/demo/figure_configs/ (shipped with pip install): combined configs that replay on the demo files (run_from_config(combined_config=<file>)), on cossart_ophys_000219: a cells map coloured by firing rate and a raster (Display activity). Their session paths are relative to the demo data and their results go to the folder the replay is run from (results_path: .). Tests tests/test_demo_figure_configs.py check that each one is portable and replays.
Combined configs accept session paths relative to the YAML file's folder (load_combined_config, so replays from the runner and the GUI). Before, a relative path was opened from the current folder.
Cells map: "Cells' number size (pt)" (cell_numbers_size, 1–20, default 6), used with "Display cell numbers". Before, the size was fixed at 6 pt. When the figure takes the background image resolution, the size is divided by 6: the default gives 1 pt as before (the code asked for 0.05 pt, which matplotlib draws at 1 pt), larger values now make the numbers bigger. Intended change: in that mode the numbers are drawn bold, as on the other figures, instead of ultralight.
Version check of plugin packages: a package whose declared range of cicada-nwb / cicada-analysis / cicada-gui does not match the installed versions is not loaded (none of its plugins is imported); the GUI Plugin Manager lists it under "Not loaded" with the reason (e.g. "needs cicada-analysis>=0.4,<0.5, installed 0.3.2"). Requirements without a range and those of extras are not checked. New dependency packaging.
Lab package template templates/cicada_lab_package_template/ (repo only): a lab's NWB conventions (nwb/, entry point cicada_nwb.lab_submodules), analysis tools (tools/) and plugins (plugins/, entry point cicada_analysis.plugins) as one installable package, with one working example of each part and their tests (the plugin runs on the demo files). templates/new_plugin_template.py rewritten: it runs as it is (mean activity per cell, optional shuffled baseline) and follows the current conventions (super() first, selected_series, declared parameter rules, validate_parameters, seeded random generator, save_figure, no plt.show()); the folder list and the file naming rule, obsolete since the plugin registry, are gone.
Plugin registry cicada_analysis.base.plugin_registry, used by the runner and the GUI: plugins are found in the installed packages that declare them under the entry-point group cicada_analysis.plugins (an entry point names a package, walked recursively, or one plugin class), then in the extra folders. cicada-analysis declares core (core_analysis) and, until they move to their lab packages, cossart and petersen. A plugin is any concrete CicadaAnalysis subclass (before: a class named Cicada* with setup_parameters / run_analysis; same 40 plugins found, checked). discover_plugins(extra_plugin_dirs) returns the plugins with their source and the ones that could not be loaded (import error, class name already used, entry point that is neither a package nor a plugin) instead of skipping them silently; find_plugin(class_name, module_name=None, extra_plugin_dirs=()) replaces the runner's private _resolve_analysis_class (templates/generate_config_template.py updated). After updating, reinstall cicada-analysis (pip install -e ./cicada_analysis --no-deps) so the entry points are registered.
Documentation site of the three packages, built from the Markdown files of the repos with Zensical (mkdocs.yml, .readthedocs.yaml, docs/_tools/assemble.py; local preview: python docs/_tools/assemble.py then zensical serve). New extra pip install "cicada-analysis[docs]" (zensical, mkdocstrings). Overview pages (docs/index.md, docs/overview/: get started, data sources incl. DANDI, demo, architecture, developers and AI helpers); package pages built from the README sections (install, quick start); API reference pages generated from the code (runner and config files, CicadaAnalysis, the family base classes, the parameter schema, demo). The analysis docs moved to docs/analysis/; the cicada-tools reference is split into one page per subpackage (docs/analysis/cicada_tools/), with draft entries (signature and docstring summary, to review) for the 75 tools used by plugins that were not documented. Install commands on the site use the latest release tag.
Plugin catalogue: a "GUI label" column in every parameter table (the label shown in the GUI next to the YAML name); the parameter rules declared in the code appended to the descriptions that did not state them ("Used when ...", "Shown when a session has ..."); missing rows added (Display activity: data to display, unit quality filter, LFPs, trace downsampling, binarize_activity_to_sum; pairwise similarity: axis and label colours; triple sequence plot: raster and trace series); shared parameter tables collapsible; a "How to read the tables" note.
Tests tests/test_docs_api.py (the functions and parameters written in the cicada-tools reference and the AI helpers exist in the code; every tool used by a plugin is documented) and tests/test_plugin_catalogue.py (every parameter a plugin declares on the demo files has a row in its catalogue table; reported as a DocsDriftWarning, a failure with CICADA_STRICT_DOCS=1).
Parameter rules: set_parameter_rules(..., hide_when_unused=True | "<selector>") hides a parameter of a branch not chosen instead of greying it out (GUI); add_choices_arg_for_gui(..., follow=...) and add_trial_dict_arg_for_gui(..., tables=..., follow=...) give choices following another parameter (choices_follow). Data requirement epochs (epoch groups hidden when a file has no period), data_requirements.epoch_names / event_names (the periods and events offered, without the empty ones), CicadaEventsBase.event_tables.
cicada_tools.connectivity.pairwise_cell_similarity.similarity_pairs(matrix, cells, groups, distances=None) (one row per pair of cells, named after the cell groups of its two cells) and plot_similarity_vs_distance (scatter, or mean and SD per distance bin), used by pairwise similarity.
"Interactive viewing of the figures" (interactive_figures, off by default), a checkbox next to the figure formats of every plugin: save_figure also writes each figure as a .mplfig file (the matplotlib figure, pickled, about 0.3 MB), which the GUI's Interactive viewing tab opens with zoom and pan; in Python, pickle.load. Needs a matplotlib version close to the one that wrote it. Set per run and per thread (core_plots.set_interactive_figures, called by CicadaAnalysis.run_analysis; turned off after headless runs). A figure that cannot be pickled is reported and skipped.
Ephys PSTH: "Plot only 'n' random units" (pick_n_random_units, n_random_units, random_seed): the plots per unit for n units of each session, drawn with a seed among the units with a spike around an event; the group PSTHs still use all the units.
Display activity: "Random seed" (random_seed, default 0) for "Plot only 'n' random cells": the same seed draws the same cells. Before, the cells were drawn with the global, unseeded random state, so each run showed other cells.
Every random step is replayable: a "Random seed" parameter (random_seed, default 0, in every combined YAML) in the plugins that draw anything at random, greyed out when nothing random is on. New in SCE description (surrogates of the SCE threshold), time-correlation graph (same), Malvache assemblies (SCE threshold surrogates, k-means initialisations and their surrogates, test of the assemblies), seq graph (global surrogates and transition-matrix surrogates), activity intervals ratio (rolled rasters) and connectivity graph (pairs drawn for the CCG plots). Intended change: these results were different at each run and are now fixed by the seed (the same seed gives the same results, whatever the number of parallel workers). Plugins that already had a seed (Display activity, ephys PSTH, population / single-cell PSTH, TIFF movie) give identical results. Plot jitter (box / scatter plots, graph layouts including ForceAtlas2 and spring, sequence link jitter, seq graph scatters) uses a fixed seed: the same figure at every run, no parameter.
CicadaAnalysis.add_random_seed_arg_for_gui(used_for, ...), random_generator(**kwargs) and random_generators(n, **kwargs) (one independent generator per random step). cicada_tools functions with a random step take seed (int or np.random.Generator): get_sce_raster_threshold, get_rolling_surrogate_threshold, detect_sce_from_spike_times, detect_sce_rolling, find_best_kmeans, find_significant_kmeans, the Malvache assemblies functions (surrogate_clustering, clusters_on_sce_from_covnorm, statistical_cell_assemblies_def, compute_kmean, compute_and_plot_clusters_raster_kmean_version), find_sequences_using_graph_main; plot functions with jitter take a fixed seed=0 (plot_box_plots, plot_scatter_family, plot_graph, build_jittered_scatter_positions, build_probe_depth_positions, render_spikes(jitter_seed=0)).
Ephys PSTH artifact correction: artifact onsets from any source the sessions have ("Artifacts at": events / epochs / intervals chosen by name, the trials flagged in the trial table as before, or optogenetic stimulations), and the artifact window (artifact_ms_before / artifact_ms_after, default 1 and 4 ms, the previous fixed window). No longer hidden for sessions without a trial table.
CicadaPsthBase.event_onsets (onsets of one source, unfiltered), event_group_times, psth_event_sources, psth_event_names (moved out of add_psth_events_args_for_gui and collect_psth_alignment_times, unchanged), add_psth_reduction_args_for_gui(default_band=...).
Display activity shows LFPs and other extracellular signals (NWB ElectricalSeries: LFP, ECoG, raw): new "Data to display" choice (auto / imaging / spikes / LFPs, listing only the types present in the loaded sessions; auto keeps the previous per-session choice, imaging then spikes, then LFPs), LFP series selector, channel groups by electrode location or typed channel indices, optional zero-phase band-pass (Butterworth). LFPs are read for the time slice only ('Plot slice of time' is required), in µV, and use the trace options (normalization, downsampling, line width, scale). Figures of existing configs are unchanged.
Display activity filters units on the quality label column the file has: Bombcell bc_label, Allen quality, Kilosort ks_label / KSLabel, IBL kilosort2_label, phy group ("Filter units by quality labels of" + "Units to keep"); before, only bc_label was recognised. Unit cell types from the units table (e.g. excitatory / inhibitory) are offered in "Groups of cells".
Display activity draws spike counts and event amplitudes (ROI response series recognised by their values, e.g. Allen DfOverFEvents) as a heatmap of their values, with a colour bar. Activity sum: total spike count for spike counts, none for event amplitudes, or, with the new "binarize activity to sum" option, the cells with a non-zero value. Binary rasters and traces are drawn as before. cicada_tools.imaging.imaging_plots.render_heatmap; plot_raster(display_heatmap=..., heatmap_label=...).
Raster plugins (Cossart descriptive statistics, connectivity, epochs, sequences) and the cells map work from spike counts and event amplitudes too (e.g. Allen DfOverFEvents), recognised by their values, with no new parameter; each conversion is printed:
spike counts and event amplitudes are binarized (1 where the value is above 0); transient frequency and the cells map "colour by firing rate" count the spikes of spike counts instead;
transient duration needs a raster dur (transients over several frames, e.g. Cossart rasters) and skips other series: single-frame rasters, counts and events have no duration;
cells map: before, event amplitudes below 1 were counted as no event, spike counts were counted per run of non-zero frames, and traces gave meaningless counts (now: no colouring, with a message).
cicada_tools.imaging.calcium_signal_processing.activity_to_raster (1 where > 0) and raster_dur_to_onsets (first frame of each transient), which replace the onset loop copied in transient frequency, transient amplitude, pairwise similarity and SCE description (proven identical, dtype included). Base method CicadaAnalysis.binarize_sparse_activity(session, keys, data); check_binary_raster(raster_dur_only=...).
cicada_tools.ephys.ephys_signal_processing.butterworth_filter: band-, high- or low-pass, zero phase; NaN gaps are kept (each finite stretch filtered on its own).
Parameter rules declared by plugins (set_parameter_rules): enabled_if (a parameter used only when another one has a given value) and requires_data (a parameter hidden when no loaded session has the data, e.g. spike or trace options). A parameter that is not used gets its default value, with a warning if it was set to something else in a config. Generated and combined config files show the rule of each parameter in its comment. Plugins can add their own checks (validate_parameters); every run (GUI, run_from_config, replay) checks the parameters first and raises ParameterError listing every problem. Display activity declares its rules (no change in the figures).
Shared PSTH framework: the four PSTH plugins (population, single cell, behavior / DLC, ephys) inherit from a new CicadaPsthBase (base/cicada_psth_base.py) and share their parameters, in the order of the user's choices:
"Events": events / epochs / intervals, trial (or epoch) table with any time column, or optogenetic stimulations; event or trial groups; invalid times and close events left out;
"Groups": epoch groups (events split by the epochs their 'Align on' time falls in) and session groups (by age when every session is under 24 days, else by session);
"Reduction": mean or median over the events of a session, the sessions of a mouse and the mice (median by default), and one band around the line: SD, SEM, 95% CI of the mean, percentiles (25-75 by default) or none, over the units of the plot's last level; a level with a single session (or mouse, unit) keeps the band of the level below;
"Figures": also one plot per session / per mouse; each kind of groups (event, epoch, session, and the plugin's: cell groups, unit groups, data / surrogate) is overlaid with colours or line styles, or drawn in separate figures (default: nothing overlaid, one figure per combination of groups);
"Figure style": text sizes, ticks, colours and the line at 0, applied to every PSTH figure (figures of the chosen width x height, legend outside).
Parameter rules: enabled_if_any=[{...}, {...}] in set_parameter_rules, used when at least one set of conditions holds (on top of enabled_if). The ephys PSTH's "Random seed" is greyed out unless "Plot only 'n' random units" (with plots per unit) or the artifact correction is on.
Parameter rules: Satisfies(test, description) in enabled_if, a test of another parameter's value (e.g. the population PSTH's traces options are greyed out when the selected series is not traces).
cicada_tools: stats.line_and_band, band_functions, array_line_and_band, reduce_psth_level; display.psth_plots.plot_psth_lines, plot_raster_and_psth, plot_trials_superimposed, split_into_separate_figures, common_y_limits, psth_legend_counts, line_table, style_psth_axes, PSTH_FIGURE_STYLE; ephys.psth_utils.unit_psth_table, spikes_around_events; ephys.anatomy_utils.select_units_by_area; imaging.psth_utils.select_cells, active_frame_times, align_rolled_cell; core.split_events_by_epoch_groups, normalize_groups; behavior.behavior_analysis_utils.preprocess_dlc_series. Each new PSTH computation was checked against the previous code on the demo files (identical lines and bands, differences listed below).
CicadaEventsBase (base/cicada_events_base.py), inherited by CicadaPsthBase and Display activity: the trial groups parameters (add_trial_groups_args_for_gui: trial groups and the table's time column) and the readers of the trial groups' times (table_event_times) and of the optogenetic stimulations (opto_event_times), with a message for every group left out.
CicadaGroupsBase (base/cicada_groups_base.py), inherited by CicadaEventsBase (so by the PSTHs and Display activity) and meant for the descriptive statistics: epoch and session groups (add_epoch_groups_arg_for_gui, add_session_groups_arg_for_gui), the group figures (add_group_figure_args_for_gui: one plot per session / mouse, kind overlaid with colours) and their readers (epoch_groups_times, session_groups, group_overlay, group_colors, group_params_errors), moved from CicadaPsthBase (methods without the psth_ prefix; parameters unchanged). Class map in docs/cicada_analysis.md.
Transient frequency works on ephys units too (spikes of each unit over the recording, electrophysiology.get_recording_time_range, unit quality filter), and with epoch groups: the frequency within the epochs of each group (which replaces the 'Epochs' transient frequency' lab plugin). Session, epoch and cell / unit groups (cell types, unit areas or area groups, unit cell types, cell indices); each kind of groups on the x axis, in colour or in separate figures; also one plot per session / per mouse.
CicadaAnalysis.selected_series(roi_response_series) ([(session, keys)] of the sessions with a series selected), selected_series_are_traces (moved from CicadaPsthBase) and add_unit_label_args_for_gui (unit quality filter, shared by Display activity, the ephys PSTH and transient frequency).
cicada_tools.core.valid_intervals(epochs, start, end, invalid_times): the epochs cut to the recording, overlaps merged, minus the invalid times, so that events counted and duration cover the same time.
cicada_tools: from_timestamps_array_to_list(clip=True) cuts an epoch partly within the recording to it instead of leaving it out; plot_psth_lines(share_y=...) (panels showing different quantities, e.g. behavioral series side by side).
Cells map (intended changes): the cells drawn are those of the chosen activity series, numbered by its rows like in the other plugins (the segmentation it refers to; the segmentation selector only for files with a segmentation but no series); one "Colour the cells by" choice (none, cell groups, firing rate, sequence order, cell assemblies, rainbow) replaces five options with a hidden priority, and a chosen mode without its input is refused; shared cell_type_groups / cell_index_groups (the old mixed widget is removed) and "Keep only good cells" (failing cells hidden, numbers kept); "Background image": none, a summary image of the file (suite2p meanImg / max_proj / Vcorr, Allen max projection) or the mean / std of an imaging movie, 2-photon or widefield dF/F (replaces display_img_on_background, imaging_type, ci_movie, bckground_method and the hard-coded widefield F0); "Cells' opacity over the background" (50 % by default; before 20 % for pixel masks); cells drawn as pixel masks (default) or polygons, no longer both; parameters greyed out when unused (background settings, open cv contours with polygons only, each mode's inputs, number color). Base add_background_image_arg_for_gui / background_image, selected_in_a_session, add_segmentation_arg_for_gui(family_widget, ...), add_roi_response_series_arg_for_gui(optional=...); data requirements background_image, segmentation_without_series; is_selected reads 'none' (NOT_SELECTED) as nothing selected. Full-files matrix: 0 crash / 60 sets (was 28), invalid sets 18/18 refused (was 0).
New core plugin Display behavior (core_analysis/cicada_display_behavior_analysis.py): behavioral time series over time, one panel each (any series of the file: DLC, Facemap, speed, licks, pupil...), with the events, trial groups, epochs and optogenetic stimulations as bands (shared with Display activity); time slice, outlier filter, z-score / median normalization, min-max downsampling. cicada_tools.behavior.behavior_analysis_plots.plot_behavior_series. Averages around events stay in the behavior PSTH.
CicadaEventsBase.add_overlay_args_for_gui and overlay_bands: the events (event groups or trial groups), epoch groups and optogenetic stimulations drawn over a display, moved from Display activity to share them with Display behavior (bands identical in 135 cases on the demo files, figures pixel-identical). Display activity's interval_names and epochs_names are renamed event_groups and epoch_groups (as in the other plugins): configs using the old names must be updated. overlay_bands also returns the group names: the bands now have a legend (add_bands_legend) in Display activity (raster) and Display behavior (groups within the time shown); intended change of the Display activity figures with bands. Display activity's time slice: bounds from the recordings of the loaded sessions, default slice of 600 s from their start (before: 0 to 7200 s, default 0 to 600 s, e.g. most of DANDI 000055, 57159 s, out of reach); the description lists each session's recording range (imaging, ephys) and the messages of a session skipped for an empty slice give its recorded range.
Malvache sequences: the speed (run epochs), the position (traveled distance) and the panel below the sequences are chosen among the behavioral time series of the file (speed_series, position_series, display; defaults: the series named like speed / position), instead of get_mouse_speed_info / get_mouse_position_info (same values for the series named like speed / position: proven identical on Allen and Giocomo). The panel can show any series (e.g. lick, piezo) or the run epochs, labelled with its name (before: speed, binary speed or position, labelled 'Speed' / 'Run' / 'Position'); 'none' for no panel. Run settings are greyed out without a speed series, the belt length without a position series.
TIFF movie (intended changes): built on CicadaPsthBase, the frames around events are the PSTH of the movie: the PSTH plugins' events (event / trial groups, optogenetic stimulations, 'Align on') and window (t_before, t_after, baseline correction), epoch groups crossed with the event groups, cell type / index groups (average within the pixels of their cells, masks of the series' rows; replaces movie_by_cell_type). Any imaging movie with frames: one-photon / widefield movies too (e.g. a dF/F movie in processing/ophys), placeholders no longer offered; the movie's own frame times. Every event's clip has the same frames before and after it (before: onset ± baseline_length, the end of the epoch unused although announced); dF/F0 per event before averaging (before: one F0 pooled over the events after shifting by the minimum + 1); single events drawn with random_seed (before: unseeded). Removed: sampling_tiff_method (now movie_mode), use_main_epoch, main_epoch, baseline_length, segmentation, the F0 figure. From the widefield time courses (which stay in the Petersen lab plugins, with their atlas overlay): averages at the session, mouse (mean of its sessions) and session group (mean of its mice) levels (levels; only movies of the same size are averaged together), time-binned image series in png (save_image_series, bin_duration in s over the whole window, image_cmap, image_scale), general_data_dict.npy (session averages, same structure as the widefield time courses' one); new extracted_trials.h5 (save_trials_h5): every event's frames, /mouse/group/session (events, frames, lines, columns), written event by event. The average is a running sum, one event in memory at a time (identical to the mean of the stacked events, proven on the widefield demo; before: 7.3 GB for 55 events of a 512 x 512 movie). cicada_tools: images_handling.time_binned_images, imaging_plots.plot_image_series. cicada_tools.imaging.images_handling: event_clips, normalize_clip, cells_mask. Base add_ci_movie_arg_for_gui offers every imaging movie of each session (before: the last 2-photon one); data requirement imaging_movie.
"Keep only good cells" (keep_good_cells, on by default) in display raster, the population and single-cell PSTHs, transient frequency and amplitude, StPR and connectivity graph: imaging cells failing the quality control of the ROI table (column good_cells, else suite2p iscell) are left out; shown only when a loaded session has such a column, a session without it keeps all its cells. StPR: left out like cells with too few events (zeroed, not valid; event counts kept in the table); population PSTH "average all traces": mean of the good cells. Intended change for files with a quality column (e.g. DANDI 001361, suite2p iscell: 44 of 50 cells of the demo file); keep_good_cells: false gives the previous results. Base add_good_cells_arg_for_gui, good_cells(session, keys, **kwargs), data requirement good_cells; cicada_toolsselect_cells(keep=...).
Demo data shipped with the package: 9 small trimmed copies of real NWB files (Allen Visual Behavior Neuropixels and Visual Coding ophys, IBL Brain Wide Map, DANDI 000044, 000055, 000219, 001361, a Petersen lab file, and a widefield session of DANDI 001847 whose movie is kept only around the trials), 0.9 to 63 MB each, about 119 MB in total. cicada_analysis.demo.names() / demo.path(name) give their paths; sources, licences and SHA-256 are in cicada_analysis/demo/data/DATA_SOURCES.md.
Connectivity graph: "Do a figure with all graphs" crashed (ZeroDivisionError) when no graph was built (every population skipped); it now says so and draws no figure.
Sessions YAML files: a relative session path is resolved against the folder of the YAML file (load_sessions_config, used by run_from_config and the GUI's "Load group"), as in combined configs. Before, it was read from the current folder: loading a demo config as a group of sessions in the GUI loaded nothing, without a message. Intended change: a sessions YAML written with paths relative to the folder the run was started from must now give them relative to the YAML file (or absolute; generate_sessions_config writes absolute paths).
stPR crashed on a Windows console using the cp1252 encoding (UnicodeEncodeError when printing "≥" in the number of cells or units kept); it now prints ">=".
PSTH ephys - electrical series: a filter cutoff or a frequency band starting at 0 Hz crashed in the filter (ValueError); it is now refused before the run with a message ("must be above 0 Hz").
Connectivity graph on imaging positions: files with pixel masks and no imaging movie (e.g. Allen) crashed (UFuncTypeError on the masks); the field of view size now comes from cicada-nwb (get_ci_dimension_from_img_mask, also from pixel masks). The plugin's own fallback is gone: it read each mask's first pixel instead of its extent. Without any size, a message and the cells at their positions, without the frame.
Figure style: the CICADA colormaps (hotcold, cyanmagenta, whitemagenta) chosen as the style's colormap crashed every plot using the default colormap, and the DLC PSTH trajectory ("'hotcold' is not a valid value for cmap"); they are now registered in matplotlib by name, as get_colormap builds them.
Figure style: typed values outside their range are refused before the run, with a message (e.g. "'Figure width (mm)' must be at least 20 (got 0)"); a figure width or panel shape of 0 crashed the figures of every plugin (empty image, NaN sizes, singular transforms). Ranges: figure width at least 20 mm, panel height / width at least 0.1, colour bar width at least 1 mm, opacities 0 to 1, the other sizes (text, lines, ticks, spacing) at least 0. add_field_float_option_for_gui(min_value=, max_value=) (inclusive) for any plugin's typed floats.
Rasters with events without duration crashed when no event line width was given (TypeError ... 'NoneType' in axvline): Cell assemblies (Malvache) on every file, and any other caller of plot_raster or of the ephys traces figure. The line width is now passed to matplotlib only when set (else matplotlib's default, as documented). cicada_tools.display.plot_raster, cicada_tools.ephys.ephys_signal_processing.
Display activity: the text file listing the rows of a raster crashed when the session identifier is a path (e.g. /data/InVivoDA/... in the Giocomo files); its name now uses the cleaned identifier, like the figure next to it.
Raster above PSTH figures (single-cell imaging PSTH, single-unit ephys PSTH): the y labels of the two panels are aligned (they followed each panel's tick label width).
Imaging PSTH (population) with "Baseline-correct PSTHs" and the median over cells of traces (intended change): at each event, each cell's own pre-event mean is now subtracted before the median over the cells, so the PSTH is the median of the cells' changes. Before, the median cell's curve minus its pre-event mean, which hid responses when the cells have different levels (e.g. cells rising while the median cell is flat). Unchanged: the mean over cells of traces, rasters (proportion or count of active cells minus its pre-event mean), and every run without baseline correction (old and new code compared on 120 cases: identical except the median of traces with baseline). cicada_tools.imaging.build_population_psth.
Plugins with events from a table (Display activity, PSTHs, Display behavior...) crashed when building their parameters on a group of sessions that do not all have the same interval tables ('NoneType' object has no attribute 'columns', in CicadaEventsBase.add_trial_groups_args_for_gui; found with cicada-config params on the demo files, open bug 02). A table is offered with the time columns of the sessions that have it.
Results folders given explicitly are created if needed: results_path= of run_from_config / run_from_combined (and --results-path, RESULTS_PATH of the run template), which replaces the results_path of the configs, and result_path of generate_config (cicada-config params --results-path, as the template already did). Before, the run stopped when that folder did not exist. A results_path read from a config must still exist.
templates/generate_config_template.py and run_from_config_template.py: EXTRA_PLUGIN_DIRS (plugins that are not installed). The headless workflow page lists, for each task, the template, the command, the Python call and the GUI way, in that order; it described a plugin file naming rule removed by the plugin registry.
Headless templates and docs: the identifier of a sessions YAML was described as the name used in results and figures; it is not read (files are opened by path, sessions are named by the identifier stored in each NWB file). generate_sessions_yaml.py now writes that NWB identifier (was the file name), generate_config_template.py creates the results folder (a run refuses a missing one), run_from_config_template.py has HASH_INPUTS and no longer promises "exact reproduction".
Combined YAML: with cicada-analysis or cicada-nwb installed from PyPI in a virtual environment inside a git repo (e.g. a .venv in the user's analysis project), the commit of that repo was recorded as the package's git hash. The hash is now only read from a package installed from its own clone.
Plugins with overlaid groups (PSTH plugins, and those with groups on an axis): overlaying a kind of groups none of which is defined (e.g. "Overlaid, with colours" = cell groups while only location groups are set) is refused with a message; before, nothing was overlaid and each group got its own figure without a word.
Malvache assemblies, SCEs on an epoch or with the speed filter: frames outside them were removed first, so SCE frames were positions in the shortened data, read as frames of the recording (wrong SCE times in the figures and the assemblies file), and "All frames" joined the two sides of a removed gap into one SCE. Now the frames are masked, not removed.
Malvache assemblies crashes: speed undefined with the speed filter off (10 / 80 sets of the matrix), "Use_epoch" without a group, keep_only_the_best (IndexError, or KeyError when the best number of clusters was not above its surrogates), more clusters asked than SCEs (now capped at the number of SCEs minus 1), result paths over the Windows limit (the assemblies and k-means text files are now shortened like the figures, the number of clusters kept in the name). The text summary gave the SCE threshold in cells as the percentile.
"All frames" SCEs (Malvache assemblies): a cell active only on the last frame of a multi-frame SCE was not counted in it (intended change of the cells x SCEs matrix). detect_sce_raster (SCEs on traces) never looked at the last window: an SCE can now be found there (and, with the minimal distance, move a close neighbour).
Connectivity graph: the folder given in "Specify a path to load and/or save all the graph files" is created if it does not exist (before, saving the graphs failed).
DLC PSTH, 2-D series (e.g. x / y positions): the trajectory figure drew the plain mean of all the events pooled, without band, whatever the reductions and the band chosen (and no other figure showed these series). Its x(t) and y(t) panels now show the reduced line (events → session → mouse → group, as the other series) with the chosen band; the trajectory panel follows the same lines. The x / y lines are also in the behavior_psth_sessions/mice/groups.csv tables.
Connectivity graph, imaging with "Use anatomical position": the cells were placed with x and y swapped (the graph was the cells map flipped along its diagonal) and the figure stretched to the figure size. The cells are now where the cells map draws them, framed on the whole field of view with equal aspect, the figure taking the field of view's shape (long side: figure width). Ephys layouts unchanged.
Spike-triggered population rate (units): the spikes were binned from t = 0, so a recording starting later counted its silent start in the mean rates; the coupling was inflated by a constant offset (e.g. median 0.30 → 2.46 for a recording starting at 100 s) and the delays pulled towards 0. The spikes are now binned over the session's recording (first to last spike of its units, the same range for every location group and cross-area pair): results no longer depend on the start time. compute_stpr / compute_stpr_cross take t_start / t_stop (default: first / last spike given). Identical results for recordings starting at 0 binned from 0; imaging unchanged.
Spike-triggered population rate: the delay is the centre of mass of each curve rescaled to 0–1 (minimum 0, maximum 1), as stated in the method; before, of the positive part of the curve only, and a curve with no positive part got delay 0 and a dot at 0 in the scatter (now NaN, left out of the scatter, last in the heatmap). Intended change: delays a few ms closer to 0 (at most 4 ms on synthetic data); curves and coupling unchanged. The scatter no longer changes matplotlib's global settings (Arial font and font types were kept for every later figure).
Connectivity graph: every node was drawn in the colour of node 0 (the cell group colours were ignored) when the graph was built in the run, its node ids being numpy integers. Graphs reloaded from a .graphml file were not affected.
Combined configs: a session given by its DANDI address (dandi://..., https://...) was turned into a local path next to the YAML file, so the replay could not open it; addresses are now kept as they are.
Runner, config without analysis_module: CicadaStPRAnalysis and CicadaUnit3DBrain were not found (the file name was guessed from the class name); every plugin is now found by its class name. A config whose analysis_module no longer exists (e.g. a plugin moved to a lab package) falls back to the class name instead of failing.
PSTH windows in frames (new cicada_tools.core.window_to_frames, shared): a window that is a whole number of frames could lose or gain one through float error (100 Hz × 0.29 s = 28.999999999999996 gave 28 frames after the event; 7.5 Hz × 3.6 s gave 28 frames before instead of 27). Fixed in align_array_to_timestamps and build_psth_dataframe (outputs change only at those exact windows: compared on 6.5 M cases). The imaging PSTHs used their own rounding, both sides up: they now use the same rule as every PSTH (at least 'before', not past 'after'). Intended change: the single-cell imaging PSTH no longer draws one frame past 'after' (e.g. 29.97 Hz with 0.1 s after: 2 frames instead of 3); the population imaging PSTH figures are unchanged (that frame was outside its bins; values identical to 2e-15 on 31,200 runs).
gauss_blur_1d / gauss_blur on an even number of samples: the frequency grid was shifted by half a sample, so the filter was not symmetric and a constant signal was not kept (3.0 → 2.92 for 10 samples; a spike lost 1 % of its mass). Odd lengths unchanged (identical outputs); the Malvache sequences, which use it on long traces, change by less than 1e-5 (relative).
cicada-tools reference: signatures and descriptions that no longer matched the code (e.g. compare_two_distributions, combine_population_psth, get_complementary_frames, map_coordinates_to_image, find_paths_in_a_graph), the display functions listed under a wrong module (core_plots), entries of functions no longer in the code (add_area_column, plot_wf_timecourses). Plugin catalogue: with_speed / speed_color removed from Display activity (no longer parameters). AI helper cicada_nwb_api.md: the optogenetic getters are in session.optogenetic; it points to the online API reference for what it does not list.
Seq graph: the real vs surrogate scatters are drawn again (they failed with NameError: jitter_rng since the random seed change); their jitter uses a fixed seed (plot_scatter_seq_real_vs_surrogate(seed=0)), the same figures at every run.
PSTH trial groups: filtering on a True/False column of the trial table (e.g. lick_flag: ['True']) crashed with could not convert string to float: 'True'; the 'True' / 'False' values are now read as booleans.
Install: statsmodels>=0.14,<0.15 declared. statsmodels 0.15.0 no longer provides multipletests in statsmodels.sandbox.stats.multicomp, where scikit-posthocs 0.12 imports it: a fresh install (e.g. the GitLab CI) failed at import scikit_posthocs.
Demo data: the windows of MH031 (890–1010 s, every trial type; 50 units chosen in MOs, SSp, thalamus and midbrain), DANDI 000055 (39370–39490 s, 5 reaches, pose tracked) and DANDI 000044 (17320–17440 s, maze period with position) were moved: the previous ones had no hit, reach or position data around their events, so the behavior and ephys PSTHs had nothing to show. New SHA-256 in DATA_SOURCES.md.
Display activity / Display behavior: epoch groups made of epoch-table labels (epochs: <label>) were offered but not drawn (the bands looked the names up among the interval tables and behavioral epochs only).
Connectivity graph on spikes: "Graph on the cell groups only" ticked without a cell group made a graph of 0 units (crash NetworkXError: Graph has no nodes or edges with ForceAtlas2 or the figure of all graphs, else empty tables and figures); it is now used only when a cell type or cell index group is selected (else ignored, with a warning). A session or location group with fewer than 2 units left by the unit selections is skipped with a message, and no monosynaptic connection found gives a message instead of an empty table.
Pairwise similarity: crash in "one by epoch" mode when the last epoch kept no cell, wrong cell numbers and types in the per-epoch tables, distances paired with the last epoch's matrix, blank figures on deconvolved traces (normalized by a median of 0), and distance bins dropping the pairs closer than one bin and drawn one bin to the right (see the rewrite under "Changed").
xkcd style ("xkcd mode") of Display activity, the raster plots and the cells map stayed on after the figure, so later figures of the session were drawn in xkcd style too; it now ends with its figure (figures themselves unchanged, pixel check).
run_from_config / run_from_combined draw with matplotlib's non-interactive Agg backend, so no window opens during a run (e.g. with an interactive backend in IPython) and runs work without a display; the caller's backend is restored afterwards.
TIFF movie: crashed when no event's clip fitted in the movie (np.stack of nothing); "Use epochs" without epochs stopped every session (now refused before the run); file names from session identifiers that are paths.
Cells map crashes (28 of 60 parameter sets on the full files): "Invert xy coords" on a field of view that is not square (now: the session is skipped with a message when its masks fall outside the field of view); a background asked for on a file without movie (Allen) or with a placeholder movie (Giocomo); polygons around groups of fewer than 3 cells (e.g. firing rate). Sequence order colored the cells 0, 1, 2, ... instead of the typed ones. Widefield dF/F background: one NaN pixel blanked the whole image. The activity array was read once per cell group, the image masks all read to get the size of the field of view.
Plugin audit on the demo files, fixes:
Connectivity graph, connectivity graphs description, hubs, time correlation graph, SCE description and StPR took the wrong data path when nothing was selected in a config (None, the GUI gives ''): spike files were read as imaging and crashed.
Group parameters (epochs, cells groups...) left out of a config were None instead of {} (the GUI value), which crashed several plugins.
Pairwise similarity: pixel_size default was text ("2.0").
The 7 Petersen widefield plugins crashed in check_data on files without Petersen metadata instead of rejecting them.
Movement quantification accepted any file and crashed without facemap data: it now requires facemap series and a trial table. Single mouse behavior plots require the whisker-task trial columns. Ephys PSTH condition defaults are columns that exist (runs on Allen and IBL trial tables).
Cells map and TIFF movie on files whose movie is only a placeholder (e.g. suite2p exports, DANDI 001361): image size taken from dimension, TIFF movie rejects such files; cells map file names with identifiers that are paths.
PSTH (Cossart) crashed building its parameters when a subject age is missing.
SCE description traces: unpacking of detect_sce_traces (now 4 values); no crash when no SCE is found. Behavior quantification: no crash when no behavior epoch is found.
The 15 plugins needing an inferred-activity raster recognised it by the word "raster" in its name and checked only the first session: any series with only 0/1 values is now accepted, and every session is checked.
Demo file cossart_ophys_000219.nwb: the cell types stored per ROI (control / control_description) still listed the 515 ROIs of the original file instead of the 50 kept ones, which made the plugins using cell types crash on it.
15 imaging plugins (pairwise similarity, StPR, both PSTHs, Seq Malvache, connectivity graph and graphs description, hubs, time correlation graph, SCE description, seq graph, triple seq plot, assemblies, activity intervals ratio, transients vs intervals) took the sampling rate of the 2-photon movie, which is missing in many files (Allen, widefield, suite2p exports): they crashed (float * None). They now use the rate of the analysed series, from its own timestamps or rate. Intended change: on files with a movie, the rate can differ slightly from the movie's nominal rate (Cossart demo file: 10.7945 Hz from the frame timestamps, 10.7985 Hz stored for the movie). TIFF movie keeps the movie rate.
A results folder that does not exist (or none) is refused before the run, with a message (GUI, headless and replay); before, the run went on without a results folder and crashed in the plugin, the cause only printed ("results directory not found").
filter_table_with_dict (trial groups of movement quantification): a column holding several values per row (e.g. tags) selected no row; it now keeps the rows where one of the values is allowed. It no longer modifies the dict it is given (same rows as before otherwise, checked on 5000 tables).
Parameter files saved with numpy values (e.g. epoch names from np.unique) could not be read back (!!python/object YAML tags): save_parameters_config writes plain values.
Connectivity graph printed a wrong recording duration (computed from the data instead of the timestamps).
Connectivity graph crashed on imaging data when one cell type was chosen (e.g. only interneurons): the cross-correlograms looped over all cells instead of the kept ones.
Connectivity graph coloured the nodes wrongly when one cell type was chosen together with cell groups: node i got the colour of recorded cell i instead of the i-th kept cell (intended change: figures with this combination differ).
Pairwise similarity, connectivity graph, connectivity graphs description and activity intervals ratio crashed when computing the 'rest' frames (get_complementary_frames was called with its old keyword yin_frames).
Pairwise similarity:
the distribution figures (similarity per pair type, overall and per epoch) were saved empty: sns.catplot ignores the target axes and drew in another figure. They now show the data (new cicada_tools.display.categorical_plot). The same pattern is in 11 other plugins, fixed in their own pass;
"Jacquard" was offered but the computation only knows "Jaccard": every run with it crashed (also the default of twitches activity, lab plugin);
crashed when only one similarity matrix was plotted (one epoch), when the epoch distances table was saved (drop of a row instead of a column), on session identifiers that are paths (Giocomo files), and on empty tables (epoch with no cell pair: now skipped with a message);
the _with_distances.h5 table had no distance column (written from the similarity table); it now holds the same table as the .csv / .xlsx (intended change);
with the first session skipped, the per-epoch tables crashed the next session;
a session whose series has no sampling rate is skipped with a message.
Seq Malvache:
crashed with the PCA split on files without speed (test set never built), with fewer than 2 run epochs (now split on the frames, with a message), on files without position (run distance), with more than 10 PCs (figures of 2 x 5 axes), with no run epoch (figure of the runs, results table), and with one sequence panel plus speed (render_traces_heatmap);
the lag histogram crashed when the lags of the sequence cells were within less than 0.25 s (e.g. widefield areas): it now has at least one bin, with the same bins as before otherwise (checked on 4658 histograms); the uniformity test is not run when the lags span 0.5 s or less (one bin), the title says so (before: a value computed on one bin);
a message when the chosen panel below the sequences (speed, binary speed, position) has no data in the session; a session whose series has no sampling rate is skipped with a message.
PSTH (population):
with 'Build PSTH from ONE main epoch' and no main epoch selected, every event was left out (the message said "analyzing without that restriction"); a main epoch from an interval table was never found (only behavioral epochs were searched), so no event was kept;
crashed with 'Build PSTH from table' but no group of trials (event groups read as trial requirements), on rasters with the default reduction 'median' (not valid for rasters), with a group of cells matching no cell (empty figure), and on PSTH bins without data (NaN axis limits, plot_one_psth);
an epoch is kept when its reference time (start, end or middle) is within the imaging, even if the epoch goes beyond it (before: only epochs entirely within; e.g. the single Allen stimulus epoch of the demo file was always left out). Epochs entirely within give the same PSTH as before (checked on 10000 cases);
a message says why the events of a name are all left out (main epoch, invalid times, reference time outside the imaging); a session whose series has no sampling rate is skipped with a message.
PSTH single cell:
with several groups of epochs, the surrogates of every group were sized and labelled with the trials of the last group: wrong tables and figures, or a crash when the counts differed or the last group had no trial (intended change: surrogates of multi-group runs);
crashed when the declared format did not match the series or the keyword found no series, on rasters stored as floats (summarised as traces), when every trial of a group was left out, with a cell type absent from the session, and on pandas 2 (sort_columns);
same fixes as PSTH for the main epoch (interval tables, no main epoch selected), epochs kept by their reference time, and messages when all events are left out.
Both PSTHs and TIFF movie crashed filtering epochs (cicada_tools.core.period_utils.filter_epoch_timestamps) when there are no invalid times, or when the main epoch is empty or absent from a session. A main epoch absent from a session now keeps no epoch (as an empty one), with a message. Other cases give the same result as before (checked against the previous version on artificial data).
Trial/epoch-table group selectors (add_trial_dict_arg_for_gui, add_epoch_dict_arg_for_gui) no longer crash when a session has no table. They follow the new dict returned by cicada-nwb for epoch tables, and offer every column found in any loaded session (before: only the first session's columns).
Population and single-cell PSTH no longer crash when a table selection matches no trial or epoch.
Display activity (work in progress):
no longer crashes on .strip() of an empty y-axis label, on time slices or table selections in frames without an imaging time axis, on selected cells with spike trains, or on selections beyond the number of cells;
shows cells in their real file order through sorting, random and selected cells (y labels and highlight colours now refer to the file's cell numbers);
imaging data and timestamps stored in non-standard ways are handled (transposed data, frame indices as timestamps, mismatched lengths);
the time slice clips every behavioral series on its own time axis.
Figures whose name contains characters invalid in file names (e.g. session identifiers that are paths) were not saved; save_figure and plot_raster now sanitize file names.
On Windows, figures whose full path exceeded 259 characters (deep results folder + long session identifier) were not saved (FileNotFoundError). The end of the file name is now shortened to fit, with a message (behaviour change: only the name of such files differs).
align_array_on_timestamps_list (Movement quantification, facemap aligned on R+/R- transitions): a first event closer than t_before to the start of the recording gave a truncated window that set the window length, so every complete window was then skipped. Events whose window does not fit in the recording are now skipped. Sessions whose first transition was in the first t_before seconds now keep all their transitions.
Typed cell indices (validate_indices_in_string_format, extract_indices_from_string): an entry such as 1- 3 crashed with IndexError; it is now rejected as invalid.
compute_psth: when t_after - t_before was not a multiple of bin_size, bins were resized to fit the window but counts were still divided by bin_size, so rates were wrong (e.g. 12.5 % too low for a 0.35 s window with 0.1 s bins). Bins are now always bin_size wide and the window is extended to the next whole bin. Behaviour change for such windows: Ephys PSTH (build_peth_dataframe), ephys time-correlation graph, and SCE detection from spike times (detect_sce_rolling: one more step at the end when the recording duration is not a whole number of steps).
Activity-sum panel (count_active_units_per_bin): same binning as compute_psth (bins of exactly the chosen size, window extended to the next whole bin). Behaviour change when the displayed time range is not a whole number of bins: before, bins were slightly stretched to end exactly on the range; now the last bin may extend past it.
PSTH across epochs or sessions (combine_population_psth, Cossart PSTH plugin): values falling in the same time bin were averaged pairwise in order instead of as a mean, negative or zero values (e.g. after baseline subtraction) replaced the bin instead of being averaged, and a time before the first bin edge went into the last bin. Each bin is now the mean of its values; times outside the bin edges are ignored (a time exactly on the last edge stays in the last bin). Behaviour change for plots combining several sessions or epochs.
Single-cell PSTH (align_single_cell_to_epochs): a trial whose window started on the first frame, or needed one frame past the last, was kept but filled with NaN, making the summary NaN at those frames. Such trials are now removed like the other trials too close to the recording edges.
build_psth_dataframe (widefield PSTH, widefield error response): a length-1 list in extra_metadata crashed; it is now used as a constant column.
Connectivity graphs built from an adjacency matrix (build_graph_from_adjacency_matrix, Cossart connectivity graph and connectivity graphs description with Buzsaki monosynaptic connections): for a directed graph, every connection i -> j also added j -> i, and connections from the last cell were only added reversed, so edge directions were lost. The graph now has exactly one edge i -> j per non-zero A[i, j]; undirected graphs are unchanged. Behaviour change: directed graphs, and everything computed from them (in/out degree, hubs, paths).
Sequence detection from graphs (find_paths_in_a_graph): between two paths of the same length, the one with the lowest weight was meant to be extracted first but the first one found was kept. Behaviour change: the order of extraction of equally long sequences, and therefore which sequences are found next.
Ephys time-correlation graph (get_neuron_population_crosscorr_at_events_ephys): neighbouring bins could get the same lag (bin centres rounded half to even: -4, -4, ..., 0, 0, 2, 2), so a unit's preferred lag could be off by one bin and units firing just before and just after the event both got lag 0. Each bin now has its own lag, the left edge of the bin in bins (-n ... n-1).
compute_rolling_binned_activity accepts None spike trains (silent units), as documented; they crashed.
Brain area groups: CS was listed in both Midbrain and Pons and medulla; it is now only in Pons and medulla (no output change: the lookup already used that group).
get_continous_time_periods returns [] for an empty array instead of crashing.
PSTH single cell figures that came up empty or unreadable: raster spikes were drawn as dots of area 0.5 (spike size x 0.01), the x axis was padded by 1 s on each side (-3 to 3 s for a +-2 s window), the superimposed trials started at the white end of the colormap (the first trials invisible), and the font parameters were never registered (always None). Rasters are now drawn as ticks over the window (plot_raster_and_psth), the trials' colours start mid-colormap, and the shared figure style sets the sizes; a message says when a cell has no activity in any trial of a group.
PSTH single cell: the "Also show" series was always used (a series selector always holds a series), so the run was refused whenever it was of the same kind as the first series; it is now used only when "Also show a series of the other kind" is ticked.
Behavior (DLC) PSTH: the figure size, dpi, xkcd mode, colours and font sizes were ignored (the plot function took them but did not apply them); "Display" by epoch did nothing (no epoch parameter); without a colour choice, the event groups were averaged together into one line.
Behavior PSTH and Display activity: the "Filter traces" description announced a Gaussian smoothing that is not done (outliers above 20 SD removed, then NaN interpolated).
from_timestamps_to_frame_epochs(..., as_list=False) returns shape (2, 0) when no epoch is in the recording (was (0,)). No CICADA plugin uses this mode.
find_nearest(..., is_sorted=False) now breaks ties like the sorted mode (the larger of two equally near values; before: the first in the array). No CICADA plugin uses this mode.
Display activity: a time slice containing no spike crashed the activity-sum panel; the session is now skipped with a message (e.g. trial-aligned files whose spike times are relative to an event).
PSTH plugins, groups without events:
a run is refused only when none of the event (or trial) groups has a time in the loaded sessions; before, one trial group without a value in the chosen column refused the whole run;
a group without events in one session is skipped for that session, with a message (before: silently);
two trial groups with the same name are refused (the second replaced the first, one PSTH per name);
a run where no group is left after filtering (invalid times, close events, epoch groups, recording edges) is refused with the same message in the four PSTHs (check_psth_has_events); the behavior and single-cell PSTHs saved nothing without a clear message.
PSTH figures: the figure has the chosen width x height (before: square panels fitting in it, e.g. 4 x 8 inches for 15 x 8 asked), also for the raster and trials figures (intended change: figure layout).
PSTH single cell and ephys PSTH: a cell (unit) with no activity (spike) in any window gets no figure, with a message (before: an empty raster above a flat line); its results stay in the tables.
Behavior (DLC) PSTH:
lines and bands of each level as the other PSTHs (line_and_band, then reduce_psth_level): a level made of a single line (one session, one mouse) keeps the band of the level below (before: no band). Lines unchanged (checked on 132 artificial cases); the sessions, mice and groups tables are saved (behavior_psth_sessions/mice/groups.csv);
behavioral series side by side, each with its own y axis; per-session and per-mouse figures in per_session / per_mouse;
a series with no value (all NaN) is skipped with a message (before: empty figures); a group whose windows are all out of the recording says why, with the time ranges (e.g. event times stored in frames, not seconds).
Display activity:
discrete events (behavioral events, or trial groups at a time column of the table) and epochs (interval tables, behavioral epochs) are separate overlays and can be combined; before, the trial table replaced the epochs;
an epoch partly within the recording (e.g. a block starting before the imaging) is shown within it, with a message; before, it was left out silently;
epoch bands are drawn under the traces and spikes (they dimmed them), events stay above;
an event or epoch name absent or empty in a session is reported; trials without a time in the chosen column are left out, not their whole group;
behavioral series read in their unit (conversion, offset) with the cicada-nwb getters; a series with several columns says only the first is shown; default colour of the 1st series visible on the black background;
optogenetic stimulations as an epoch overlay ('Show the optogenetic stimulations');
'Dashed line under each trace' crashed with traces (the line's end was the whole time array); the line is now the baseline of each (shifted) trace, over the recording;
the behavioral series panel stayed empty for rasters (spikes, binary) without the activity sum: it was drawn for traces only;
a behavioral series with no value (all NaN) is not shown, with a message; a series skipped no longer gives its name to the next one;
'Plot only selected cells' with a selection that is not cell indices (e.g. the 'enter selected cells' choice) is refused before the run (before: no cell left, nothing saved); a time slice whose start is not before its end is refused for every kind of data (before: LFPs only, else ignored);
scale bars: their thickness no longer depends on the number of cells or the window (x bar 0.1 data unit thick, y bar 1 s wide); a bar longer than what is shown (time window, signal range) is not drawn, with a message (before: it ran out of the axes). The y bar's unit is the one typed, else none (before: 'dF/F' by default, also on LFPs). cicada_tools.display.core_plots.add_scale_bar.
Display activity: the time axis showed large clock times as an offset (e.g. ticks 0, 10, 20 and "+1.72e4" in the corner) for every kind of data; the ticks now show the real times. The LFP figure title and the y scale bar's help showed "µV" for µV.
Demo file allen_ecephys_563497: the eye-tracking corneal_reflection_tracking had 1349 timestamps for 7200 samples (the trimming cut the timestamps it shares with eye_tracking twice). Re-trimmed: the eye-tracking series share the eye_tracking timestamps as in the original file; all other data unchanged (new SHA-256 in DATA_SOURCES.md).
Results folder not given (results_path empty or unset, in the GUI, a config or a script): results go to <Downloads folder>/cicada/results, created if needed, next to the DANDI downloads; the folder is printed. Before, the run stopped asking for a folder (GUI) or for the mandatory results_path (headless). A folder given that does not exist is still refused. The demo figure configs leave it empty (results_path: '', was ., the folder the replay was run from), so their replays save in the Downloads folder.
Replay git mismatch warning (config recorded at another commit of a CICADA package): always given, with the number of .py files of the package changed since, 0 included. Before, no warning when no .py file had changed. The demo figure configs are made one commit before the release tag (a commit cannot record its own hash), so replaying them from a clone at the tag reports the same version, another commit and 0 .py files changed; installed from PyPI (no git), only the version is compared.
Demo figure config A1_graph: connectivity time window of 100 ms (time_delay, was 500 ms); its reference numbers rewritten.
Small transients detection, "Rolling window" method (Malvache assemblies, SCEs on traces; detect_small_transients): about 100 times faster (the medians and inter-quartile ranges of every frame's window at once, instead of one frame at a time): 196 s to 2 s on the widefield demo file. Results identical (checked on 13 artificial cases covering every option and on the widefield demo file).
Faster figures with panels of a fixed width (single-cell PSTH: one figure per cell, and the other PSTH figures): the size of a figure starts from the previous fit of the same figure type, 3 to 4 times fewer redraws (a single-cell run on the Allen demo file went past 5 minutes, most of it fitting figure sizes). Intended change: sizes may differ by up to 0.1 mm from the earlier fit (checked on 151 figures of 3 demo files).
Replay compares commits on the package's code: a different commit whose .py files are the same (e.g. the release commit that adds the demo configs) no longer warns; when files differ, the warning gives their number. A commit not in the clone (or a PyPI install) gives the warning as before.
Replay compares the Python version on major.minor: a patch release (3.11.9 vs 3.11.15) no longer warns.
Malvache assemblies: "Maximal number of clusters (k-means)" (max_ncl) is 10 by default (was 18): the k-means surrogates over every number of clusters from 2 to 18 took several minutes on small recordings. Intended change: runs with the default try 2 to 10 clusters; saved configs keep their value.
GUI labels say "subject" instead of "mouse": "Over the sessions of a subject", "Over the subjects" (Reduction of the PSTH plugins) and "Also one plot per subject" (Figures). The parameter names (mouse_reduction_fct, one_plot_per_mouse), file names and table columns are unchanged.
PSTH imaging - single neurons: the y label of the traces figures is the name of the series in the NWB file (with the normalization if any, e.g. "dff (z-score)"), instead of "raw fluorescence" / "df/f" / "z-score" whatever the series. With one panel, the PSTH line figures put their axis labels next to the panel (they were at the figure edges, which made the panel smaller than in the other figures).
Display behavior: when every panel has the same unit (e.g. z-score), one y label for the whole figure instead of one per panel (on short panels they overlapped).
Behavior PSTH (DLC): the trajectory figure's axes are labelled "x" and "y", the series named by the title (before: " x" and " y", which overlapped on the short time panels); the y labels aligned.
PSTH imaging, single cell: every figure of a cell has panels of the same size, 60 % of the figure width; each figure's width follows its labels (before: panels of different sizes, e.g. the trials figure larger than the summary because of their different labels). New core_plots.fit_panel_width(fig, panel_width, n_cols=1) and the panel_width_mm key of the PSTH plots' figure style (plot_psth_lines, plot_trials_superimposed, plot_raster_and_psth; None: the width kept, as before).
Display behavior: "Show the titles" hides only the figure's title (the session); the name of each series stays above its panel (before: hidden too).
Cells map: the colour bar's label is no longer cut at the right edge (e.g. presentation preset, one column); the figure is widened to fit the bar, its ticks and label, the map keeping its size.
Display activity: the scale bar labels take the figure style's font (before: always a monospace font), and the scale bar thickness is the one set, in pt, on both bars (before: changed by the layout, e.g. 1.2 pt for the time bar and 2.1 pt for the cells bar at 2 pt).
Core plugin names and GUI families homogenized: the four PSTHs in one family "PSTH" (before: "Epochs", "Ephys", "Behavior"), named PSTH imaging - population (was Population level PSTH), PSTH imaging - single neurons (Single-cell level PSTH), PSTH ephys - units (PSTH per mouse) and PSTH behavior (Deep Lab Cut PSTH); in "Display": Display calcium imaging movie (Write CI movie to tiff) and Display calcium imaging cell maps (Cells map); Sequences detection (Malvache's sequences detection) and Neuronal assemblies detection (Malvache's assemblies detection). Short descriptions rewritten (shorter; the two empty ones of the transients filled), long descriptions written for the cells map, TIFF movie and sequences and rewritten for Display activity. The results folders take the new names. Catalogue and API pages updated.
stPR figures: square heatmaps (each heatmap of the grid too) and a square scatter panel, the figure height fitted to them; the scatter is titled with the session and its legend lists the cell groups ("all cells" and each group in its colour; before: one entry, the session); two-line axis labels. Reference lines (zero, events) take the text colour of the light and dark themes, the reference line colour only with the custom theme (before: the default theme's colour, white lines on a white background with the light theme).
Connectivity graph: white background by default (light theme; before: black), dark grey nodes over lighter grey edges; the legend of the figure with all graphs in the nodes' colour (before: always cornflower blue).
stPR and connectivity graph: the dots of the stPR scatter plot and the nodes and edges of the graphs are grey by default (before: white, invisible on a light background); labels "Dot colour of the scatter plot (cells in no group)", "Node colour (cells in no group)", "Edge colour" (before: "Default dot / curve color", "Figure face color", "Figure edge color"; same parameter names).
seq Malvache: speed_line_color is labelled "Line colour of the panel below the sequences" (before: "Color of the panel below the sequences", though it colours the line, not the panel).
Every core plugin draws in the figure style (default preset: 89 mm wide, 7 pt text, 0.8 pt lines, square panels, Okabe-Ito colours), its figures within the figure width (constrained layout, no crop on saving). Figures that ignored the figure options before now follow them: the speed, position and PCA figures of seq Malvache (before: fixed sizes, 23 pt labels, pdf only), the cross-correlograms of the connectivity graph (before: 8 x 3.5 inches, the first format only), the stPR scatter and heatmaps (before: fixed sizes and fonts, 300 dpi), the cell assemblies figures (before: 20 x 14 inches, the figure's dpi), the image series of the TIFF movie (before: png at 150 dpi), the similarity matrices (before: 300 dpi whatever the dpi chosen).
save_figure keeps the layout of a figure that has one (e.g. constrained) instead of forcing a tight layout.
Malvache assemblies (now a core plugin, reworked): the series' kind decides the detection (rasters: Peaks / All frames on the surrogate threshold, spike counts and event amplitudes binarized; traces: small transients), each detection's parameters greyed out for the other kind; files without a raster or traces refused with a message; immobility from any behavioral time series (speed_series, at or below speed_threshold; frames without a speed value left out, while the old rolling-window detection on traces kept them: intended change); the standard epoch groups, one analysis per group in its own folder; min_ncl above max_ncl refused; the threshold in percentage of cells up to 100 % (was capped at 30); session skipped with a message when its series has no sampling rate; keep_only_the_best keeps the best number of clusters among those above their surrogates.
Display behavior: the legends are right of the panels, not over the data. When every panel has the same columns (e.g. x, y), a single legend for the figure, with the events / epochs; else each panel its own, the events / epochs with the top panel's.
Display behavior: the columns of a position series are named x, y (z) in the legend (needs cicada-nwb's get_behavioral_time_series_column_names); other series with several columns keep "column 0, 1…".
Display activity: no box around the behavioral time series panel, only its value axis (left; right for a second series) and the time axis.
Display activity: the legend of the events / epochs bands is drawn right of the raster or traces (no frame, in the axes label colour) instead of over their top right corner; with a heatmap, below its colour bar.
Connectivity graph figures: no frame, axis ticks or tick labels around the nodes (the axes are pixel or layout coordinates, not informative).
cicada-tools reference (docs/analysis/cicada_tools/): every page has one section per module (###.`), every function its signature, description, parameter table and return value; the drafted entries are in their module's section, tagged "(draft)", instead of a separate list at the end. Fixed:BREWER_COLORS(23 colours, Paired then RdYlBu, not 9 Set1), the'hotcold'colormap (cyan–blue–violet → dark grey → red–yellow, not blue–white–red); addedepoch_reference, and the constructors ofTiffMovieView,CellsCoord,CellAssembliesStructand the main parameters ofrender_spikes.tests/test_docs_api.py` now reads the signature under each function heading, so the documented parameters are really checked against the code (before: no heading matched, nothing was checked).
Every figure is saved through save_figure: the direct fig.savefig calls of the Cossart plugins (descriptive statistics, epochs, connectivity graph and graphs description, seq graph, seq Malvache) and of cicada_tools (distribution plots, raster plots, cells map, connectivity utils, Malvache assemblies, behavior plots) now go through it, so their figures get interactive figure files too. Figure files are byte-identical (checked for each kind of call in PNG, PDF, SVG, EPS and TIFF). Intended changes: their file names are made safe (safe_file_name: a trailing _ left when there is no timestamp is dropped, e.g. graph_density_.pdf → graph_density.pdf, ..._cell_assemblies_only_sca_.pdf → ..._cell_assemblies_only_sca.pdf; repeated _ are collapsed; characters invalid in file names become _; names over 150 characters are cut), and their PDF / SVG text is editable (fonts embedded as TrueType, SVG text kept as text), as was already the case once any save_figure had run in the session.
save_figure closes only the figure it saved (before: every open figure, including those of another analysis running at the same time).
Behavior (DLC) PSTH: refused before the run, with the data and event ranges of each session, when no event of the chosen groups keeps its window within the selected behavioral series (after the invalid times, close events and epoch groups), or when the selected series have no value; before, the run went through every session and ended with "No event left to align on". CicadaPsthBase.events_within_data_errors(data_ranges, **kwargs), for the other PSTHs to use with their data range.
Epoch groups (every plugin on CicadaGroupsBase: PSTHs, Display activity, Display behavior, TIFF movie, transient frequency and amplitude, connectivity graph, pairwise similarity): the trial table, stored with the intervals, is no longer offered as an epoch (it is an event source: filtering trial-table events by trials left out every event on a trial's start or stop); the epoch table is offered by its labels (e.g. PREEpoch / MazeEpoch on DANDI 000044, the stimulus blocks drifting_gratings, natural_movie_one... on Allen ophys) instead of as one whole table.
filter_events_based_on_epochs vectorized (identical results, ~25x faster on spike-like data), for spike trains.
Figure helpers in one place, cicada_tools.display.core_plots: FIGURE_STYLE, style_axes (was psth_plots.PSTH_FIGURE_STYLE / style_psth_axes; applies only the style keys given, figure background included) and split_into_separate_figures (moved from psth_plots). set_figure_style is merged into style_axes (behaviour plots: the bottom axis line is now drawn in the axis colour, before hidden), and so is configure_axes (style_axes(ax, xlim=, ylim=, xlabel=, ylabel=, despine=True)); the v_line default is now False. Unused plot_violin_distribution and plot_multiple_violin_distributions removed (use categorical_plot).
Cell-type and area choices of the cells map, Display activity and the imaging PSTHs are sorted (before: a random order at each start).
Behavior PSTH: the trajectory figure shows the trajectory on top and x(t), y(t) below on one time axis (before: small side panels with time on their short side); colour bar in the figure style. The trajectory panel is square and as wide as the x(t) and y(t) panels, its axes aligned with theirs (before: narrowed by the colour bar and the legend); the figure height fitted to it.
StPR: the spike raster is built one unit at a time (identical results): memory no longer grows with the number of units (a full 1 ms raster of 105 units over 10 h needed ~15 GB).
A warning when a run saves nothing (usually an empty selection), and on Windows when the results folder path is long enough to exceed the 259-character limit (see README, "Windows: enable long paths").
cicada-analysis no longer imports cicada-nwb constants or modules: plugins and the base class ask the session (e.g. is_sparse_activity), versions and git hashes for the config files are found without importing cicada-nwb, and only the runner imports NWBSession to open files (its unused fallback for a missing cicada-nwb is removed).
Cells map: the figure size follows a new "Figure size (inches, long side)" parameter and the dpi (before: 20 pixels per image pixel, e.g. 10,000 px wide for a 500-pixel field of view).
Display activity: much lower memory use (float32 data, display mode decided on a sample, activity-sum panel computed without a units x bins matrix); optional min/max downsampling of traces for display (downsample_traces, downsampling_factor); a warning when a spike raster is estimated to need more than half of the computer's RAM (estimate from measurements: ~1.3 GB + 0.155 GB per million spikes).
Activity-sum panel (render_spike_activity_sum): memory proportional to the number of bins only (count_active_units_per_bin).
Spike rasters (render_spikes, spike shape |) with more than 500,000 spikes to draw are drawn as one line per unit instead of one segment per spike: ~40x faster and ~6x less memory (1 M spikes: 203 s / 1.35 GB -> 4.6 s / 0.21 GB). Spike positions and widths are unchanged and identical when zooming in; at full view, pixels where many spikes overlap are slightly less bright (behaviour change, only above the threshold). Smaller rasters are drawn exactly as before. DANDI 000044 full session (13.3 M spikes) now draws in ~36 s / 3.3 GB instead of exceeding 6 GB.
Display activity: the Bombcell unit filter (bc_label: good, mua) is a unit_labels parameter shown only when the column exists.
Files other than figures are saved only with "Plotted data and intermediate files" (save_figure_data, see Added), which replaces the options "Save the tables" (save_table: transient frequency, transient amplitude, pairwise similarity), "Save graph" (save_graphs, connectivity graph; "Do a figure with all graphs" now needs the new option, it reads the saved graphs) and save_psth_data (ephys PSTH, psth_units.csv). Unticked: figures only, also in the plugins that always saved their tables (PSTHs, stPR, sequences...); the TIFF movie, whose result is a movie, is refused before the run. Configs with the old options replay with a warning (option ignored), with the new option's default. Files no longer written (they repeated another one): Display activity raster_<session>_rows.txt (_rows.csv), the sequences' PC_cell_order/*_sorted_cells.txt and PC_shifts/*_cell_shifts.txt (columns of PC_tables/*_table.csv), the .gexf copy of each connectivity graph (.graphml kept) and the connectivity graph's monosynaptic table in the run folder (kept in Connectivity_graphs/). compute_and_plot_clusters_raster_kmean_version(save_files=True): False writes no .txt.
No timestamp in figure file names: the run's results folder already carries one. The option 'Timestamp in filename' (with_timestamp_in_file_name, on by default in Display activity) and CicadaAnalysis.add_with_timestamp_in_filename_arg_for_gui are removed (a lab plugin calling it must drop the call); the connectivity graph, which always added one, no longer does; plot_raster and the distribution plots of cicada_tools.display take with_timestamp_in_file_name=False by default (before: True). Configs with with_timestamp_in_file_name replay with a warning (parameter ignored).
Tables are saved as .csv only, no longer as .xlsx (writing xlsx took about 35 times longer): transient frequency, transient amplitude and pairwise similarity (their .csv were already saved, unchanged), and Malvache sequences, whose tables were xlsx only: PC_tables/<id>_sequences_PC<n>_table.csv, order_in_runs/PC_<n>_order_in_runs.csv, correlations_table.csv, correlations_table_summary1.csv / summary2.csv, without the pandas row numbers. The summaries have one header row: the group columns, then <value>_mean, <value>_median, <value>_size (before: two header rows, and the statistics in an order that could change between runs). New tool cicada_tools.core.flat_columns. In Excel on a locale with a comma decimal separator (e.g. French), open a .csv with Data > From Text/CSV.
docs/example_configs/ removed (configs of July 2026, with old plugin names and parameters, on example files from a Google Drive folder): the configs to start from are the demo configs shipped with the package, on the demo files (README, Demo page of the docs).
Demo file petersen_widefield_001847.nwb re-trimmed on another window of the same DANDI session, 1310.6–1430.6 s (was 140–260 s): a switch from the rewarded to the non-rewarded context, with 5 whisker trials (2 correct hits in the rewarded context, 2 correct misses and 1 error in the non-rewarded one); the widefield movie is kept around these 5 trials (150 frames, was 360 around 12 trials). 32.6 MB (was 63.2 MB): the cicada-analysis wheel stays under PyPI's 100 MB limit. Analyses of this demo file at the old times must use the new window.
Packaging for PyPI: cicada-nwb is required by version range (cicada-nwb>=0.4.0.dev0,<0.5, >=0.4,<0.5 from the 0.4.0 release) instead of a GitLab URL; dependencies no longer used are removed (neo, elephant, quantities, imageio, tables: a package that uses them declares them); the cicada_analysis_update command is removed (update with pip install -U cicada-analysis, or git pull in a clone). Contributors install the clones from the bottom up: cicada-nwb, then cicada-analysis (the README gives the commands).
Display activity and Display behavior: the events, trial groups, epochs and stimulations drawn over the display take two new Figure style options, side by side: "Event line width (pt)" (event_line_width, the lines of events without duration; 0.8 pt, presentation 1.5 pt, typed with custom) and "Opacity of the events, epochs and stimulations (0-1)" (event_opacity, default 0.5). They replace intervals_alpha_color (Events group, 1–100; no alias, configs to update, the demo and example configs are). Before, the event lines took the line width of the traces. Same figures with the defaults. Each plugin names what its options draw: Display activity "Line width of the traces and behavioral series (pt)", "Colormap of the heatmaps (spike counts, event amplitudes)", "Heatmap colour bar width (mm)"; Display behavior "Line width of the series (pt)" (add_figure_style_args_for_gui(labels=...), figure element event_overlay). Tools: plot_raster(span_line_width=...), render_spike_activity_sum(span_line_width=...), plot_behavior_series(event_line_width=...).
Display activity: lfp_filter is a filter type, none / band-pass / high-pass / low-pass (default none), instead of a bool whose missing side was a cutoff set to 0 or empty. The low cutoff is used by band-pass and high-pass, the high cutoff by band-pass and low-pass, and a used cutoff is required. Configs with lfp_filter: True must give the type.
Figure parameters replaced by the figure style (no aliases; configs to update, the demo and example configs are): every plugin: width_fig, height_fig, xkcd_mode (now figure_width_mm, panel_aspect, xkcd); the PSTH plugins: ticks_labels_size, axis_label_size, axis_label_pad, legend_police_size, ticks_length, ticks_width, color_v_line_width, background_color, color_ticks, axes_label_color, axes_border_color, color_v_line; Display activity: traces_lw (the line width), background_color, x_ticks_labels_color, y_ticks_labels_color, axes_label_color (the theme), raster_y_axis_label_size, x_axis_ticks_label_size, y_axis_ticks_label_size (the axis and tick label sizes); Display behavior: line_width, font_size; Cells map: figure_size (the width), background_color, cell_numbers_size (the annotation size); connectivity graph: background_color (node_size moves to the Figure style group); seq Malvache: background_color, sequences_cmap (the colormap), speed_width, axis_labels_size, ticks_label_size, ticks_label_color, axis_color; stPR: background_color, axes_label_color, fig_edgecolor (the reference line colour); TIFF movie: image_cmap (the colormap); the group distributions (transient frequency, amplitude, pairwise similarity): background_color, axis_color, labels_color, font_size. Imaging PSTH: with_timestamp_in_file_name removed (never used). CicadaPsthBase.add_psth_figure_style_args_for_gui and psth_figure_style removed; add_image_format_package_for_gui and add_dpi_arg_for_gui kept for the lab plugins until they move. Tool signatures: plot_behavior_series(line_width=None, legend_position=...) (no font_size), plot_similarity_vs_distance(marker_size=None, ...) (no colour or font arguments), CellsCoord.plot_cells_map(figure_width_inches=...) (was figure_size_inches, the long side).
Malvache assemblies parameters: method is "Peaks" or "All frames" (the "Traces" value is gone: traces are detected as such when the selected series is traces); use_speed → speed_series; epochs_to_use / epochs_names → epoch_groups (the 'rest' derived from the other epochs is gone: use the speed series). Configs with the old parameters must be updated.
Malvache assemblies: the small transients method "Arnaud" (transient_method) is renamed "Rolling window", what it does (a frame above the median of a rolling window, Malvache et al. 2016; still the default). Configs with "Arnaud" must be updated.
Lab code moved to the lab packages: the Cossart lab plugins (14) to cicada-cossart and the Petersen lab plugins (11) to cicada-petersen, installed next to cicada-analysis and found through their entry points; Cossart_lab_plugins/ and Petersen_lab_plugins/ are gone. The 11 core plugins that were in those folders are now in core_analysis/ (list in the plugin catalogue). Configs of moved plugins whose analysis_module names the old folder still run (the class is found by name).
Two core plugins renamed, without alias: CicadaPsthAnalysis (cicada_psth_analysis) is now CicadaImagingPsth (core_analysis/cicada_imaging_psth.py), CicadaPsthSingleCellAnalysis is now CicadaImagingPsthSingleCell (cicada_imaging_psth_single_cell.py): configs and combined YAMLs naming the old classes must use the new names.
Lab-only cicada_tools functions moved to the lab packages (67), unchanged: the Petersen behavior task plots and tables (behavior_analysis_plots, behavior_analysis_utils), the CCF 3D plots (ephys/ccf_plot_utils), widefield/widefield_petersen_lab_utils (the cicada_tools.widefield package is gone) to cicada-petersen; sequences/utils_sequences, cell_assemblies/utils_cell_assemblies and the time-correlation graph functions of connectivity/connectivity_utils to cicada-cossart. Generic functions used only by lab plugins stay. Their reference entries moved to the lab packages' docs/tools.md, the lab plugin sections of the catalogue to their docs/plugins.md. The brain_atlas extra (iblatlas, plotly) moved to cicada-petersen.
cicada_tools.imaging.imaging_time_axis(timestamps, n_frames, imaging_rate=None, verbose=False) takes the imaging rate instead of the session (cicada_tools reads no NWB); callers pass session.calcium_imaging.get_ci_movie_sampling_rate(). Outputs and messages identical (checked on every ROI series of the synthetic and demo files).
Event and epoch tables, configs to update: the event source "trial table" is now "table" with a "Table to use" (events_table: every interval table with columns to pick rows by, the trial table first and by default: trials, epochs, stimulus presentations such as Allen ophys drifting_gratings from nwb.stimulus); the trial groups and "Align on" (align_column) follow the chosen table. Configs with events_from: trial table must use events_from: table and set events_table. The epoch table is no longer used as a "trial table" when a file has none. "Events / epochs / intervals" lists the behavioral events and epochs, the interval tables without columns to filter (e.g. invalid_times, ECoG reaches) and the epoch labels (epochs: <label>, to align on an epoch's start or end); epoch groups list the same periods. Epoch labels are named epochs: <label> (before: <label>). Empty event series and periods are left out of the lists (e.g. the demo MH031 window has no whisker hit). The ephys PSTH's artifacts flagged in a table use the trial table; the DLC PSTH accepts any interval table. Trial-table alignment times identical to the previous code on the demo files (1,308 cases).
Pairwise similarity rewritten on CicadaGroupsBase, configs to update:
the data used follows the selected series (traces as traces, binary rasters as they are, spike counts and event amplitudes binarized): data_to_correlate removed, and with it the 'Raster' option (onsets of a raster dur);
"Normalization of the traces" (none, median, z-score; default none), used only when every selected series is traces: before, traces were always normalized by their median;
one matrix per session and epoch group (frames within the group's epochs, without the invalid times; none defined: the whole recording): epochs_to_use, epochs_names, specify_twitches_duration, twitches_duration removed, no automatic 'rest' group;
session, cell type and cell index groups, "Keep only good cells"; each pair belongs to the pair of cell groups of its two cells (cell_group, e.g. PV or PV / Pyr, replaces PairType built from the cell types), cells numbered by the rows of the series in every epoch group;
cells without activity in an epoch group left out of its matrix, with a message; distance figure per session and epoch group, from the masks of the series' own segmentation;
figures, statistics and saving of the group base (x axis, colours, kind of plot, stats per mouse or session, save table / figure, style): representation choices, x_axis / hue values, palettes, font_type, fontweight, fig_facecolor, fig_facecolor2, fig_edgecolor, do_plots removed. Tables: one row per pair, summaries per session and per mouse (csv, and xlsx when under Excel's row limit).
Ephys PSTH defaults: mean over the events, units, sessions and mice (was median, which gives 0 for sparse spike counts: 97 % of the units flat on two full sessions) and SEM band (was percentiles 25-75). The other PSTHs keep median and percentiles.
Ephys PSTH baseline (baseline correction, z-score): the whole time before the event (t_before); baseline_duration (default 0.1 s) is removed, and ignored in older configs.
Ephys PSTH artifact correction: the replacing spikes are drawn with random_seed (before: unseeded, so two runs differed), and their rate is measured over the time before the event up to the artifact window (before: 200 ms; identical with t_before = 0.2 s). With the trial table and the default window, onsets and window are unchanged (checked on MH031 and AB131).
No more plt.show() in cicada_tools: the show_raster argument of plot_raster and the show_fig arguments of render_traces_heatmap, CellAssembliesStruct.plot_cell_assemblies and show_co_var_first_matrix are removed (every caller passed False). Removed the unused plot_t_sne_results and load_t_sne_from_b_soid, which only showed a window.
Cell groups (CicadaGroupsBase): two widgets, one kind of groups "cell groups" (was "cell type groups"; table column cell_group, was cell_type_group):
"Cell type groups" (cell_type_groups) hold cell types only, and are shown only when a loaded file has cell types (new data requirement cell_types); typed indices in it are no longer read;
new "Cell index groups" (cell_index_groups, new parameter type add_index_groups_for_gui, GUI widget with a name, the indices checked as typed, a colour): cells typed as '3 1 7-9', kept in the typed order; imaging: rows of the activity array, units: unit ids (select_cells(..., ids=); before: positions among the units kept). Used by transient frequency, transient amplitude, the population, single-cell and ephys PSTH and Display activity (population and single-cell PSTH: tables and figures identical with cell type groups, checked on the Cossart demo); the single-cell PSTH's default cells '0-9' are a cell index group; configs typing indices in cell_type_groups must move them to cell_index_groups;
every typed index group is checked before the run ('3 1 x' is not a list of indices).
Display activity cell selection: "Cell index groups" replace "Plot only selected cells" (plot_selected_cells, selected_cells_plot): only these cells, in the typed order (before: put back in display order), each group in its colour; used when no cell type or location group is set (greyed out otherwise). "n random cells" picks n cells in each cell type or location group (or among all the cells), in display order (before: n among all, in random order), greyed out with cell index groups. Units show their unit ids on the y axis (before: their position among the units kept).
StPR, same coupling, delay and valid units as before on the full Cossart, Allen and Petersen files:
data: units with the file's quality labels (before: 'good' only, hard-coded); imaging spike counts kept as counts (before: binarized); files without events: peaks detected from the chosen traces (before: refused); a file with events must have them selected;
cell groups (cell types, typed cells) colour the dots of the scatter (before: cells whose type name contained 'interneuron', 'pv', 'sst'... in red); location groups from the shared widget (areas and area groups), one population each; removed: cell_to_use (never used), location_col_name;
the tables of units hold their unit ids (before: positions); files of sessions whose identifier is a path are saved in the results folder (before: at that path, e.g. C:\data\...);
checked before the run: a data source per session, low-pass cutoffs below half the sampling rate; computation errors are no longer caught and printed as a skipped session.
Transient frequency and amplitude statistics ("Compare the groups on the x axis") compare the means of the mice (new stats_level, default mouse, or session) instead of the cells, which counted every cell as an independent sample; a group with fewer than 2 mice (sessions) is not compared, with a message (stats.compare_groups(units=...)).
Transient amplitude: no table of every transient any more (13.8 million rows on a spike counts file, beyond the Excel limit); transient_amplitudes (one row per cell: mean amplitude, number of transients) and its summaries are kept.
The 4 PSTHs share their window (CicadaPsthBase.add_psth_window_args_for_gui, checks psth_window_params_errors): t_before and t_after in seconds (default 0.75 s and 1.5 s) and baseline_correction (the mean of the time before the event subtracted), replacing psth_range_before / psth_range_after (ms, 10 s each) and baseline_subtraction (population PSTH), psth_range (single cell, symmetric, ms; no baseline before), psth_start / psth_stop (ms, 250 ms each) and subtract_baseline (DLC PSTH, on by default before: off now). The ephys PSTH keeps bin_size, baseline_duration and zscore (its window defaults were 0.1 s and 0.2 s). Same tables and figures with the same window (population, single cell, DLC). Single cell: a window before / after the event and the baseline correction of the traces (each trial, surrogates too) are new; cicada_tools.imaging.psth_utils.align_single_cell_to_epochs / align_rolled_cell take a window (before, after) (one value: symmetric, as before) and baseline_subtraction.
Population and single-cell PSTH, traces normalization (traces_normalization, traces_norm) as in Display activity: choices None (was raw), median (was df/f), z-score; the default is now None (before: df/f, i.e. median), so traces PSTHs run with default parameters are no longer normalized.
Connectivity graph (Cossart lab), cell and location groups (graphs identical on the full Cossart and Petersen files):
node colours from the cell groups (cell_type_groups, cell_index_groups), then the location groups, then the default colour; units get their cell types from the units table and typed indices are unit ids; color_by_cell_type (automatic colours per type) is removed: define cell type groups;
cell_to_use (graph on one cell type, imaging only) is replaced by only_cell_groups (graph on the cells of the cell groups, imaging and units);
location_groups from the shared widget (areas and area groups); location_col_name (one graph per value of a column, which crashed on area names with a '/', e.g. 'RSPv2/3') is replaced by one_graph_per_location;
units filtered on the file's quality labels (unit_label_column, unit_labels; before: 'good' only, hard-coded);
removed, never used: sort_raster_by_cell_type, axis_color, axes_label_color, ticks_labels_color, font_type, fontweight; graph file names use 'all_cells' / 'cell_groups' instead of the cell type.
Parameter rules: a parameter not used (greyed out or hidden) counts as its default value in the conditions of the others (before: every parameter depending on it was disabled too). Checked on every plugin x demo file: the only changes are the ones above.
Cell type and location groups, two kinds of groups that each cell / unit belongs to on its own (crossed in the figures only if asked; configs from earlier versions must be updated):
parameters renamed in every plugin: cells_groups -> cell_type_groups (cell types or typed indices); cells_location (Display activity, connectivity graph and graphs description, hubs, StPR, SCE description, time correlation graph) and units_groups (ephys PSTH) -> location_groups (areas and area groups of the units); kinds "cell groups" / "unit groups" -> "cell type groups" / "location groups" (in overlay_color, overlay_style, x_axis); table columns cell_group / unit_group -> cell_type_group / location_group (transient frequency, ephys PSTH);
shared widgets CicadaGroupsBase.add_cell_types_groups_arg_for_gui (cell types of the ROI and units tables, typed indices) and add_area_groups_arg_for_gui (areas and area groups, units only), used by transient frequency, ephys PSTH and Display activity; the other plugins switch in their own pass;
transient frequency: cell type groups and location groups (before: one list mixing cell types and areas, a unit in a group if it matched any item); one row per cell / unit and each combination of its groups; a cell listed twice in a group counted once;
ephys PSTH: new kind "cell type groups" (unit cell types, or unit indices among the units kept), crossed with the location groups; figures without cell type groups are unchanged (checked pixel by pixel); psth_legend_counts(group_columns=...) (was group_column);
Display activity: location groups with area groups; a unit in several location groups is shown once, in its first group (before: once per group); new rows_grouped_by (with both kinds: rows sorted and coloured by the groups of this kind, then sorted by the other kind); "Sort raster cells' groups" is used only without location groups. Figures with one kind of groups are unchanged (checked pixel by pixel); with both kinds, before, the cell type colours replaced the location colours and the rows stayed in location order.
Display activity colours (in "raster_config"): traces and LFPs use the default colour unless "Use brewer colors for traces / LFPs" is ticked (default now off: before, one brewer colour per trace); the default colour (spikes_color) is shown for every kind of data (spikes, rasters, traces, LFPs). Spike shape and size are shown only when a loaded session has spike times or a binary raster (new data requirement spike_raster).
Transient amplitude rewritten on CicadaGroupsBase, as transient frequency:
the traces are chosen ("Traces to measure on") instead of found by the name 'trace' / 'raw': Allen files (DfOverFEvents + DfOverF) and other labs' files run (before: refused); files without events (binary raster, spike counts, event amplitudes) are accepted, their transients detected from the traces (detect_transients), and a file that has events must have them selected;
the old "dF/F" normalization divided cell i by the median over the cells of frame i (wrong values in every table saved so far); now a choice: none (default, traces as they are), median (per cell, dF/F) or z-score;
amplitude of raster dur and spike counts unchanged (trace at the peak minus trace at the onset, checked identical on artificial data); pure rasters and event amplitudes: trace at the peak (before: peak minus onset, near 0 for single-frame events); negative amplitudes are NaN, left out of the means and plots (before: 0), with a warning above 5 %;
session, epoch (transients whose onset is within the epochs, without the invalid times) and cell type groups, with the figures of transient frequency; tables: one row per transient, one per cell (mean amplitude, number of transients) and summaries per session and per mouse; removed: cell_to_use, do_not_show_unclassified, hue, palettes, cell_types_to_compare, fig_facecolor, font_type, fontweight; white background and font size 20 by default.
Transient frequency: files without events (binary raster, spike counts, event amplitudes) and without spike times are accepted; their transients are the peaks detected from the chosen traces (new traces_series, detect_transients); a file that has events must have them selected (before: any session without a selected series fell back to its units). Frequencies from events unchanged (tables identical).
Transient frequency and amplitude share their figure parameters and figures: CicadaGroupsBase.add_group_distribution_args_for_gui, group_distribution_params_errors, plot_group_distributions; cicada_tools.display.distribution_plots.plot_groups, stats.compare_groups, stats.summarize_by_levels, imaging.calcium_signal_processing.transient_amplitudes (transient frequency: figures, tables and printed statistics identical before / after).
categorical_plot: strip jitter and bar bootstrap seeded (CATEGORICAL_PLOT_SEED), so a figure is the same at every run (before: strip plots changed at each run); numpy's global random state is put back.
Transient frequency rewritten (same per-cell frequencies, checked on Cossart and Allen files): parameters x_axis / hue over table columns, cell_to_use, do_not_show_unclassified, cell_type_groups, cell_types_to_compare, palettes, fig_facecolor, font_type, fontweight removed (groups instead); only binary series, spike counts and event amplitudes are offered (before: any series, e.g. dF/F, counted as transients); one table per cell / unit and epoch group with summaries per session and per mouse (new columns); white background and font size 20 by default; invalid times left out by time (before: by nearest frame).
PSTH plugins on the shared framework (E5; configs from earlier versions must be updated, unknown parameters are ignored with a warning):
all four: 'Main epoch' (do_psth_on_one_epoch, psth_period) is replaced by the epoch groups, which keep an event when its 'Align on' time is within an epoch of the group (before: the whole event); tables are CSV (before: xlsx / h5); the line at 0 is 2 wide by default;
population PSTH: without session groups, all the sessions are pooled (before: one group per session), with "Also one plot per session / per mouse"; a mouse level is added (events -> sessions of a mouse -> mice); the band is one choice (before: a lower and an upper bound function at the event and at the session levels); cell groups and data / surrogate are kinds of groups (overlaid or separate) instead of fixed figure families; surrogates are seeded (random_seed, same computation otherwise); tables psth_sessions.csv, psth_mice.csv, psth_groups.csv; removed: session_color_choice, session_default_color, one_fig_by_group_and_epoch, plot_style_option, average_fig, the four border switches, low/high_percentile_surrogate (only used by a threshold that was never drawn); surrogate_color now colours the surrogate lines;
PSTH single cell: every cell group is used (before: the first one only), no group means every cell (cells_to_include removed); events split by event group and epoch group; line and band from the shared reduction (median, 25-75 by default, as before); surrogates seeded (random_seed, same computation), the raster threshold now saved too; other_series needs also_show_other_series: true; all 9 figures kept, drawn with the shared plots; removed: prctl_color, spike shape / size / colour, show_raster, show_traces, with_activity_sum, activity_sum_plot_color, tick options, axis / label / background colours (shared figure style);
behavior (DLC) PSTH: no seaborn, figures from the computed lines and bands (identical to seaborn's for mean / median with SD, SEM or percentiles; the 95% CI is the seeded bootstrap CI of the mean); median by default at each level (before: mean), percentiles band (before: SD); "Plot(s) to do" and the per-mouse plot choice are replaced by "Also one plot per session / per mouse" (the plot of all sessions is always made); to_display is replaced by the overlay choices; the series are filtered once per session (before: once per event group and epoch, same values); the CSV has a session_group column, epoch is 'all' without epoch groups (before: 'not_defined'), bodypart comes second (values unchanged); white figures with black text by default (before: seaborn white, the requested black was ignored);
ephys PSTH: any event, epoch, interval, table time column or optogenetic stimulation (before: trial start_time, every trial), with invalid times and the close-events filter; trial groups from the "Events" box replace the condition columns (condition_rows/cols/colors, trial_outcome, split_trials_into_halves removed); units filtered on the file's quality label column (before: bc_label only); new kind "unit groups" (areas and area groups) replaces the fixed per-area figures (plot_per_area removed); the mouse-groups file is removed (session groups instead); levels events -> units -> sessions -> mice (new); the SEM band uses the sample SD (ddof 1, sqrt(n / (n - 1)) wider than before); "Baseline-correct" is greyed out with z-score (z-scoring subtracts the baseline itself) and a baseline longer than the time before the event is refused; "Also one plot per unit" (raster above the PSTH) replaces plot_per_neuron; psth_units.csv replaces psth_data.h5; group_order (unused) removed. Unit PSTHs and the population line are identical to before (checked on the Petersen demo file);
cicada_tools functions no plugin uses any more are removed: plot_one_psth, plot_several_psth, plot_population_psth, plot_average_across_sessions, plot_unit_raster_psth, plot_psth_dlc, build_peth_dataframe, save_peth_hdf5, load_mouse_groups, split_trials_into_halves; build_dlc_psth_df only aligns (no filtering, no label columns: the caller adds them).
Display activity, events and epochs: use_trial_table is replaced by events_from ('events' or 'trial table'); interval_names holds behavioral events only, epochs and intervals are in the new epochs_names; the trial groups use align_column (default start_time). Configs from earlier versions must be updated.
Display activity: units are filtered on good + mua by default whatever the quality label column (before: only for Bombcell bc_label). Files with Allen quality or IBL kilosort2_label labels now leave out their 'noise' units by default; select all labels in "Units to keep" to show them.
Connectivity graph, connectivity graphs description, hubs and StPR (Cossart lab) keep only 'good' units on files with Allen quality or IBL kilosort2_label labels too (before: only on Bombcell bc_label files, all units otherwise).
Display activity trace_normalization choices are now None (default), median (was df/f), z-score; raw is now None. Configs from 0.3.2 using df/f or raw must be updated.
Pairwise similarity:
no segmentation parameter: distances between cells use the segmentation the analysed series refers to (before: any segmentation could be chosen, and a different one crashed or gave wrong distances). The key is ignored in old configs;
similarity_metric "Jacquard" is now "Jaccard"; configs using "Jacquard" must be updated;
combinations that gave meaningless results are refused with a message instead of running: Hamming / Jaccard on traces (were silently replaced by Pearson), Raster / Rasterdur on a traces series (no events: Rasterdur used the raw traces, Raster counted values >= 1 as events), a pixel size of 0 with distances, nothing saved (neither tables nor figures).
Seq Malvache:
runs on calcium traces only (raw, dF/F or deconvolved rates): the series selector lists only those, sessions without traces are rejected, and a config naming a raster, spike counts or event series is refused (before: rasters and events were run through the PCA);
'manual_sequences' without the csv folder is refused (before: silently switched to run auto-detection); a PCA split with 100 % training is refused (no test part).
PSTH (population):
no work_on_traces parameter: traces or raster is given by the kind of the selected series (spike counts and event amplitudes are binarized, with a message). Before, a traces series with work_on_traces off was read as a raster;
cell_reduction_fct offers median / mean for traces and proportion / count (new) for rasters, according to the loaded series; a reduction that does not fit a session's series, and sessions mixing traces and rasters, are refused;
refused with a message instead of saving nothing or crashing: no group of events (or of trials with 'Build PSTH from table'), 'one main epoch' without a main epoch; event groups are used only when 'Build PSTH from table' is off, trial groups only when it is on;
sessions with no behavioral events, epochs or trial / epoch table are rejected (nothing to align on).
cicada_tools: align_array_on_timestamps_list and align_array_from_table_stim_time are removed; align_array_to_timestamps is the single alignment on event times (new options time_axis=0 for time-first data such as behavioral series, drop_outside=True to leave out events whose window leaves the recording). Movement quantification (lab plugin) uses it: up to ~40 % more trials kept (the old functions dropped, without a message, every event whose window got one frame more or less than the first one), each window centred on the frame nearest to the event, one frame longer (intended change; checked on artificial data).
PSTH single cell:
data_type, has_traces, trace_keyword, has_raster, raster_keyword are replaced by an optional second series, other_series ("Also show", of the other kind); traces or raster is given by the kind of each series (spike counts and event amplitudes are binarized). Configs using the old parameters must select the series instead;
the custom list of cells starts with the group '0-9' (before: empty, and the default run stopped); refused with a message: no epochs or trial groups, 'one main epoch' without one, 'custom list' or 'cell-type group' without a group, a custom list that is not cell indices, and a second series of the same kind;
sessions with nothing to align on (no events, epochs, trial table or optogenetic stimulation) are rejected.
tests/: known-answer unit tests of cicada_tools, one test file per module (tests/cicada_tools/<subpackage>/test_<module>.py).
add_roi_response_series_arg_for_gui(kinds=...): the series selector lists only the series of the given kinds of activity (e.g. ("traces",)). Parameter rules can require "speed", "position", "traces" or "raster_like" (requires_data). from_timestamps_to_frame_epochs(keep_if="start" | "end" | "middle") keeps epochs whose reference time is within the frames (default "whole": unchanged). add_choices_for_groups_for_gui(default_value=...): groups given at start (shown by cicada-gui from its next version). cicada_tools.behavior.behavior_analysis_utils.table_time_columns(table): the columns of a trial / epoch table holding times. cicada_tools.display.categorical_plot (axes-level seaborn categorical plots, see Pairwise similarity).
New cicada_stpr_analysis plugin (Connectivity): spike-triggered population rate (leader/follower coupling and delay), with cross-area and combined-heatmap support.
New cicada_tools.clustering submodule (find_best_kmeans, find_significant_kmeans, plot_silhouettes), shared by the Malvache cell-assembly detection.
SCE ("Christmas tree") triggered-average analysis adapted to ephys spike data, shared with the existing imaging pipeline.
New cicada_tools.ephys.psth_utils: spike-train PSTH/PETH utilities (compute_psth, build_peth_dataframe, rolling binned activity, causal half-Gaussian smoothing).
unit_3d_brain plugin: coarse area grouping and graceful handling when ffmpeg is unavailable for the rotation movie.
ephys_psth plugin: xkcd display mode and a single-unit raster panel alongside the population PSTH.
run_from_config() now accepts a list of parameter config files (this was already added late in 0.3.1 but undocumented until now — see docs/headless_workflow.md).
Refactored the Malvache cell-assembly detection (cicada_tools.cell_assemblies) to delegate to the shared clustering and pairwise_cell_similarity modules; removed dead code paths and fixed a stale reordering bug.
More generic handling of differing ephys location column names (ccf_atlas_acronym / ccf_acronym / location) across ephys plugins and PSTH utilities, with a fallback fetch from the electrodes table when absent from the units table.
cicada_tools.core.event_alignment — event-alignment functions (align_array_to_events, align_array_to_timestamps, etc.) moved from imaging to core as their canonical home.
run_from_config() now accepts a list of parameter config files, enabling sequential analysis runs while keeping NWB sessions loaded between runs — avoids repeated file reloading and significantly speeds up multi-analysis workflows. Also improved handling of session-keyed parameter files.