Skip to content

Changelog

[Unreleased]

Changed (breaking)

  • NWBSession.get_timestamps_range() covers the whole session: from the earliest to the latest time of every TimeSeries (acquisition, processing, stimulus) and of the units' spikes, read without loading the timestamps. It looked only at the CI movie frames (ci_frames) and the behavior movies (cam_*), returned (None, 0) when there were none, and its end was never below 0; it now returns None when nothing in the file has times.

Improved

  • calcium_imaging.get_roi_response_serie_kind reads the first 2 minutes of a series (CLASSIFY_SECONDS, all cells, at most CLASSIFY_MAX_FRAMES = 5000 frames; 5000 frames when the rate is unknown) instead of always 5000 frames: less data read when the plugins check a streamed file, e.g. from DANDI (reading 71 s -> 43 s on 4 DANDI files). Same kinds on 629 series of 86 local and DANDI files.
  • The PyPI page links to the documentation, the repository and the issues ([project.urls]).
  • New helpers in submodules.time_series_utils: time_series_time_range (first and last time of a TimeSeries, without loading its timestamps), stored_timestamps and time_axis (a series of channels or ROIs stored transposed), shared with the electrophysiology getters (same values).

Fixed

  • Kind of activity of a ROI response series (calcium_imaging.get_roi_response_serie_kind, classify_activity): deconvolved rates (suite2p spks, OASIS deconvolved activity) with 90 to 92 % zeros were read as event amplitudes and are now traces: continuous values need at least 95 % zeros (EVENTS_MIN_ZERO_FRACTION, was 90 %), integer counts still 90 % (COUNTS_MIN_ZERO_FRACTION). The non-zero stretches of counts and events may last up to 0.1 s (median, SPARSE_MAX_MEDIAN_STRETCH_S) from the series' sampling rate, instead of 3 frames whatever the rate (still 3 frames when the rate is unknown), so counts imaged at a high rate are no longer read as traces. A series of only zeros (in the frames read) is a trace, no longer a pure raster. classify_activity(data, rate=None) takes the sampling rate. Checked on 629 series of 86 local and DANDI files: 15 deconvolved series and 2 all-zero ones change kind, no other.
  • Epoch and trial tables: when every start_time is an integer, the values are read as frame indices only if they go beyond the session duration. That duration now comes from time_series_time_range, the same reading of each TimeSeries as NWBSession.get_timestamps_range. A sampling period stored as the rate, data stored (channels, time) and timestamps linked to a series outside the file are now read right. Before, they gave a wrong duration, and so could read the table in the wrong unit. The session end is now the time of the last sample, rounded up to the second for the comparison: an integer start up to that second is read as seconds.
  • time_series_time_range: a NaN or non-numeric starting_time is taken as 0, as in time_series_timestamps. Before, the range was NaN, and NWBSession.get_timestamps_range could return NaN or a wrong start or end.
  • Movies stored outside the NWB file (external_file of an ImageSeries: imaging movies in get_ci_movies and get_ci_movies_sample, widefield raw acquisitions in get_widefield_raw_acquisition_path, behavior movies in get_behavior_movies): a relative path, which the NWB format takes as relative to the .nwb file, was returned as stored and so opened relative to the current folder; it is now joined to the folder of the .nwb file. Absolute paths (drive, UNC, POSIX) are returned as stored, and so are the paths of a file not read locally (streamed from DANDI). Same return types as before. New helper submodules.time_series_utils.external_file_paths.

[0.4.0] - 2026-11-12

