Skip to content

session.calcium_imaging

ROI response series (traces, rasters), segmentation, cell types and quality, imaging movies. A series is addressed by [module, interface, series name].

cicada_nwb.submodules.calcium_imaging.NWBCalciumImaging

Read-only access to calcium imaging data stored in an NWB file. Covers: ROI response series, segmentations, cell types, CI movies. No computation — returns raw arrays and metadata as stored.

contains_ci_movie

contains_ci_movie(consider_only_2_photons)

Return True if the NWB file contains at least one CI movie. Args: consider_only_2_photons: if True, only TwoPhotonSeries count.

get_all_cell_types

get_all_cell_types()

Return a list of unique cell type names across all ROI response series. Empty list means cell types are not annotated.

get_binary_raster_series

get_binary_raster_series()

get_cell_indices_by_cell_type

get_cell_indices_by_cell_type(roi_serie_keys)

Return a dict mapping cell type name → array of cell indices. Uses rrs.control (uint8 code per cell) and rrs.control_description (name per cell). Args: roi_serie_keys: [module_name, interface_name, rrs_name] Returns: dict or empty dict

get_cell_snr

get_cell_snr(roi_serie_keys)

Return a list of snr (one per row of the series) from the first ROI table column whose name contains 'snr', or an empty list. Reads only that column. Args: roi_serie_keys: [module_name, interface_name, rrs_name]

get_cells_qc

get_cells_qc(roi_serie_keys)

Return a dict {column: values} with every column of the ROI table but the masks, values in the order of the series' rows (the ROIs it points to); {} if the series is not found. Args: roi_serie_keys: [module_name, interface_name, rrs_name]

get_ci_dimension_from_img_mask

get_ci_dimension_from_img_mask(segmentation_info)

Infer CI movie dimensions from the shape of the image masks, or, with pixel masks only, the size of the image masks get_image_mask builds from them. Args: segmentation_info: [module_name, image_seg_name, plane_seg_name] Returns: (n_lines, n_cols) or (None, None)

get_ci_movie_dimension

get_ci_movie_dimension(only_2_photons=False, ci_movie_name=None)

Return (n_lines, n_cols) for a CI movie, or (None, None).

get_ci_movie_sampling_rate

get_ci_movie_sampling_rate(only_2_photons=False, ci_movie_name=None)

Return the sampling rate (Hz) of a CI movie, or None. Args: only_2_photons: if True, only consider TwoPhotonSeries ci_movie_name: if given, only check that specific acquisition key

get_ci_movie_time_stamps

get_ci_movie_time_stamps(ci_movie_name=None)

Return timestamps for the CI movie from the 'ci_frames' acquisition entry, or, with ci_movie_name, of that movie (stored, or from its rate and starting time; see get_ci_movies). Returns None if not present.

get_ci_movies

get_ci_movies(only_2_photons)

Return a dict of CI movies: {key: file_path_or_data}. Args: only_2_photons: if True, return only TwoPhotonSeries

get_ci_movies_sample

get_ci_movies_sample(only_2_photons, n_frames=2000, ci_movie_name=None)

Return a dict of CI movies (or of the movie ci_movie_name) sampled to at most n_frames: {key: file_path_or_data}.

get_good_cells

get_good_cells(roi_serie_keys)

Boolean array, one value per row of the series: True for the cells passing the quality control of the first CELL_QUALITY_COLUMNS column found ('good_cells', suite2p 'iscell': its first value); NaN counts as False. None if the ROI table has none of these columns.

get_image_mask

get_image_mask(segmentation_info)

Return image masks for all cells in a plane segmentation. Args: segmentation_info: [module_name, image_seg_name, plane_seg_name] Returns: Image mask array or list of 2D arrays, one per cell. Converts pixel_mask if image_mask absent.

get_imaging_movie_names

get_imaging_movie_names()

Names of the imaging movies with frames (TwoPhotonSeries, OnePhotonSeries; not e.g. behavior cameras).

get_imaging_plan_location

get_imaging_plan_location(only_2_photons=False, ci_movie_name=None)

Return the imaging plane location string, or None.

get_pixel_mask

get_pixel_mask(segmentation_info=None, roi_serie_keys=None)

Return pixel masks for all cells in a plane segmentation, or for the cells of an ROI response series. Args: segmentation_info: [module_name, image_seg_name, plane_seg_name] roi_serie_keys: [module_name, interface_name, rrs_name]: instead of segmentation_info, the masks of the rows of the table the series refers to, in its order (one per row of its data) Returns: List of pixel mask arrays, one per cell. Converts image_mask if pixel_mask absent.

get_raster_dur_series

get_raster_dur_series()

get_raster_like_series

get_raster_like_series()

Binary rasters, spike counts and event amplitudes: what raster analyses can work from.

get_roi_response_serie_data

