ca_neurons.py

CaNeurons

This class represents calcium imaging data, associated labels, raw traces, and other related properties. It extends from the DataWriter class, which seems to be imported from neuropy.core.datawriter.

Attributes

• S, C, A, YrA (np.ndarray): Calcium imaging data arrays.
• trim (dict or None): Information for trimming data.
• t (various types, optional): Time associated with the data.
• sampling_rate (int, default: 15): Sampling rate for the calcium imaging data.
• neuron_ids (various types, optional): IDs referencing original numbers from minian output.
• neuron_type (various types, optional): Type or classification of the neuron.
• metadata (various types, optional): Additional metadata associated with the data.
• basedir (str or Path, optional): Base directory for the data.
• posthocmerge (dict or None, optional): Information regarding post-hoc merging of data.

Methods

plot_rois(...) -> Tuple[plt.Figure, plt.Axes, List]:

• Plots regions of interest (ROIs) based on several optional parameters including labels, axes, mask plotting, and highlighting.

max_proj() -> Any:

• Returns the maximum projection for the session. It appears to grab this data from an external directory.

roi_com(neuron_inds=None) -> np.ndarray:

• Returns the center-of-mass of all neuron ROIs.

min_proj(proj_type: str) -> Any:

• Returns the appropriate minimum projection.

plot_proj(proj_type: str, ax=None, flip_yaxis=False):

• Plots the specified type of projection.

plot_rois_with_min_proj(...):

• Plots ROIs over the maximum projection alongside the minimum projection. This is primarily used for data quality control purposes.

plot_traces():

• Placeholder method intended to plot traces. Implementation in this file does nothing.

plot_traces_and_ROIs():

• Placeholder method intended to plot both traces and ROIs. Current implementation does nothing.

quick_merge(unit_ids: list, method="max") -> CaNeurons:

• Quickly merges units post-hoc. The method allows for merging of multiple neuron units either based on the maximum value or other methods (although only "max" is implemented currently).

Usage Example

# Assuming the CaNeurons class and necessary imports are available

# Create a CaNeurons instance
data = CaNeurons(S=np.array([...]), C=np.array([...]), A=np.array([...]), YrA=np.array([...]))

# Plot regions of interest
data.plot_rois(neuron_inds=[0, 1, 2], label=True)

Notes

• Some functions within the class rely on external utilities and functions such as load_variable, detect_roi_edges, detect_roi_centroid, and flatten.

---

CaNeuronReg

Code focusing on tracking and manipulating neurons across multiple imaging sessions.

Attributes

caneurons: A list containing data structures for each calcium imaging session. alias: An optional list providing identifiers or names for each session. nsessions: The number of imaging sessions (derived from the length of caneurons).

Methods:

quick_merge(self, sesh_alias, in_place=False, kwargs):

• Merges neurons for a given session.
• Inputs:
  • sesh_alias: Identifier for the session.
  • in_place: If True, updates the session in caneurons with the merged result.
• Returns: Merged neurons for the session.

get_session(self, sesh_alias: str):

• Retrieves data for a specific session.
• Inputs:
  • sesh_alias: Identifier for the session.
• Returns: Data for the specified session.

get_alias_index(self, sesh_alias: str):

• Gets the index of a session based on its alias.
• Inputs:
  • sesh_alias: Identifier for the session.
• Returns: Index of the specified session.

plot_rois_across_sessions(self, fig_title="", sesh_plot: list or None = None, kwargs):

• Plots ROIs across different sessions.
• Inputs:
  • fig_title: Title for the figure.
  • sesh_plot: List of sessions to plot.
• Returns: Plot figure and axes.

plot_reg_neurons_overlaid(self, sesh1, sesh2, map1_2, plot_max=True, ax=None, color=None):

• Overlays neurons from two sessions on a plot.
• Inputs:
  • sesh1 and sesh2: Identifiers for the two sessions.
  • map1_2: DataFrame mapping neurons between the two sessions.
• Returns: Change in center-of-mass for mapped neurons.

overlay_base_roi_on_reg(...):

• Overlays a single ROI from one session on all ROIs from another.
• Returns: None.

shift_roi_edges(roi_edges: plt.Line2D, delta_com: np.ndarray, use_mean: bool = True):

• Adjusts plotted ROI edges by a given amount.
• Inputs:
  • roi_edges: List of plotted ROI edges.
  • delta_com: Shift amounts for ROI edges.
• Returns: None.

load_pairwise_np_map(map_np_filename):

• Loads a pairwise neuron map from a file into a DataFrame.
• Inputs:
  • map_np_filename: Filename of the map.
• Returns: DataFrame containing the map.

load_pairwise_map(self, sesh1, sesh2):

• Description: Loads a pairwise neuron map between two sessions from a file.
• Inputs:
  • sesh1 and sesh2: Identifiers for the two sessions.
• Returns: Loaded pairwise map.

Usage Examples

# Example data
session1_data = ...
session2_data = ...

# Create an instance of the CaNeuronReg class
neuron_registry = CaNeuronReg(caneurons=[session1_data, session2_data], alias=['session1', 'session2'])