Changed (breaking)

  • DANDI support is installed with cicada-nwb: remfile, requests and platformdirs are regular dependencies, the dandi extra is gone (pip install "cicada-nwb[dandi]" no longer exists; plain cicada-nwb gives the same). The GUI's DANDI menus work in every install.
  • The Cossart and Petersen lab submodules left cicada-nwb: session.cossart and session.petersen now come from the lab packages cicada-cossart (https://gitlab.com/cossartlab/cicada_cossart) and cicada-petersen (https://github.com/LSENS-BMI-EPFL/cicada_petersen), which declare them under the entry-point group cicada_nwb.lab_submodules; their methods are unchanged and documented in the lab READMEs. Without the lab package, session.<lab> raises an AttributeError naming the package to install. cicada_nwb.lab_submodules keeps the base class NWBLabSubmodule.

Added

  • electrophysiology.get_electrical_series_electrode_groups(keys): the electrode group of each channel of an electrical series (electrodes table group_name, else the group's name), e.g. the shanks of a probe or the grids and strips of ECoG.
  • NWBSession.find_files(location, recursive=False): the NWB files of a local .nwb file or folder (optionally recursive; a folder named .nwb, e.g. Zarr, is not listed) or of a DANDI file, dandiset or folder of it, sorted, without opening them, as sessions YAML entries {identifier, path}: the identifier stored in local files (read with h5py; the file name if unreadable, with a warning), the file name for DANDI files, whose path is the version-pinned address. Used by cicada-config sessions and the GUI-free templates of cicada-analysis.
  • Command cicada-dandi: cicada-dandi ls <dandiset or folder address> lists the NWB files with their size and version-pinned address; cicada-dandi cache clear deletes the stream chunk cache (downloads are kept). Module cicada_nwb.cli. After updating, reinstall cicada-nwb (pip install -e ./cicada_nwb --no-deps) so the command is installed.
  • Behavioral events also come from ndx-events Events (ndx-events 0.2, e.g. DANDI 000055 ReachEvents), read through the extension spec cached in the file (ndx-events need not be installed): behavior.get_behavioral_events_names, get_behavioral_events_times and get_event_times. The EventsTable of ndx-events 0.4 is not read.
  • session.source of a local file also gives its size in bytes, as for DANDI files (recorded in the combined YAML).
  • behavior.get_behavioral_time_series_column_names(name): 'x', 'y' ('z') for a position (SpatialSeries of 2 or 3 columns), None otherwise (one column, columns without a name, unknown series). Reads the data's shape only.
  • Version check of lab packages: a lab package whose declared range of cicada-nwb / cicada-analysis / cicada-gui does not match the installed versions is not loaded (its submodule is not imported); the reason is given by NWBSession.lab_submodule_errors() and in a warning (e.g. "needs cicada-nwb>=0.4,<0.5, installed 0.3.2"). Requirements without a range and those of extras are not checked. New dependency packaging.
  • Lab submodules are loaded from the installed packages through the entry-point group cicada_nwb.lab_submodules, so a lab package (e.g. cicada-petersen) adds session.<lab> without changing cicada-nwb; Cossart and Petersen are declared in this package's pyproject.toml until they move to their lab packages. Replaces the scan of the lab_submodules/ folder, which hid every loading error: a lab submodule that cannot be loaded (import error, not an NWBLabSubmodule, entry point not named as its name, name already used by the session) is left out with a warning and listed by NWBSession.lab_submodule_errors(). session.<lab> for a lab not installed raises an AttributeError saying which package to install. Grouping factors are attribute paths from the session ("petersen.session_type", "metadata.session_description"), read by the new NWBSession.group_value(path); the 7 Cossart / Petersen relay methods of NWBSession (session_type(), belt_type(), ...) are removed (use session.petersen.session_type(), ...). cicada_nwb.lab_submodules exports only NWBLabSubmodule. Template and docs describe the entry-point declaration. After updating, reinstall cicada-nwb (pip install -e ./cicada_nwb --no-deps) so the entry points are registered.
  • Documentation site pages (built from cicada-analysis): docs/index.md, install.md, quickstart.md (from README sections) and changelog.md, and an API reference with one page per module generated from the code (docs/api/). The user guide (docs/cicada_nwb.md) is a short tutorial; the API reference is the full list. The README has a "What's inside" section, and its quick start was corrected: get_roi_response_serie_keys does not exist (a series is addressed by [module, interface, series name] from get_roi_response_series()), there is no session.subject (subject_id, age, genotype are properties of the session), widefield acquisitions come from get_wf_acquisition_dict(). In the user guide, get_behavioral_time_series_data / _timestamps take serie_name. Test tests/test_docs_api.py: the methods and arguments used in the README and the user guide exist.
  • DANDI files opened directly: NWBSession accepts dandi://<dandiset>[@<version>]/<path>, dandiarchive.org file links, DANDI API asset links and any .nwb URL. Modes stream (default; remfile with a disk cache of the chunks read), download (one-asset download into a download folder, sha256 checked, reused at the next run; streams instead when the file is bigger than the free disk space or 10 GB) and auto (download up to 1 GB): NWBSession(ref, dandi_mode=...). Once opened, session.data_ref is the version-pinned address (so sessions and combined YAMLs record the dandiset version) and session.source gives dandiset, version, asset id, size, sha256, mode and local copy ({"kind": "local", "path": ...} for local files). Stream chunks: CICADA_DANDI_CHUNKS, else the user cache folder. Embargoed dandisets: DANDI_API_KEY. Uses the DANDI REST API directly (no dandi package); new extra pip install "cicada-nwb[dandi]" (remfile, requests, platformdirs). Module cicada_nwb.dandi. Local files are opened exactly as before.
  • Listing a dandiset without opening its files: dandi.parse_dandiset_reference (000728, DANDI:000728/<version>, dandi://000728[@<version>][/<folder>], dandiarchive.org dandiset or folder links, DANDI DOIs), dandi.dandiset_info (name, version, number of files, size) and dandi.list_assets(dandiset, version, path_prefix) (NWB files with size and version-pinned address, all pages). A dandi:// address not ending in .nwb is a folder, not a file.
  • Download folder of DANDI files: NWBSession(ref, dandi_mode='download', dandi_download_dir=...) (dandi.open_nwb(download_folder=...)), as <folder>/<dandiset>/<version>/<path>; default: <user Downloads folder>/cicada (dandi.download_dir()), with a message giving the local copy. Stream chunks stay in the cache folder.
  • dandi.clear_stream_cache() deletes the stream chunk cache (kept until then; downloads untouched), returns the bytes freed; dandi.stream_cache_dir() (the environment variable CICADA_DANDI_CHUNKS moves it), dandi.download_dir() (default folder of downloads).
  • behavior.get_intervals_names(include_trials=True, epoch_labels=False): include_trials=False leaves out the trial table (stored in nwb.intervals too), epoch_labels=True replaces the epoch table by its labels, named <epoch table>: <label> (e.g. epochs: PREEpoch, epochs: drifting_gratings, distinct from a table of the same name): the values of its selectable columns, or for a table without one (e.g. a single epoch) its short text values (up to EPOCH_LABEL_MAX_LENGTH = 50 characters). Defaults unchanged. behavior.get_event_times(name) also resolves these labels (the start / stop of the epochs with that label), after the interval tables, behavioral epochs and events.
  • Interval tables of nwb.stimulus (TimeIntervals, e.g. Allen ophys drifting_gratings: one row per grating presentation with its orientation and temporal frequency) are read like those of nwb.intervals: listed by get_intervals_names (stimulus/<name> if the name is already used), read by get_interval_as_data_frame, get_interval_times, get_interval_original_frames and get_event_times. Results for the tables of nwb.intervals unchanged (checked on the demo files and the full Allen ophys file). get_interval_as_data_frame leaves out the columns referencing other NWB objects (timeseries), as the trial and epoch table getters.
  • Any interval table by name: get_table_choices(name) (columns to select its rows, with the trial / epoch tables' default excluded columns), get_table_timestamps(name, requirements_dict, use_stop_time=False) (times of the matching rows and their unit), get_trial_table_name(). The trial and epoch table getters keep their signatures and results (proven identical on the demo files).
  • Electrical series (LFP, ECoG, raw) getters in electrophysiology: get_electrical_series() (in acquisition and processing modules, stored directly or in LFP / FilteredEphys containers), get_electrical_series_data(keys, start, stop, channels) (reads only the time window and channels asked for, in volts: conversion, per-channel channel_conversion and offset applied; channels x time), get_electrical_series_rate, get_electrical_series_time_range, get_electrical_series_channels (electrodes table rows of the channels), get_electrical_series_locations, has_electrical_series.
  • electrophysiology.get_recording_time_range(): (start, end) of the ephys recording, from the earliest to the latest time of the electrical series and the spikes (e.g. for firing rates over the recording). calcium_imaging.is_traces(keys), next to the other questions on a series' kind.
  • Synthetic test files ecephys_raw (int16 in acquisition, conversion + offset + channel_conversion) and ecephys_lfp (LFP with timestamps, electrode subset) in cicada_nwb.testing.synthetic_nwb.
  • Unit quality labels beyond Bombcell: UNIT_LABEL_COLUMNS (bc_label, quality, ks_label, KSLabel, kilosort2_label, group), electrophysiology.get_unit_label_columns() (columns with no value left out). get_unit_labels, get_spike_times and get_spiketimes_group take label_col=None = the first label column of the file (was always bc_label); the spike getters take return_ids=True to also return the unit ids.
  • Unit cell types: get_unit_cell_types(), get_unit_cell_type_map() (cell type column of the units table, same search as for imaging ROIs). Synthetic file units_quality.
  • Kind of activity of a ROI response series, from its values: calcium_imaging.classify_activity, get_roi_response_serie_kind, get_roi_response_series_by_kind (one kind or a tuple of kinds). Kinds: raster dur (only 0/1, transients over several frames, e.g. Cossart rasters: durations known); pure raster (only 0/1, single active frames); spike counts (non-negative integers, >= 90 % zeros, short stretches); event amplitudes (same but continuous, e.g. Allen L0 events); traces (anything else, including inferred rates such as suite2p deconvolved). Classified on the first 5000 frames, cached per series. Question methods so callers need not know the kind names: is_raster_dur, is_binary_raster, is_spike_counts, is_event_amplitudes, is_sparse_activity (counts or events), and get_raster_dur_series, get_binary_raster_series, get_sparse_activity_series, get_raster_like_series (binary rasters, counts and events).
  • electrophysiology.get_known_unit_label_columns(): the quality label columns looked for, in order of preference.
  • calcium_imaging.has_ci_movie_frames(): whether a CI movie has actual frames (some files keep only a placeholder series).
  • The behavioral time series getters (get_behavioral_time_series_names, get_behavioral_time_series, ..._data, ..._timestamps) also find the series of PupilTracking, EyeTracking and Position containers (before: BehavioralTimeSeries only); get_behavioral_time_series_data(name, in_unit=True) returns data * conversion + offset (the NWB rule; default: raw data, as before).
  • behavior.get_behavioral_time_series_unit(name): the unit of a behavioral time series (e.g. 'cm/s').
  • behavior.get_event_times(name): times (2, n) of an interval table, behavioral epoch or behavioral event of that name, looked up in that order (the three existing getters).
  • session.optogenetic (NWBOptogenetic, existing but not attached before): has_opto_stimulation(), get_opto_stimulation_time_serie() (moved from behavior, unchanged; session.behavior.get_opto_stimulation_time_serie no longer exists) and get_opto_stimulation_times(): the stimulation periods (2, n), from the runs of non-zero values.
  • calcium_imaging.get_rrs_segmentation(keys): the plane segmentation a ROI response series refers to (its rois link), as [module, image segmentation, plane segmentation], the format of get_pixel_mask.
  • Cell quality control of imaging ROIs: calcium_imaging.get_good_cells(keys) (boolean, one value per row of the series, from the first CELL_QUALITY_COLUMNS column of the ROI table: good_cells, then suite2p iscell (its first value); NaN counts as False; None without such a column) and has_good_cells(keys). Synthetic ophys files have snr and good_cells columns.
  • calcium_imaging.get_pixel_mask(roi_serie_keys=...): the masks of the cells of an ROI response series (the table rows it refers to, in its order), instead of every ROI of a segmentation. Image masks are converted one row at a time (outputs identical to before on all local files).
  • calcium_imaging.get_summary_images() (2D images of the Images containers, e.g. suite2p Backgrounds_0 meanImg / max_proj / Vcorr, Allen SummaryImages, in the processing modules and in acquisition; nested dict like get_segmentations) and get_summary_image(keys).
  • CI movies are also found in the processing modules (e.g. the widefield dF/F movie dff0, a OnePhotonSeries in processing/ophys), by every movie getter (contains_ci_movie, has_ci_movie_frames, get_ci_movies, get_ci_movies_sample, rate, dimension, number of frames, ...). has_ci_movie_frames and get_ci_movies_sample take ci_movie_name. get_imaging_movie_names(): the imaging movies with frames (TwoPhotonSeries, OnePhotonSeries; not behavior cameras, not placeholders). get_ci_movie_time_stamps(ci_movie_name=...): the times of that movie's frames (stored, or from its rate and starting time); without a name, 'ci_frames' as before. Checked on all local files: only the widefield file's outputs change (its movie is found).
  • submodules/table_utils.py: table helpers shared by submodules (find_cell_type_column, decode_values, moved from calcium_imaging, unchanged); submodules no longer need to import each other.
  • cicada_nwb.testing.synthetic_nwb: every synthetic file has a Subject (age range P90D/P120D, weight 0.025 kg) and session metadata (SUBJECT, SESSION), as standard NWB files; new files widefield (Petersen converter layout: dff0 OnePhotonSeries in ophys, raw F as an external file, F0 image Images), optogenetic (ogen_stim) and ophys_pixel_masks (ROIs stored as pixel masks only), with their known values (widefield_dff0(), widefield_f0(), OPTO_STIM, PIXEL_MASKS).
  • Tests: known-answer tests of the metadata, widefield and optogenetic getters on synthetic and real files, and of the units getters left untested; tests/test_all_getters.py runs every public getter of the six submodules on every test file (22 synthetic, 9 real). A getter that the test does not call gives a MissingTestWarning (fails with CICADA_STRICT_TESTS=1).

Fixed

  • calcium_imaging.get_ci_dimension_from_img_mask: with pixel masks only (e.g. the Allen files), the size of the image masks get_image_mask builds from them (the imaging movie's, enlarged to the masks' extent); before, (None, None).
  • Unit locations and coordinates of files that link units to electrodes with references instead of Allen's peak_channel_id (P72): get_units_location, get_units_location_map, get_spiketimes_group and get_units_coordinates take the electrodes table's values through the units' max_electrode (one electrode per unit, IBL), else the standard NWB electrodes column (the most common location of the unit's electrodes, the first one on ties; the mean position for coordinates). Before, these units had no location (their ids were offered instead) and no coordinates, e.g. the IBL demo file (now "Mediodorsal nucleus of thalamus"). Results of the files with a location on the units table or with peak_channel_id unchanged (compared on the demo and synthetic files). New synthetic files units_max_electrode, units_electrode_refs.
  • metadata.get_sessions_info()['weight'] was 0.0 for weights in kilograms (DANDI 000044 '0.3 kg', IBL '0.023 kg'): the weight is now read in grams ('15.1' and '15.1 g' as before, '0.3 kg' → 300.0). Intended change: an unreadable value ('nan', 'inf', a negative number) gives 0.0, like 'na' (before: NaN, inf, the number); '25G' gives 25.0 (before: 0.0). Other values unchanged (compared on every form found in the real files).
  • calcium_imaging.get_image_mask() crashed on files storing pixel masks only (Allen ophys, suite2p exports such as DANDI 001361): pynwb's pixel_to_image cannot know the image size. Image masks are now built with x = line and y = column (as get_pixel_mask on image-mask files and the cells map), sized as the imaging movie, else on the masks (largest x and y + 1).
  • behavior.get_mouse_speed_info() / get_mouse_position_info() crashed when the last-resort search found a table column named like 'speed' / 'position' (DANDI 000055); they now take only time series, and a series stored with a rate gives (data, None). This also broke the "speed" data requirement of plugins on such files.
  • widefield.get_widefield_raw_acquisition_path() and get_widefield_f0(), and behavior.get_facemap_data(), crashed on acquisitions of another type (no external file, not an Images container); they return None (no SVD images for facemap).
  • Behavioral series with an unknown conversion factor (conversion = NaN, e.g. the DANDI 000055 pose series, positions in pixels labelled 'meters'): get_behavioral_time_series_data(..., in_unit=True) returned only NaN; the values are now returned as stored, and get_behavioral_time_series_unit gives 'a.u.' for them. Same for a NaN offset. Every other series of the demo files unchanged (proven identical).
  • metadata.age crashed on an age that is not a number with a unit (DANDI 000044 stores '/'), so did every plugin reading it (e.g. PSTHs). An unreadable age now gives None, as a missing one; a range (P90D/P120D) gives its lower bound. Intended change: an age such as P1Y2M gave a text ('1Y2') instead of a number and now gives None; age_unit gives None for an age without a unit (before: its last digit, e.g. '2' for '12').
  • calcium_imaging.get_ci_movie_dimension() returned 1 x 1 for files whose TwoPhotonSeries data is a placeholder (e.g. suite2p exports, DANDI 001361): the size is now read from dimension in that case (other files unchanged).
  • behavior.get_epochs_names_from_table() crashed on any text or ragged column, e.g. the standard epochs.tags (np.isnan applied to text). Columns are now read through to_dataframe(); ragged columns are flattened into their unique values and missing values are dropped whatever the column type.
  • behavior.get_epochs_timestamps_from_table() crashed when filtering on a ragged column. For ragged columns, a row now matches if any of its values is requested. It returns (None, None) instead of None when there is no table or no match, like the trial version.
  • behavior.get_behavioral_time_series_timestamps() crashed on series stored with a rate instead of timestamps. Timestamps are now rebuilt from rate and starting_time, with warnings for badly formed series.
  • calcium_imaging.get_roi_response_serie_data() always transposed, so series stored as (n_rois, n_times) came back as (n_times, n_rois). Orientation is now checked against the number of ROIs referenced by the series, and the result is always (n_cells, n_times); 1D series (one ROI) come back as 2D. Seen in some Cossart files.
  • calcium_imaging.get_roi_response_serie_data_by_keyword() with a list of keywords returned {} as soon as the first series did not match.
  • calcium_imaging.get_rrs_sampling_rate() crashed when a series had neither rate nor timestamps. It also returned a rate stored as a period unchanged, while get_roi_response_serie_timestamps() inverted it.
  • calcium_imaging.get_cell_indices_by_cell_type() gave wrong indices when a series references only a subset of the ROI table.
  • calcium_imaging.get_cells_qc() and get_cell_snr() returned every row of the ROI table, not the rows the series refers to (in their order), wrong when a series references only a subset of the table (same values otherwise, proven on real files). get_cells_qc also leaves out voxel_mask and reads ragged columns.
  • CI movie getters: get_starting_ci_movie_frames crashed on a movie without starting_frame (Cossart, Giocomo), get_ci_movie_dimension / get_n_ci_movie_frames on a movie without dimension (e.g. a behavior camera ImageSeries), get_imaging_plan_location on a plain ImageSeries: they now return None. get_ci_movies_sample no longer reads a pixel of every frame to count the frames.
  • electrophysiology.get_spiketimes_group() raised a KeyError when the units table has no location column (the unit ids offered by get_units_location() under the name 'index' are now matched on the units index).
  • Epoch/trial table choices no longer offer blank text values (e.g. unlabelled epochs in DANDI 000055); filtering on '' still works.
  • Sampling rate estimated from timestamps (calcium_imaging.get_rrs_sampling_rate, electrophysiology electrical series rate) is no longer rounded to 2 decimals (e.g. 10.7945 Hz instead of 10.79 Hz on the Cossart demo file). Intended change: results using these rates shift slightly.

Improved

  • get_epochs_names_from_table() returns a single dict {column: [values]} instead of a list of dicts. Values are plain Python types, no longer numpy scalars.
  • Epoch and trial tables are looked up in the standard nwb.epochs / nwb.trials first; the old search by name is kept as a fallback.
  • Text columns with one distinct value per row are now offered as selection choices in small tables (<= 50 rows, SMALL_TABLE_MAX_ROWS), e.g. named epochs PREEpoch / MazeEpoch / POSTEpoch (DANDI 000044). Numeric per-row-unique columns and text columns of larger tables stay hidden (identifiers). Checked on all local test files: only that column newly appears.
  • trial_type is now offered as a trial-table selection column. Both get_*_names_from_table() functions take an exclude_columns argument.
  • Requested values are converted to the column's type, so "1" matches 1 and "False" matches False.
  • Behavioral epochs, events and time series are found by container type in any processing module, not only in one named behavior/Behavior. Epoch start/stop come from the IntervalSeries data sign when it is consistent.
  • Table times are read as frame indices only when every value is an integer and the largest one is beyond the session duration (some early Allen Institute files). When the duration is unknown, they are read as seconds. A warning is printed when every selected row has the same start_time.

  • Electrophysiology getters (get_spike_times, get_single_unit_spike_times, get_units_location, get_units_location_map, get_spiketimes_group) read only the units-table columns they need instead of the whole table (some files carry heavy per-spike/per-channel columns, e.g. Allen spike_amplitudes, waveform_mean). Outputs checked identical to the previous code on 4 real files (Allen 563497, MH031, DANDI 000044, Armstrong 489); Allen: ~650 MB less and ~3x faster per call, MH031: ~12x faster.

  • Calcium imaging: a rate below 1 Hz is read as a sampling period only when the recording would otherwise last more than 24 h (before: always inverted, wrong for slow imaging). A missing starting_time is taken as 0 instead of returning no timestamps.
  • Calcium imaging: the cell-type column is chosen by exact name first (cell_type, celltype, ..., type), then among the columns containing "type" whose values are categorical, preferring those also containing "cell" (before: the first column containing "type"). get_all_cell_types() also reads DfOverF series.
  • GUI "Group by" factors that apply to any standard file: "Cell types" (with_cell_types(): 'With cell types' if the imaging ROIs or the units have cell types, else 'Without cell types'), one factor per kind of data ("Data: ROI signals", "ROI rasters", "imaging movie", "units", "electrical series", "widefield", "behavioral series", "epochs", "trials", "optogenetics"; methods with_<kind>(), 'With ' / 'Without '), and the NWB text fields "Lab", "Institution", "Protocol", "Experimenter". New properties metadata.institution, metadata.protocol (also on the session). The Cossart factors "Raster status" (found the raster by its name) and "Cell type status" (listed the cell types) are replaced by them: cossart.raster_status() and cossart.cell_types_status() removed. The Petersen submodule adds "Session description" and "Experiment description".
  • behavior.get_facemap_data() moved to petersen.get_facemap_data() (Facemap series names of the Petersen pipeline; identical outputs, checked on the synthetic, demo and hand-built Facemap files).
  • calcium_imaging.get_cell_snr() reads only the SNR column instead of every column of the ROI table (outputs identical on the synthetic files, edge cases and demo files).
  • Getters used by no CICADA code removed: calcium_imaging.get_signals_info, get_signal_by_keyword, get_signal_keys (any TimeSeries of the processing modules, found by name), get_n_ci_movie_frames (read only a 3-value dimension, rare), get_starting_ci_movie_frames; behavior.get_acquisition_names, get_interval_original_frames (non-standard start_original_frame / stop_original_frame columns), get_stimulus_names, and get_trials_timestamps_from_table / get_epochs_timestamps_from_table: use get_table_timestamps(name, requirements_dict, use_stop_time) with get_trial_table_name() or "epochs" (same results); petersen.get_dlc_timestamps, get_dlc_data: use behavior.get_behavioral_time_series_data(name, in_unit=True).

Added

  • electrophysiology.get_unit_labels(label_col='bc_label'): unique unit quality labels, or [] if the column is absent.
  • electrophysiology.get_spiketimes_col() reads column names only (no units table loaded).
  • submodules/time_series_utils.py: shared, tolerant timestamps and rate reading for TimeSeries (used by behavior and calcium imaging).
  • use_stop_time option (default False) on get_epochs_timestamps_from_table() / get_trials_timestamps_from_table(): row 1 holds the real stop_time instead of start_time + 1.
  • behavior.get_epoch_table().
  • cicada_nwb.testing.synthetic_nwb: generator of synthetic NWB files with known content (make_<name>(path), generate_all(folder), python -m cicada_nwb.testing.synthetic_nwb <folder>), for the tests of cicada-nwb and cicada-analysis and for labs testing their plugins.
  • tests/ with synthetic NWB fixtures (pytest), incl. test_electrophysiology.py (known outputs for units tables with location on the units table, from the electrodes table, or absent; labels present or absent).

[0.3.2] - 2026-07-13

Added

  • calcium_imaging.get_cell_snr() — extract per-cell SNR from a custom *snr* column in the ROI table, if present.
  • electrophysiology.get_units_coordinates() — x/y/z unit coordinates, joined in from the electrodes table (via peak_channel_id) when absent from the units table.
  • electrophysiology.get_units_location_map() — per-unit {unit_id: location} dict counterpart to get_units_location().
  • electrophysiology.get_spike_times(), get_spiketimes_group() for filtering/grouping units by label and location columns.

Improved

  • electrophysiology.get_units_location() and get_spiketimes_group() now try a longer list of location column names (ccf_atlas_acronym, ccf_acronym, location, acronym, ecephys_structure_acronym, atlas_id) and, if none is present on the units table, fall back to joining it in from the electrodes table before giving up. get_units_location() returns the resolved column name alongside the values: (locs, col_name).

Fixed

  • behavior.get_trials_timestamps_from_table() now returns (None, None) instead of None when no trial table or no matching trials are found, and skips (instead of raising) on requirement columns absent from the trial table.
  • Fixed a typo in behavior.get_mouse_position_info() (timesatmps → timestamps) and guarded speed/position timestamp reads against series with no timestamps array.

[0.3.1] - 2026-06-02

Added

  • New wrappers for extracellular electrophysiology.
  • Speed and position wrappers in the behavior module.

Improved

  • Submodule attributes (behavior, calcium_imaging, etc.) now carry explicit type annotations instead of = None declarations, enabling IDE autocomplete when using cicada-nwb as an external package.

[0.3.0] - 2026-05-11

Publication

  • Release associated with the Bech, Dard et al., eLife publication

[0.1.0] - 2026-04-05

Added

  • Initial release, refactored from the CICADA monolithic repository.
  • Lazy read-only NWB wrappers: session.calcium_imaging, session.behavior, session.widefield, session.metadata, session.subject.
  • No GUI or analysis dependencies — pure data access layer.
  • Tested on Python 3.11 / pynwb 3.1.3 / NumPy 2.4.4.