get_roi_response_serie_data(keys)

Return the data array for one ROI response series as (n_cells, n_times), whatever the orientation stored in the file (see _orient_rrs_data). Args: keys: [module_name, interface_name, rrs_name] Returns: 2D numpy array (n_cells, n_times) or None

get_roi_response_serie_data_by_keyword

get_roi_response_serie_data_by_keyword(keys, keyword)

Return a dict of {rrs_name: data_array (n_cells, n_times)} for all RRS under keys[:2] whose name contains keyword (str), or all the keywords (list of str). Args: keys: [module_name, interface_name] keyword: str or list of str Returns: dict or empty dict

get_roi_response_serie_kind

get_roi_response_serie_kind(keys)

Kind of activity of one ROI response series, from its values (first CLASSIFY_SECONDS, at most CLASSIFY_MAX_FRAMES frames, all cells) and its sampling rate: RASTER_DUR, PURE_RASTER, SPIKE_COUNTS, EVENT_AMPLITUDES or TRACES (see classify_activity); None if the series does not exist.

get_roi_response_serie_timestamps

get_roi_response_serie_timestamps(keys, verbose=True)

Return timestamps for one ROI response series as a 1D array. Falls back to rebuilding timestamps from rate and starting_time (0 if missing) when not stored. A period stored as a rate is detected (see time_series_utils.resolve_rate). Args: keys: [module_name, interface_name, rrs_name] verbose: deprecated — logging level is now controlled via the standard logging module Returns: 1D numpy array or None

get_roi_response_series

get_roi_response_series(keywords_to_exclude=None)

Return all ROI response series names grouped by module and interface. Structure: {module_name: {interface_name: [rrs_name, ...]}} Args: keywords_to_exclude: list of str — exclude RRS whose names contain any of these

get_roi_response_series_by_kind

get_roi_response_series_by_kind(kind)

ROI response series of one kind, or of any kind in a tuple, as [[module, interface, name], ...].

get_roi_response_series_list

get_roi_response_series_list(keywords_to_exclude=None)

Return a sorted unique array of all ROI response series names across all modules. Args: keywords_to_exclude: list of str — exclude names containing these keywords

get_rrs_sampling_rate

get_rrs_sampling_rate(keys)

Return the sampling rate (Hz) for one ROI response series: its rate (a period stored as a rate is detected), or estimated from the first 100 timestamps. Args: keys: [module_name, interface_name, rrs_name] Returns: float or None

get_rrs_segmentation

get_rrs_segmentation(keys)

Return the plane segmentation an ROI response series refers to (through its 'rois' link). Args: keys: [module_name, interface_name, rrs_name] Returns: [module_name, image_seg_name, plane_seg_name] (the segmentation_info of get_pixel_mask), or None if the series does not exist or has no 'rois' link.

get_segmentations

get_segmentations()

Return a nested dict of all image segmentations. Structure: {module_name: {image_seg_name: [plane_seg_name, ...]}}

get_sparse_activity_series

get_sparse_activity_series()

get_summary_image

get_summary_image(keys)

The 2D image keys = [module_name, images_name, image_name] (see get_summary_images), or None.

get_summary_images

get_summary_images()

2D images of the Images containers (e.g. suite2p 'Backgrounds_0' meanImg / max_proj, Allen 'SummaryImages'), in the processing modules and in acquisition ('acquisition' as module name), as a nested dict like get_segmentations: {module_name: {images_name: [image_name, ...]}}. Read one with get_summary_image.

has_ci_movie_frames

has_ci_movie_frames(consider_only_2_photons, ci_movie_name=None)

True if a CI movie (or the movie ci_movie_name) has actual frames: listed external movie files, or stored data with at least 2 frames larger than 1x1. Some files keep only a placeholder (e.g. suite2p exports: data (1, 1, 1), size in 'dimension'), which contains_ci_movie counts but which holds no movie.

has_good_cells

has_good_cells(roi_serie_keys)

True if the ROI table of the series has a cell quality column (see get_good_cells).

image_plane_location

image_plane_location()

Return imaging plane location string for GUI grouping, or 'NA'.

is_binary_raster

is_binary_raster(keys)

Only 0 and 1 (raster dur or pure raster).

is_event_amplitudes

is_event_amplitudes(keys)

Event amplitudes (non-negative, nearly all 0, continuous).

is_raster_dur

is_raster_dur(keys)

Only 0 and 1, transients over several frames: transient durations are known.

is_sparse_activity

is_sparse_activity(keys)

Spike counts or event amplitudes: sparse but not binary, binarized by raster analyses.

is_spike_counts

is_spike_counts(keys)

Spikes per frame (non-negative integers, nearly all 0).

is_traces

is_traces(keys)

Continuous signals: raw or dF/F traces, deconvolved rates.