# quick_merge(self, sesh_alias, in_place=False, **kwargs)
merged_neurons = neuron_registry.quick_merge(sesh_alias='session1', in_place=True)

# get_session(self, sesh_alias: str)
merged_neurons = neuron_registry.quick_merge(sesh_alias='session1', in_place=True)

# get_session(self, sesh_alias: str)
session_data = neuron_registry.get_session(sesh_alias='session1')

# get_alias_index(self, sesh_alias: str)
session_index = neuron_registry.get_alias_index(sesh_alias='session1')

# plot_rois_across_sessions(self, fig_title="", sesh_plot: list or None = None, **kwargs)
fig, ax = neuron_registry.plot_rois_across_sessions(fig_title="ROIs Across Sessions", sesh_plot=['session1', 'session2'])

# plot_reg_neurons_overlaid(self, sesh1, sesh2, map1_2, plot_max=True, ax=None, color=None)
delta_com = neuron_registry.plot_reg_neurons_overlaid(sesh1='session1', sesh2='session2', map1_2=...)

# overlay_base_roi_on_reg(...)
neuron_registry.overlay_base_roi_on_reg(...)

# shift_roi_edges(roi_edges: plt.Line2D, delta_com: np.ndarray, use_mean: bool = True)
neuron_registry.shift_roi_edges(roi_edges=..., delta_com=...)

# load_pairwise_np_map(map_np_filename)
neuron_map = neuron_registry.load_pairwise_np_map(map_np_filename="map_filename.npy")

# load_pairwise_map(self, sesh1, sesh2)
pairwise_map = neuron_registry.load_pairwise_map(sesh1='session1', sesh2='session2')

Notes

• Some details, like specific data types or exact method behaviors, are inferred from the code and may require actual implementation context to fully understand.

---

PairwiseMap

Save pairwise neuron registration maps

Attributes

• map (pd.DataFrame) - DataFrame containing the pairwise mapping.
• animal (str) - Name of the animal.
• sesh1 (str) - Name of the first session.
• sesh2 (str) - Name of the second session.
• trim1 (str) - Trim attribute of the first session.
• trim2 (str) - Trim attribute of the second session.
• merge1 - Posthoc merge attribute of the first session.
• merge2 - Posthoc merge attribute of the second session.
• savename (pathlib.Path) - Path where the map will be saved.

Methods

to_numpy(savename=None):

• Inputs
  • savename (str or pathlib.Path, optional) - Name of the save file.
• Returns: Saves the object to a numpy file.

---

MultiSessionMap

Class to load maps for more than one pair of sessions

Attributes

• maps (list) - List of PairwiseMap objects.
• multi_sesh_map (pd.DataFrame or None) - Map of multiple sessions. Initialized to None.

Methods

grab_map(sesh_pair_names, coactive_only=False) - Parameters: - sesh_pair_names (list of str) - List containing names of two sessions. - coactive_only (bool, optional) - If True, only returns mappings that are coactive. - Returns: The appropriate pairwise map or None if that session pair doesn't exist.

get_reverse_map(sesh_pair_names)

• Gets session maps going backwards in time.
• Inputs:
  • sesh_pair_names (list of str) - List containing names of two sessions.
• Returns: (Currently not implemented)

**stepwise_reg(kwargs)

• Registers each session in order to the next.
• Inputs:
  • kwargs - Arguments for the .add_third_session() method.
• Returns: Stepwise registered map.

Notes

• It is essential to ensure that the session order provided matches the order in the pairwise maps.

---

Standalone Methods

load_pairwise_map(map_path)

• Function to load a saved pairwise map
• Parameters:
  • map_path (str or pathlib.Path) - Path to the saved pairwise map.
• Returns:
  • Loaded PairwiseMap object.

id_and_plot_reference_cells(caneurons1, caneurons2, return_inds=False, kwargs)

• Function to identify and plot reference cells active across both sessions.
• Inputs:
  • caneurons1 (CaNeurons object) - Object for the first session.
  • caneurons2 (CaNeurons object) - Object for the second session.
  • return_inds (bool, optional) - If True, returns indices of the reference neurons.
  • kwargs - Additional arguments for the CaNeurons.plot_rois method.
• Returns:
  • Figure and axis objects. Optionally, also returns session indices.

detect_roi_edges(roi_binary, kwargs)

• Function to detect the edges of roi.
• Inputs:
  • roi_binary (np.ndarray) - Binary mask of the ROI.
  • kwargs - Additional arguments for the feature.canny function.
• Returns:
  • xedges (np.ndarray) - X coordinates of the edges.
  • yedges (np.ndarray) - Y coordinates of the edges.

detect_roi_centroid(roi_binary, kwargs)

• Function to detect the centroid of a cell ROI.
• Inputs:
  • roi_binary (np.ndarray) - Binary mask of the ROI.
  • kwargs - Not currently used.
• Returns:
  • com_x (float) - X coordinate of the centroid.
  • com_y (float) - Y coordinate of the centroid.

Notes

• Always validate the output of the ROI detection functions visually, especially in complex or noisy images.