interlinked-lab 0.2.0

No project description provided

The Interlinked Module

This module is for neuroscientific computation and analysis with Python submodules and Rust-optimized kernels. This code is developed by Andrej Lozevski for the En Yang Lab at UNC Chapel Hill (2026).

Installation

This module can be installed by running:

pip install interlinked-lab

Submodules

All code is organized into the following submodules:

• utils --- Contains functions for a wide range of uses
• io --- Contains functions for I/O operations and streamlined file use
• form --- Contains functions for manipulating labeled and non-labeled arrays
• stats --- Contains functions for statistical tests and measures
• info --- Contains functions for information theoretic tests and measures
• draw --- Contains functions for data visualization
• config --- Contains methods for updating, resetting, loading, and saving parameter settings for the module's default behaviors and arguments

Each submodule can be used in a program directly or through imports:

# Method 1
import interlinked
print(interlinked.config.defaults())

# Method 2
from interlinked import config
print(config.defaults())

All submodules and their functions/methods are listed below¹:

---

Config

This submodule is a class instance, possessing the following methods and attributes:

Methods

• def defaults(self)
  Lists all config default parameters
  returns: None
  

• def list(self)
  Lists all current config parameters
  returns: None
  

• def configure(self, **kwargs)
  Updates any specified config parameters
  Default parameters cannot be changed to a different type, but custom parameters have no restrictions
  returns: None
  

• def reset(self)
  Resets config parameters to defaults
  returns: None
  

• def save(self)
  Saves current config parameters in the temp directory
  Overwrites any pre-existing saved config parameters
  returns: None
  

• def load(self)
  Loads config parameters saved in the temp directory
  If no saved parameters are found, throws an Exception and loads defaults
  returns: None
  

Attributes

• TEMP_DIR: Path = /tmp/interlinked
  where the temp directory is located (DO NOT CHANGE)
  

• TEMP_PREFIX: str = "__temp__"
  file prefix given to temporary files (DO NOT CHANGE)
  

• TEMP_SUFFIX: str = ".dat"
  file suffix given to temporary files (DO NOT CHANGE)
  

• CLEAR_TEMP: bool = False
  see io.check_temp() below

• BATCH_SIZE: int = 1000
  size of batches for parallelism
  

• NUM_WORKERS: int = 8
  number of workers for parallelism
  

• NUM_BINS: int = 5
  number of bins for binning and digitization
  

• NUM_KNNS: int = 8
  number of nearest neighbors for KNN operations
  

• NUM_ITER: int = 1_000_000
  number of iterations for monte carlo simulation and bootstrap resampling operations
  

• ALPHA1: float = 0.05
  α₁ for statistical tests
  

• ALPHA2: float = 0.01
  α₂ for statistical tests
  

• ALPHA3: float = 0.001
  α₃ for statistical tests
  

• ALPHA4: float = 0.0001
  α₄ for statistical tests
  

• RADIUS: int
  radius used for graph theory and nearest neighbors operations
  

• MIN_SIZE: int
  minimum node count for graph theory operations
  

Any ALL-CAPS variable listed below can be assumed as a parameter found in the default config instance.

Utils

• def digitize(x, n, dtype=np.int32)
  Digitizes an input array into discretized values from a given number of fixed-width bins
  x: ndarray (ndim of 1) --- input array to digitize
  n: int --- desired range of the output array
  dtype: dtype --- target dtype of output array
  returns: ndarray (ndim of 1)
  

• def interpolate(x, xp, fp)
  Interpolates an input array with vectorized calculation
  x: ndarray (ndim of 1) --- x-values of target data
  xp: ndarray (ndim of 1) --- x-values of input data
  fp: ndarray (ndim of 2) --- y-values of input data
  returns: ndarray (ndim of 2)
  

• def dff(raw, downsample=1, percentile=20, window=300)
  Calculates the ΔF/F of a calcium trace using a percentile filter and a sliding window
  raw: ndarray (ndim of 1 or 2) --- input array for which to calculate ΔF/F, assuming shape (cells, timepoints)
  downsample: int --- downsampling factor (setting to 1 prevents downsampling)
  percentile: float --- percentile with which to calculate the baseline of the time series
  window: int --- sliding window size with which to calculate the baseline of the time series
  returns: ndarray (ndim of raw)
  

