calmono 0.0.3__py3-none-any.whl

calmono/ifmatch.py

@@ -0,0 +1,445 @@
+# -*- coding: utf-8 -*-
+"""
+Created on Sat Mar  7 19:49:45 2026
+
+@author: Junxuan Ma
+"""
+
+#Semi-automatically matching calcium imaging pixels with pixels in the immunofluoresent (IF) stained images
+"""
+The matching is performed through a registration process involving stretching and shifting, 
+    while torsion and rotation are not considered. The goal is to align the pixel locations 
+    in the calcium imaging image with those in the IF image. In other words, the objective 
+    is to maximize the number of co-localized pixels (i.e., pixels with the same XY coordinates) 
+    that are positive in both the calcium imaging and IF images. For example, if pixels 
+    identified as cells (positive) in the calcium imaging image correspond to cell pixels 
+    in the IF image, the matching is considered successful.
+
+In this regard, IFmatch is composed of the following steps:
+    1. Downsize the IF images if the resolution is different from that of calcium imaging.
+    
+    2. Binarize the IF images by optimizing the IF intensity threshold to obtain cell shapes 
+        comparable to those in the calcium imaging.
+       Matching_plot_IF_threshold is helpful for deciding the IF intensity threshold.
+       
+    3. Use manual shifting and stretching and plot to understand the stretching factor.
+        This stretching is usually needed because of microscope errors, where the downsizing 
+        performed in step one is insufficient to achieve equal scaling.
+        It can be assumed that IF images taken via the same microscope can use the same stretching factor
+       Manual_regi_plot is to decide on the stretching factors based on manual registration. 
+           This is by inputting stretching factor a and c (fold change) in horizontal and vertical dimension
+           with corresponding shifter factor b and d (unit pixel) in horizontal and vertical dimension.
+        
+    4. Use automatic shifting correction of IF image through a simple optimization function. 
+        The objective function maximizes the number of shared positive pixels.
+    5. Optionally check the matching between calcium imaging and IF.
+    6. Output a dataframe of X and Y coordinates of calcium imaging and an additional column of 
+        IF intensities.
+"""
+import cv2
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+from scipy.ndimage import map_coordinates
+class IFmatch:
+    def __init__(
+        self,
+        Calcium_imaging_df: pd.DataFrame,
+        CGRP_raw: np.ndarray,
+        NF_raw: np.ndarray,
+        Calcium_height: int = 292, 
+        Calcium_width: int = 384  ):
+        
+        self.df_clust= Calcium_imaging_df
+        self.height= Calcium_height
+        self.width= Calcium_width
+        
+        #The IF image is scaled to match the dimensions of the calcium imaging image.
+        self.cgrp= cv2.resize(CGRP_raw,dsize=(self.width,self.height),interpolation=cv2.INTER_AREA)
+        self.nf= cv2.resize(NF_raw,dsize=(self.width,self.height),interpolation=cv2.INTER_AREA)
+    
+    def _if_threshold(self, channel, IF_threshold) -> np.ndarray:
+        return (channel >= IF_threshold).astype(np.uint8)
+    
+    def _mask_matrix_to_df(self, mask: np.ndarray) -> pd.DataFrame:
+        ys, xs = np.nonzero(mask)
+        IF_df = pd.DataFrame({'X': xs.astype(float), 'Y': ys.astype(float)})     
+        return IF_df
+     
+    def Matching_plot_IF_threshold(self, 
+                      IF_threshold_list: list, 
+                      n_rows: int,
+                      which_channel: str = 'NF'):
+        if which_channel == 'NF':
+            channel = self.nf
+        elif which_channel == 'CGRP':
+            channel = self.cgrp
+        else: raise ValueError(f"channel must be 'NF' or 'CGRP'. Got: {which_channel}")
+        
+        n_plots = len(IF_threshold_list)
+        n_cols = (n_plots + n_rows - 1) // n_rows
+
+        fig, axes = plt.subplots(n_rows, n_cols, figsize=(n_cols * 5, n_rows * 4), squeeze=False)
+        for i, thresh in enumerate(IF_threshold_list):
+            row = i // n_cols
+            col = i % n_cols
+            ax = axes[row, col]
+            mask = self._if_threshold(channel, thresh)   # shape (h,w), values 0 or 1   
+            ys, xs = np.nonzero(mask)    # Only coordinates where pixel == 1 (usually << 112k)
+            ax.scatter(xs, ys,
+                       color='blue', s=1,  lw=0,
+                       label='IF positive')
+            ax.scatter(self.df_clust['X'], self.df_clust['Y'],
+                       color='red', s=1, alpha=0.3, edgecolor='none',
+                       label='Ca²⁺ clusters')        
+            ax.set_title(f'Threshold = {thresh}')
+            ax.invert_yaxis()
+            ax.set_aspect('equal')
+            ax.axis('off')
+        # Hide unused panels
+        for j in range(i+1, n_rows * n_cols):
+            r = j // n_cols
+            c = j % n_cols
+            axes[r, c].set_visible(False)       
+        fig.tight_layout()
+
+
+    
+    def _registrate_linear(self,  IF_bi_df, a,b,  c,d):
+        #Input IF_bi_df should be a binary mask
+        IF_regi= IF_bi_df.copy()          
+        IF_regi["X"]= IF_regi["X"]*a + b
+        IF_regi["Y"]= IF_regi["Y"]*c + d
+        return IF_regi
+    
+    def Manual_regi_plot(self, IF_threshold,  a,b, c,d, which_channel: str = 'NF',):
+        if which_channel == 'NF':
+            channel = self.nf
+        elif which_channel == 'CGRP':
+            channel = self.cgrp
+        else: raise ValueError(f"channel must be 'NF' or 'CGRP'. Got: {which_channel}")
+        
+        mask = self._if_threshold(channel, IF_threshold)
+        IF_df= self._mask_matrix_to_df(mask)
+        IF_regi= self._registrate_linear(IF_df, a,b, c,d)
+        
+        
+        fig, (ax1,ax2) = plt.subplots(1,2, figsize=(self.width/10, self.height/20))
+        
+        ax1.scatter( IF_regi['X'], IF_regi['Y'],  color='blue', s=1)      
+        ax1.scatter( self.df_clust["X"], self.df_clust["Y"], color='red',alpha=0.3, s=2)
+        ax1.set_title('Post-registration', fontsize=11)
+        ax1.set(xlim= (0,self.width-1), ylim= (0,self.height-1))
+        ax1.invert_yaxis()
+        
+        ax2.scatter(IF_df['X'], IF_df['Y'],  color='blue', s=1)
+        ax2.scatter( self.df_clust["X"], self.df_clust["Y"], color='red',alpha=0.3, s=2)
+        ax2.set_title('Pre-registration', fontsize=11)
+        ax2.set(xlim= (0,self.width-1), ylim= (0,self.height-1))
+        ax2.invert_yaxis()
+   
+        plt.tight_layout()
+
+    
+    
+    def _registration_obj_fun(self, IF_reg_df, cal_df):
+        #This is a common algorithm in calculating mask overlapse
+        # zip() gives tupples of all combinations of X and Y. set() outputs set format removes duplicates
+        IF_set  = set(zip(IF_reg_df['X'].round().astype(int), IF_reg_df['Y'].round().astype(int)))
+        Cal_set = set(zip(cal_df['X'].round().astype(int), cal_df['Y'].round().astype(int)))
+    
+        intersection = len(IF_set & Cal_set)#& is only between sets
+        return intersection / len(Cal_set)    
+    
+    def Registration_optimize(self,          
+        IF_threshold,
+        a = 1.0,                  # fixed scale in X
+        c = 1.0,                  # fixed scale in Y
+        step = 1.0,
+        start_X = -30.0,
+        end_X = 30.0,
+        start_Y = -30.0,
+        end_Y = 30.0,
+        plot_result = True,
+        which_channel: str = 'NF'):
+        """
+        Grid search over translation (b, d) with fixed stretching scale (a, c).
+        Returns best (X_shift, Y_shift) and corresponding score.
+        """
+        if which_channel == 'NF':
+           channel = self.nf
+        elif which_channel == 'CGRP':
+           channel = self.cgrp
+        else: raise ValueError(f"channel must be 'NF' or 'CGRP'. Got: {which_channel}")
+     
+        if step <= 0:
+           raise ValueError("step must be positive")
+        # Generate empty data containers for shifts, scores, best shift and best score.
+        x_shifts = np.arange(start_X, end_X + step/2, step)
+        y_shifts = np.arange(start_Y, end_Y + step/2, step)
+        scores = np.full((len(y_shifts), len(x_shifts)), np.nan)          # 2D grid for heatmap       
+        best_score = -np.inf
+        best_shift = (0.0, 0.0)
+        shift_record = []
+        obj_values = []
+
+        mask = self._if_threshold(channel, IF_threshold)
+        IF_df= self._mask_matrix_to_df(mask)
+        for i_x, dx in enumerate(x_shifts):#enumerate output both indices and values
+           for i_y, dy in enumerate(y_shifts):
+                # Apply registration
+                IF_reg = self._registrate_linear(IF_df, a, dx, c, dy)
+
+                # Compute score
+                score = self._registration_obj_fun(IF_reg, self.df_clust)
+                scores[i_y, i_x] = score
+
+                obj_values.append(score)
+                shift_record.append((dx, dy))
+
+                if score > best_score:
+                    best_score = score
+                    best_shift = (dx, dy)
+
+        if plot_result and len(obj_values) > 1:
+            fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(13, 5.5))
+
+            # Heatmap of scores
+            im = ax1.imshow(
+                scores,
+                extent=[x_shifts.min(), x_shifts.max(), y_shifts.min(), y_shifts.max()],
+                origin='lower',
+                aspect='auto',
+                cmap='magma',
+                interpolation='nearest'
+            )
+            ax1.plot(best_shift[0], best_shift[1], 'c*', markersize=18, label='Best')
+            ax1.set_title('Objective function landscape')
+            ax1.set_xlabel('X shift (pixels)')
+            ax1.set_ylabel('Y shift (pixels)')
+            plt.colorbar(im, ax=ax1, label='Overlap ratio')
+
+            # 1D progression (useful for debugging order)
+            ax2.plot(obj_values, '.-', color='teal', lw=1)
+            ax2.set_xlabel('Evaluation #')
+            ax2.set_ylabel('Score')
+            ax2.set_title('Score during grid search')
+            ax2.grid(True, alpha=0.3)
+
+            plt.tight_layout()
+
+
+        return best_shift, best_score
+    
+    
+        
+        
+    
+    def _matrix_to_df(self,
+                  Coordinates: pd.DataFrame,
+                  image: np.ndarray,
+                  name: str = 'value') -> pd.DataFrame:
+        ys = Coordinates['Y'].astype(int).to_numpy()
+        xs = Coordinates['X'].astype(int).to_numpy()
+        cluster= Coordinates['Cluster'].to_numpy()
+        df = pd.DataFrame({'Y': ys, 'X': xs, "Cluster":cluster, name: image[ys, xs] })
+        return df
+    
+    """The updated pixel should be 
+    IF_regi["X1"]= IF_["X"]*a + b
+    IF_regi["Y1"]= IF_["Y"]*c + d
+    Now we know IF_regi["X1"] and IF_regi["Y1"], for they are the calcium imaging coordinates
+    we need to solve IF_["X"] and IF_["Y"] that are the pixels in IF corresponding to the calcium pixel
+    """
+    
+    def Merge_channels_in_df(self, a, b, c, d):
+
+        merged = self.df_clust.copy()
+
+        # calculate the transformed coordinates for indexing
+        x_idx = ((merged["X"] - b) / a).clip(0, self.width-1).astype(int).copy()
+        y_idx = ((merged["Y"] - d) / c).clip(0, self.height-1).astype(int).copy()
+
+        # add IF values
+        merged["NF"] = map_coordinates(self.nf, [y_idx, x_idx], order=1, mode='nearest')
+        merged["CGRP"] = map_coordinates(self.cgrp, [y_idx, x_idx], order=1, mode='nearest')
+
+        return merged
+    
+    
+
+
+"""---------------------------------------------------------------------------------------------------------
+A more efficient way is to do the registration in matrix"""
+
+import cv2
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+
+
+class IFmatchMatrix:
+
+    def __init__(
+        self,
+        Calcium_imaging_df: pd.DataFrame,
+        CGRP_raw: np.ndarray,
+        NF_raw: np.ndarray,
+        Calcium_height: int = 292,
+        Calcium_width: int = 384
+    ):
+
+        self.df_clust = Calcium_imaging_df
+        self.height = Calcium_height
+        self.width = Calcium_width
+
+        # resize IF images
+        self.cgrp = cv2.resize(CGRP_raw, (self.width, self.height),
+                               interpolation=cv2.INTER_AREA)
+
+        self.nf = cv2.resize(NF_raw, (self.width, self.height),
+                             interpolation=cv2.INTER_AREA)
+
+        # build calcium mask once
+        self.cal_mask = np.zeros((self.height, self.width), dtype=np.uint8)
+
+        ys = self.df_clust["Y"].astype(int).to_numpy()
+        xs = self.df_clust["X"].astype(int).to_numpy()
+
+        self.cal_mask[ys, xs] = 1
+
+
+    def _if_threshold(self, image, threshold):
+
+        return (image >= threshold).astype(np.uint8)
+
+
+    def _affine_transform(self, mask, a, b, c, d):
+
+        M = np.array([
+            [a, 0, b],
+            [0, c, d]
+        ], dtype=np.float32)
+
+        transformed = cv2.warpAffine(
+            mask,
+            M,
+            (self.width, self.height),
+            flags=cv2.INTER_NEAREST
+        )
+
+        return transformed
+
+
+    def _registration_score(self, IF_mask):
+
+        overlap = np.sum(IF_mask & self.cal_mask)
+
+        return overlap / np.sum(self.cal_mask)
+
+
+    def Registration_optimize(
+        self,
+        IF_threshold,
+        a=1.0,
+        c=1.0,
+        step=1,
+        start_X=-30,
+        end_X=30,
+        start_Y=-30,
+        end_Y=30,
+        which_channel="NF",
+        plot_result=True
+    ):
+
+        if which_channel == "NF":
+            channel = self.nf
+        elif which_channel == "CGRP":
+            channel = self.cgrp
+        else:
+            raise ValueError("channel must be NF or CGRP")
+
+        IF_mask = self._if_threshold(channel, IF_threshold)
+
+        x_shifts = np.arange(start_X, end_X + step, step)
+        y_shifts = np.arange(start_Y, end_Y + step, step)
+
+        scores = np.zeros((len(y_shifts), len(x_shifts)))
+
+        best_score = -1
+        best_shift = (0, 0)
+
+        for ix, dx in enumerate(x_shifts):
+            for iy, dy in enumerate(y_shifts):
+
+                IF_trans = self._affine_transform(IF_mask, a, dx, c, dy)
+
+                score = self._registration_score(IF_trans)
+
+                scores[iy, ix] = score
+
+                if score > best_score:
+                    best_score = score
+                    best_shift = (dx, dy)
+
+        if plot_result:
+
+            plt.figure(figsize=(6,5))
+            plt.imshow(
+                scores,
+                extent=[x_shifts.min(), x_shifts.max(),
+                        y_shifts.min(), y_shifts.max()],
+                origin="lower",
+                cmap="magma"
+            )
+
+            plt.scatter(best_shift[0], best_shift[1], c="cyan", s=120)
+
+            plt.xlabel("X shift")
+            plt.ylabel("Y shift")
+            plt.title("Registration objective")
+            plt.colorbar(label="overlap ratio")
+
+            plt.show()
+
+        return best_shift, best_score
+
+
+    def Merge_channels_in_df(self, a, b, c, d):
+
+        coords = self.df_clust.copy()
+
+        # inverse transform
+        coords["X"] = (coords["X"] - b) / a
+        coords["Y"] = (coords["Y"] - d) / c
+
+        xs = coords["X"].clip(0, self.width-1).astype(int)
+        ys = coords["Y"].clip(0, self.height-1).astype(int)
+
+        merged = self.df_clust.copy()
+
+        merged["NF"] = self.nf[ys, xs]
+        merged["CGRP"] = self.cgrp[ys, xs]
+
+        return merged
+
+
+
+
+"""Combine the IF with calcium imaging analysis outcome
+A good merge function explaination
+https://www.geeksforgeeks.org/python-pandas-merging-joining-and-concatenating/
+1.  The first step is an "outer" merge of TU and CGRP, the output is all X,Y that 
+    either positive for TU or CGRP, if only positive in TU, in CGRP it will be NA
+2.  The second step is to do a "right" merge that calcium (Position) is on the right.
+    In this way, only pixels of calcium will remain
+    calcium pixels without either TU or CGRP will be NA at corresponding position
+3.  The input is already segmented and registerred (regarding calcium)"""
+def merge_df_channels(IF_TU_regi, IF_CGRP_regi, Calcium):    
+    IF_com =pd.merge(IF_TU_regi.rename(columns={'IF':'TU'})[['X1','Y1','TU']],
+                     IF_CGRP_regi.rename(columns={'IF':'CGRP'})[['X1','Y1','CGRP']], 
+                     how="outer", on=['X1','Y1'])
+    Cal_IF =pd.merge(Calcium[['X','Y','Neuron_indice','Base','Bra','CZP', 'Cap','Kcl']], 
+                     IF_com.rename(columns={'X1':'X','Y1':'Y'}),
+                     how="left", on=['X','Y'])
+    return Cal_IF

