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_kindreads the first 2 minutes of a series (CLASSIFY_SECONDS, all cells, at mostCLASSIFY_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_timestampsandtime_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 (suite2pspks, 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_timeis an integer, the values are read as frame indices only if they go beyond the session duration. That duration now comes fromtime_series_time_range, the same reading of each TimeSeries asNWBSession.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-numericstarting_timeis taken as 0, as intime_series_timestamps. Before, the range was NaN, andNWBSession.get_timestamps_rangecould return NaN or a wrong start or end.- Movies stored outside the NWB file (
external_fileof an ImageSeries: imaging movies inget_ci_moviesandget_ci_movies_sample, widefield raw acquisitions inget_widefield_raw_acquisition_path, behavior movies inget_behavior_movies): a relative path, which the NWB format takes as relative to the.nwbfile, was returned as stored and so opened relative to the current folder; it is now joined to the folder of the.nwbfile. 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 helpersubmodules.time_series_utils.external_file_paths.
[0.4.0] - 2026-11-12¶
Changed (breaking)¶
- DANDI support is installed with cicada-nwb:
remfile,requestsandplatformdirsare regular dependencies, thedandiextra is gone (pip install "cicada-nwb[dandi]"no longer exists; plaincicada-nwbgives the same). The GUI's DANDI menus work in every install. - The Cossart and Petersen lab submodules left cicada-nwb:
session.cossartandsession.petersennow 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 groupcicada_nwb.lab_submodules; their methods are unchanged and documented in the lab READMEs. Without the lab package,session.<lab>raises anAttributeErrornaming the package to install.cicada_nwb.lab_submoduleskeeps the base classNWBLabSubmodule.
Added¶
electrophysiology.get_electrical_series_electrode_groups(keys): the electrode group of each channel of an electrical series (electrodes tablegroup_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.nwbfile 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 bycicada-config sessionsand 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 cleardeletes the stream chunk cache (downloads are kept). Modulecicada_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-eventsEvents(ndx-events 0.2, e.g. DANDI 000055ReachEvents), read through the extension spec cached in the file (ndx-events need not be installed):behavior.get_behavioral_events_names,get_behavioral_events_timesandget_event_times. TheEventsTableof ndx-events 0.4 is not read. session.sourceof a local file also gives itssizein 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 dependencypackaging. - 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) addssession.<lab>without changing cicada-nwb; Cossart and Petersen are declared in this package'spyproject.tomluntil they move to their lab packages. Replaces the scan of thelab_submodules/folder, which hid every loading error: a lab submodule that cannot be loaded (import error, not anNWBLabSubmodule, entry point not named as itsname, name already used by the session) is left out with a warning and listed byNWBSession.lab_submodule_errors().session.<lab>for a lab not installed raises anAttributeErrorsaying which package to install. Grouping factors are attribute paths from the session ("petersen.session_type","metadata.session_description"), read by the newNWBSession.group_value(path); the 7 Cossart / Petersen relay methods ofNWBSession(session_type(),belt_type(), ...) are removed (usesession.petersen.session_type(), ...).cicada_nwb.lab_submodulesexports onlyNWBLabSubmodule. 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) andchangelog.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_keysdoes not exist (a series is addressed by[module, interface, series name]fromget_roi_response_series()), there is nosession.subject(subject_id,age,genotypeare properties of the session), widefield acquisitions come fromget_wf_acquisition_dict(). In the user guide,get_behavioral_time_series_data/_timestampstakeserie_name. Testtests/test_docs_api.py: the methods and arguments used in the README and the user guide exist. - DANDI files opened directly:
NWBSessionacceptsdandi://<dandiset>[@<version>]/<path>, dandiarchive.org file links, DANDI API asset links and any.nwbURL. Modesstream(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) andauto(download up to 1 GB):NWBSession(ref, dandi_mode=...). Once opened,session.data_refis the version-pinned address (so sessions and combined YAMLs record the dandiset version) andsession.sourcegives 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 (nodandipackage); new extrapip install "cicada-nwb[dandi]"(remfile, requests, platformdirs). Modulecicada_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) anddandi.list_assets(dandiset, version, path_prefix)(NWB files with size and version-pinned address, all pages). Adandi://address not ending in.nwbis 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 variableCICADA_DANDI_CHUNKSmoves it),dandi.download_dir()(default folder of downloads).behavior.get_intervals_names(include_trials=True, epoch_labels=False):include_trials=Falseleaves out the trial table (stored innwb.intervalstoo),epoch_labels=Truereplaces 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 toEPOCH_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 ophysdrifting_gratings: one row per grating presentation with its orientation and temporal frequency) are read like those ofnwb.intervals: listed byget_intervals_names(stimulus/<name>if the name is already used), read byget_interval_as_data_frame,get_interval_times,get_interval_original_framesandget_event_times. Results for the tables ofnwb.intervalsunchanged (checked on the demo files and the full Allen ophys file).get_interval_as_data_frameleaves 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) andecephys_lfp(LFP with timestamps, electrode subset) incicada_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_timesandget_spiketimes_grouptakelabel_col=None= the first label column of the file (was alwaysbc_label); the spike getters takereturn_ids=Trueto 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 fileunits_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), andget_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)returnsdata * 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 frombehavior, unchanged;session.behavior.get_opto_stimulation_time_serieno longer exists) andget_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 (itsroislink), as[module, image segmentation, plane segmentation], the format ofget_pixel_mask.- Cell quality control of imaging ROIs:
calcium_imaging.get_good_cells(keys)(boolean, one value per row of the series, from the firstCELL_QUALITY_COLUMNScolumn of the ROI table:good_cells, then suite2piscell(its first value); NaN counts as False;Nonewithout such a column) andhas_good_cells(keys). Synthetic ophys files havesnrandgood_cellscolumns. 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. suite2pBackgrounds_0meanImg / max_proj / Vcorr, AllenSummaryImages, in the processing modules and in acquisition; nested dict likeget_segmentations) andget_summary_image(keys).- CI movies are also found in the processing modules (e.g. the widefield dF/F movie
dff0, a OnePhotonSeries inprocessing/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_framesandget_ci_movies_sampletakeci_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 fromcalcium_imaging, unchanged); submodules no longer need to import each other.cicada_nwb.testing.synthetic_nwb: every synthetic file has a Subject (age rangeP90D/P120D, weight0.025 kg) and session metadata (SUBJECT,SESSION), as standard NWB files; new fileswidefield(Petersen converter layout:dff0OnePhotonSeries inophys, rawFas an external file,F0 imageImages),optogenetic(ogen_stim) andophys_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.pyruns every public getter of the six submodules on every test file (22 synthetic, 9 real). A getter that the test does not call gives aMissingTestWarning(fails withCICADA_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 masksget_image_maskbuilds 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_groupandget_units_coordinatestake the electrodes table's values through the units'max_electrode(one electrode per unit, IBL), else the standard NWBelectrodescolumn (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 withpeak_channel_idunchanged (compared on the demo and synthetic files). New synthetic filesunits_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'spixel_to_imagecannot know the image size. Image masks are now built with x = line and y = column (asget_pixel_maskon 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()andget_widefield_f0(), andbehavior.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, andget_behavioral_time_series_unitgives 'a.u.' for them. Same for a NaN offset. Every other series of the demo files unchanged (proven identical). metadata.agecrashed 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 givesNone, as a missing one; a range (P90D/P120D) gives its lower bound. Intended change: an age such asP1Y2Mgave a text ('1Y2') instead of a number and now givesNone;age_unitgivesNonefor 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 fromdimensionin that case (other files unchanged).behavior.get_epochs_names_from_table()crashed on any text or ragged column, e.g. the standardepochs.tags(np.isnanapplied to text). Columns are now read throughto_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 ofNonewhen 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, whileget_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()andget_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_qcalso leaves outvoxel_maskand reads ragged columns.- CI movie getters:
get_starting_ci_movie_framescrashed on a movie withoutstarting_frame(Cossart, Giocomo),get_ci_movie_dimension/get_n_ci_movie_frameson a movie withoutdimension(e.g. a behavior camera ImageSeries),get_imaging_plan_locationon a plain ImageSeries: they now return None.get_ci_movies_sampleno 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 byget_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,electrophysiologyelectrical 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.trialsfirst; 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 epochsPREEpoch/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_typeis now offered as a trial-table selection column. Bothget_*_names_from_table()functions take anexclude_columnsargument.- Requested values are converted to the column's type, so
"1"matches1and"False"matchesFalse. - 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. Allenspike_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"; methodswith_<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()andcossart.cell_types_status()removed. The Petersen submodule adds "Session description" and "Experiment description". behavior.get_facemap_data()moved topetersen.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-valuedimension, rare),get_starting_ci_movie_frames;behavior.get_acquisition_names,get_interval_original_frames(non-standardstart_original_frame/stop_original_framecolumns),get_stimulus_names, andget_trials_timestamps_from_table/get_epochs_timestamps_from_table: useget_table_timestamps(name, requirements_dict, use_stop_time)withget_trial_table_name()or"epochs"(same results);petersen.get_dlc_timestamps,get_dlc_data: usebehavior.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_timeoption (defaultFalse) onget_epochs_timestamps_from_table()/get_trials_timestamps_from_table(): row 1 holds the realstop_timeinstead ofstart_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 (viapeak_channel_id) when absent from the units table.electrophysiology.get_units_location_map()— per-unit{unit_id: location}dict counterpart toget_units_location().electrophysiology.get_spike_times(),get_spiketimes_group()for filtering/grouping units by label and location columns.
Improved¶
electrophysiology.get_units_location()andget_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 ofNonewhen 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 notimestampsarray.
[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= Nonedeclarations, 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.