• def divisor(arr, minimum=1, default_positive=True)
  Converts an input array into a safe divisor for array division, keeping sign and preventing unintentional mulitiplication
  arr: ndarray --- input array to convert
  minimum: float --- minimum magnitude allowed above or below 0 (prevents multiplication)
  default_positive: bool --- used to set any 0 in the input array to ±minimum
  returns: ndarray
  

---

IO

• def find_file(path, pattern, allow_multiple=False)
  Returns a file from a directory with a specified glob pattern
  path: str | Path --- directory to search for the target file
  pattern: str --- glob pattern with which to search
  allow_multiple: bool --- whether to return an error if mulple files are found with the pattern
  returns: Path | list[Path]
  

• def load_file(path, pattern, allow_pickle=False)
  Finds and loads data from a single .npy, .tif, .h5, or .hdf5 file from a directory with a specified glob pattern
  path: str | Path --- directory to search for the target file
  pattern: str --- glob pattern with which to search
  allow_pickle: bool --- if a .npy file is found, whether to allow pickling
  returns: file data (depends on file type)
  

• def check_temp(clear=False)
  Checks if there are any temporary files in your temp directory
  clear: bool --- deletes any temporary files in the temp directory
  returns: None
  

• def clear_temp(notify=True)
  Clears any temporary files in the temp directory
  notify: bool --- whether to log that files were cleared
  returns: None
  

• class Memmap(shape, dtype)
  Streamlines handling of numpy memmap objects in the temp directory
  shape: tuple() --- shape of the stored array
  dtype: dtype --- dtype of the stored array
  

  • def save(self, data)
    Saves a memmap object in the temp directory
    data: ndarray --- numpy array to save into a memmap file
    returns: None
    

  • def load(self, read_only=True)
    Loads a memmap object's data
    read_only: bool --- whether the memmap is loaded with read or read/write permissions
    returns: numpy.Memmap
    

  • def delete(self)
    Deletes a memmap object from the temp directory
    returns: None
    

• def load_fps(path)
  Loads the fps of from an xml file found in the specified directory
  path: str | Path --- directory to search for the target file
  returns: float
  

• def load_resolution(path)
  Loads the (z,y,x) resolution from a txt file found in the specified directory
  path: str | Path --- directory to search for the target file
  returns: tuple(float, float, float)
  

• def load_metadata(path)
  Loads the (t,z,y,x) resolution from txt and xml files found in the specified directory
  path: str | Path --- directory to search for the metadata
  returns: tuple(float, float, float, float)
  

• def load_suite2p_data(path, mode="raw")
  Loads the labeled volume of all ROIs, cell activity traces, time-averaged brainmap, data shape, and ops from a Suite2p-containing directory
  Requires the existence of stat.npy, F.npy, and ops.npy files
  path: str | Path --- directory containing Suite2p files
  mode: str ("raw", "dff" "percentile") --- method of ΔF/F calculation
  returns:
  

  • ndarray (ndim of 3) --- labeled volume (z,y,x)
    
  • ndarray (ndim of 2) --- cell traces (c,t)
    
  • ndarray (ndim of 3) --- brainmap (z,y,x)
    
  • tuple(int, int, int, int, int) --- data shape (Lc,Lt,Lz,Ly,Lx)
    
  • Suite2p Ops
    

• def load_voluseg_data(path, mode="raw")
  Loads the labeled volume of all ROIs, cell activity traces, time-averaged brainmap, and data shape from a VoluSeg-containing directory
  Requires the existence of volume0.hdf5 and cells0_clean.hdf5 files
  path: str | Path --- directory containing VoluSeg files
  mode: str ("raw", "dff", "percentile", "voluseg") --- method of ΔF/F calculation
  returns:
  

  • ndarray (ndim of 3) --- labeled volume (z,y,x)
    
  • ndarray (ndim of 2) --- ΔF/F cell traces (c,t)
    
  • ndarray (ndim of 3) --- brainmap (z,y,x)
    
  • tuple(int, int, int, int, int) --- data shape (Lc,Lt,Lz,Ly,Lx)
    