calmono/imgimport.py

@@ -0,0 +1,139 @@
+# -*- coding: utf-8 -*-
+"""
+Created on Fri Feb 20 20:14:33 2026
+
+@author: Junxuan Ma
+"""
+
+import glob
+import czifile
+import numpy as np
+import cv2
+import os
+
+#Read confocal files
+"""
+To automate import, match IF (immunofluorescence) with calcium imaging with the same Sample Name.
+Specifically: IF is in a form of "IF_sample_name.czi".
+And Calcium imaging is in a form of "Cal_sample_name.czi".
+The sample name would be "sample_name.czi" .
+Note that the IF_ or Cal_ tag has to be before the same sample name.
+
+All the calcium imaging files and IF files are stored in the folder defined by the input Local_path
+Since the files are very large and there is no memory to store all simutaneously, it has to be read one and analyze, then read the next.
+
+Thus the Auto_ImportCZI contains 2 steps:
+    1. Fetch_Files: list all files representing all samples
+    Inputs (parameters): 
+    --------
+    Local_path: the local directory of the image files
+    Cal_tag: the string pattern in the file name that can be used to distinguish Calcium imaging from IF
+    IF_tag: the string pattern specific for IF file
+        Note: calcium imaging file name can be switched to IF file name
+        by changing Cal_tag to IF_tag 
+    
+    Outputs (attributes):
+    ---------
+    Get_cal_files: a function to call all the calcium imaging file names.
+    Get_if_files: a function to call all the IF file names
+        
+    
+    2. ImportCZI: choose one to import and make it easy for iteration
+    Notice that the IF and calcium imaging file names have to be well matched.
+    The only difference is their tags before the sample name.
+    Inputs (parameters): 
+    --------
+    local_path: the local directory of the image files
+    Cal_name: the filename of one calcium imaging chosen for analysis
+    Cal_tag: the string pattern in the file name that can be used to distinguish Calcium imaging from IF
+    IF_tag: the string pattern specific for IF file
+        Note: calcium imaging file name can be switched to IF file name
+        by changing Cal_tag to IF_tag 
+    
+    Outputs (attributes):
+    ---------
+    Read_if: input which channel index is "CGRP" and which is "NF". 
+        output the CGRP and NF image file in np.ndarray, respectively.
+    Read_cal: output the raw calcium imaging data as np.ndarray
+        and the pixel size of the image in a list of (height, width).
+    
+    
+Note the read_image function needs to be adapted based on the format of image
+For the following analysis the imported calcium imaging data should be np.array and need to have time in 0th dimention
+    
+""" 
+#Step 1, list all files representing all samples
+from pathlib import Path
+class FetchFiles:
+    def __init__(
+        self,
+        local_path: str,
+        cal_tag: str = "Cal",
+        if_tag: str = "IF",
+    ) -> None:
+        self._path = Path(local_path)
+        self._cal_tag = cal_tag
+        self._if_tag = if_tag
+
+        if not self._path.exists():
+            raise FileNotFoundError(f"Path does not exist: {self._path}")
+
+    # ---------- Internal logic ----------
+    def _get_filenames(self, tag: str):
+        return [f.name for f in self._path.glob(f"{tag}*.czi")]
+
+    # ---------- Public API ----------
+    def Get_cal_files(self):
+        return self._get_filenames(self._cal_tag)
+
+    def Get_if_files(self):
+        return self._get_filenames(self._if_tag)
+    
+
+#Step 2, choose one to import and make it easy for iteration
+class ImportCZI():    
+    def __init__(self, 
+                 local_path: str,
+                 Cal_name: str = 'Cal_Donor1_Day2_G5_b5_2.czi',
+                 cal_tag: str = "Cal",
+                 if_tag: str = "IF"):
+        self._path = Path(local_path)
+        self.Cal_name = self._path / Cal_name #Full path object, not just file name
+        self._cal_tag = cal_tag
+        self._if_tag = if_tag
+        
+        #To ensure correspondence, IF path is derived from Cal by changing tag
+        self.IF_name = self.Cal_name.with_name(#Full path object
+            self.Cal_name.name.replace(self._cal_tag, self._if_tag)
+        )#Full path object, not just file name
+        
+        self._if_data = np.squeeze(czifile.imread(self.IF_name))
+        self._cal_data = np.squeeze(czifile.imread(self.Cal_name))
+        
+    # ---------- Internal logic ----------
+    def _read_IF(self, CGRP: int, NF: int) ->tuple[np.ndarray,np.ndarray]:
+        if CGRP >= self._if_data.shape[0] or NF >= self._if_data.shape[0]:
+            raise IndexError("CGRP or NF index out of bounds of channels")
+        return self._if_data[CGRP,:,:], self._if_data[NF,:,:]
+    
+    def _read_Cal(self):
+        """The same as:
+            return np.reshape(self._cal_data,(self._cal_data.shape[0],
+               self._cal_data.shape[1]*self._cal_data.shape[2]))"""
+        return np.reshape(self._cal_data,(self._cal_data.shape[0],-1))
+    
+    def _cal_shape(self):
+        return self._cal_data.shape
+    
+    # ---------- Public API ----------
+    
+    def Read_if(self, CGRP: int, NF: int)->tuple[np.ndarray,np.ndarray]:
+        return self._read_IF(CGRP,NF)
+    
+    def Read_cal(self) -> np.ndarray:
+        return self._read_Cal(), self._cal_shape()
+            
+            
+            
+        
+