• def load_combined_data(path, file="segdata.h5")
  Loads the labeled volume of all ROIs, ROI activity traces, time-averaged brainmap, and data shape from a Combined-Segmentation-containing directory
  Requires the existence of a segdata.h5 file
  path: str | Path --- directory containing combined segdata file
  file: str --- name of combined segdata file
  returns:
  

  • ndarray (ndim of 3) --- labeled volume (z,y,x)
    
  • ndarray (ndim of 2) --- ROI traces (r,t)
    
  • ndarray (ndim of 3) --- brainmap (z,y,x)
    
  • ndarray ([int, int, int, int, int]) --- data shape (Lr,Lc,Lt,Lz,Ly,Lx)
    
  • ndarray ([float, float, float, float]) --- metadata (Rt,Rz,Ry,Rx)
    
  • ndarray (ndim of 1) --- Ids of Suite2p-identified ROIs
    
  • ndarray (ndim of 1) --- Ids of VoluSeg-identified ROIs
    
  • ndarray (ndim of 2) --- rigid transformation matrix for alignment
    
  • str ("suite2p", "voluseg") --- reference brainmap used for alignment
    

• def build_trials(drift)
  Builds a trials-by-timepoints (Ln,Ltt) array of timepoint indices
  drift: ndarray (ndim of 1) --- drift time series, used to distinguish trials
  min_length: int --- length cutoff to distinguish go period from pulses
  returns: ndarray (ndim of 2)
  

---

Form

• def form_volume(img, shape)
  Forms a volumetric array from a tiled image, using the specified target shape
  img: ndarray (ndim of 2) --- original tiled image
  shape: tuple(int, int, int) --- shape of target volume (z,y,x)
  returns: ndarray (ndim of 3)
  

• def form_tiles(vol, shape)
  Forms a tiled image from a volume, using the specified target shape
  vol: ndarray (ndim of 3) --- original volume
  shape: tuple(int, int) --- shape of target tiled image
  returns: ndarray (ndim of 2)
  

• def label_rois(stat, shape)
  Labels all ROIs in a volume using a stat.npy file
  stat: list[dict] --- list of pickled and sparse-labeled cells
  shape: tuple(int, int, int) --- shape of the target volume
  returns: ndarray (ndim of 3)
  

• def adjust_rois(arr)
  Removes missing labels in a labeled array by shifting ROIs
  arr: ndarray --- labeled array
  returns:
  

  • ndarray --- relabled array
    
  • ndarray (ndim of 1) --- array of indices of the original unique labels
    
  • list[int] --- list of missing indices from the original array
    

• def remove_rois(arr, rois, keep=False)
  Removes the specified labels from a labeled array, leaving missing labels
  arr: ndarray --- labeled array
  rois: list[int] | ndarray (ndim of 1) --- selected labels
  keep: bool --- if True, remove whatever rois are not selected, and if False, remove whatever rois are selected
  returns: ndarray
  

• def validate_rois(rois, Lc=0, throw_err=True)
  Checks if all ROIs in a labeled array are valid and without gaps
  rois: ndarray --- labeled array
  Lc: int --- number of expected labels excluding background
  throw_err: bool --- throw an error if validation fails, otherwise return True/False
  returns: bool or None
  

• def weight_rois(rois, weights)
  Substitutes a labeled array with each label's corresponding weight
  rois: ndarray --- labeled array
  weights: list[float] | ndarray (ndim of 1) --- weights corresponding to each label
  returns: ndarray
  

• def align_arrays(arr, ref, factor=100, order=3)
  Aligns one array to a reference array of same dimensionality
  arr: ndarray --- input array
  ref: ndarray --- reference array
  factor: int --- precision of alignment
  returns:
  

  • ndarray --- aligned input array
    
  • ndarray --- transform array
    

---

Stats

• def pearson_corr(x, y)
  Calculates the Pearson Correlation and its p-value for two variables
  x: ndarray (ndim of 1)
  y: ndarray (ndim of 1)
  returns: tuple(float, float) --- ρ and p-value
  

• def spearman_corr(x, y)
  Calculates the Spearman Rank Correlation and its p-value for two variables
  x: ndarray (ndim of 1)
  y: ndarray (ndim of 1)
  returns: tuple(float, float) --- ρ and p-value
  

• def phi_coef(x, y)
  Calculates the Phi Coefficient and its p-value for two binary variables
  x: ndarray (ndim of 1, bool)
  y: ndarray (ndim of 1, bool)
  returns: tuple(float, float) --- φ and p-value
  

• def quantile_bins(x, n_bins=NUM_BINS)
  Calculates the bin edges for a specified number of quantile bins
  x: ndarray
  n_bins: int
  returns: ndarray (ndim of 1)
  

---

Info

• def hist_H(x)
  Calculates the Shannon Entropy of a binned variable from a list of bin counts
  x: ndarray (ndim of 1)
  returns: float
  

• def KL_H(x, k)
  Calculates the Shannon Entropy of a continuous variable using the Kozachenko-Leonenko estimator
  x: ndarray (ndim of 1) --- input array
  k: int --- number of nearest neighbors
  returns: float
  

• def disc_MI(x, y, normalized=False, n_bins=NUM_BINS, bin_type=BIN_TYPE)
  Calculates the Mutual Information of two discrete variables
  x: ndarray (ndim of 1)
  y: ndarray (ndim of 1)
  normalized: bool
  n_bins: int | list[int] --- number of bins with which to discretize x and y
  bin_type: str = 'fixed' | 'quantile' --- type of bins with which to discretize x and y
  returns: float
  

• def disc_CMI(x, y, z, normalized=False, n_bins=NUM_BINS, bin_type=BIN_TYPE)
  Calculates the Conditional Mutual Information of two discrete variables conditioned on a third variable
  x: ndarray (ndim of 1)
  y: ndarray (ndim of 1)
  z: ndarray (ndim of 1)
  normalized: bool
  n_bins: int | list[int] --- number of bins with which to discretize x, y, and z
  bin_type: str = 'fixed' | 'quantile' --- type of bins with which to discretize x, y, and z
  returns: float
  

• def disc_II(x, y, z, normalized=False, n_bins=NUM_BINS, bin_type=BIN_TYPE)
  Calculates the Interaction Information of three discrete variables
  x: ndarray (ndim of 1)
  y: ndarray (ndim of 1)
  z: ndarray (ndim of 1)
  normalized: bool
  n_bins: int | list[int] --- number of bins with which to discretize x, y, and z
  bin_type: str = 'fixed' | 'quantile' --- type of bins with which to discretize x, y, and z
  returns: float
  

• def KSG_MI(x, y, k=NUM_BINS, normalized=False)
  Calculates the Mutual Information of two continuous variables using the Kraskov-Stoegbauer-Grassberger estimator
  x: ndarray (ndim of 1)
  y: ndarray (ndim of 1)
  k: int
  normalized: bool
  returns: float
  

• def KSG_CMI(x, y, z, normalized=False, n_bins=NUM_BINS, bin_type=BIN_TYPE)
  Calculates the Conditional Mutual Information of two continuous variables conditioned on a third variable using the Kraskov-Stoegbauer-Grassberger estimator
  x: ndarray (ndim of 1)
  y: ndarray (ndim of 1)
  z: ndarray (ndim of 1)
  normalized: bool
  n_bins: int | list[int] --- number of bins with which to discretize x, y, and z
  bin_type: str = 'fixed' | 'quantile' --- type of bins with which to discretize x, y, and z
  returns: float
  

• def KSG_II(x, y, z, normalized=False, n_bins=NUM_BINS, bin_type=BIN_TYPE)
  Calculates the Interaction Information of three discrete variables using the Kraskov-Stoegbauer-Grassberger estimator
  x: ndarray (ndim of 1)
  y: ndarray (ndim of 1)
  z: ndarray (ndim of 1)
  normalized: bool
  n_bins: int | list[int] --- number of bins with which to discretize x, y, and z
  bin_type: str = 'fixed' | 'quantile' --- type of bins with which to discretize x, y, and z
  returns: float
  

---

License

MIT

1. Only functions built for typical users are shown below. Additional functions not shown here are considered peripheral and should only be used after reading the source code. ↩