htsimaging 1.0.5

High-Throughput Single-cell Imaging analysis.

htsimaging

High-Throughput Single-cell Imaging analysis.
Examples · Explore the API

Examples

📈 Single-cell protein abundance and its normalization
📈 Single-cell protein abundance by marker localization
🖼️ Visualization of the images.
📈 Quantitative analysis of endocytosis.
📈 Single-particle tracking (SPT).
📈 Calculating the recovery rate from a bleach-chase data

Installation

pip install htsimaging              # with basic dependencies  

With additional dependencies as required:

pip install htsimaging[spt]         # for the analysis of the Single-Particle Tracking e.g. endocytosis.

How to cite?

1. Using BibTeX:

@software{Dandage_htsimaging,
  title   = {htsimaging: High-Throughput Single-cell Imaging analysis in python},
  author  = {Dandage, Rohan},
  year    = {2023},
  url     = {https://zenodo.org/doi/10.5281/zenodo.3697134},
  version = {v1.0.5},
  note    = {The URL is a DOI link to the permanent archive of the software.},
}

2. DOI link: , or

3. Using citation information from CITATION.CFF file.

Future directions, for which contributions are welcome

• Command-line usage.

Similar projects

• https://github.com/vanvalenlab/deepcell-tf
• https://github.com/junlabucsd/napari-mm3

API

module htsimaging.bleach_chase

module htsimaging.bleach_chase.stat

Statistical analysis of the bleach-chase

---

function exp1

exp1(x, lag, amplitude, rate)

One-term exponential.

Parameters:

• x (list): input vector
• lag (float): lag
• amplitude (float): amplitude
• rate (float): rate

---

function get_scores

get_scores(df: DataFrame) → DataFrame

Calculate the rates other parameters.

Parameters:

• df (pd.DataFrame): input table.

Returns:

• pd.DataFrame: table with the parameters.

module htsimaging.endocytosis.io

Processing of the paths of input images to create configurations and metadata.

---

function make_project_cfg

make_project_cfg(
    prjd: str,
    output_dir_path: str,
    bright_fn_marker: str = None,
    segmented_fn_marker: str = None,
    magnification: int = None,
    image_ext: str = 'tif',
    cores: int = 1,
    test: bool = False,
    force: bool = False
) → dict

Make the confguration for the analysis run.

Args:

• prjd (str): path to the directory with the images.
• output_dir_path (str): output directory path.
• bright_fn_marker (type): marker in the path of the bright field images.
• segmented_fn_marker (type): marker in the path of the segmented images.
• cores (int, optional): number of cores. Defaults to 1.
• test (bool, optional): test-mode. Defaults to False.
• force (bool, optional): over-write theoutputs. Defaults to False.

Returns:

• dict: metadata

Notes:

Infer the magnification from the filenames: if 'T1C1' in cfg['bright_fn_marker']: cfg['magnification']=150 elif cfg['bright_fn_marker']=='_t': cfg['magnification']=100

---

function make_cell_cfg

make_cell_cfg(
    cfg: dict,
    frames: list,
    cells: list,
    trial: str,
    celli: int,
    cellbox: list,
    params_get_signal_summary_by_roi: dict = {'xy_center': None, 'width': 20, 'fun_summary_frame': 'min', 'fun_summary_frames': 'median'},
    filterby_centroid: bool = False,
    scale_signal_cytoplasm: float = 1.5,
    test: bool = False,
    force: bool = False
) → dict

Make the configuration for an individual cell.

Args:

• cfg (dict): metadata.
• frames (list): list of frames.
• cells (list): list of cells.
• trial (str): trial name.
• celli (int): index of the cell.
• cellbox (list): bounding box of the cell
• params_get_signal_summary_by_roi (dict, optional): parameters for the aggregation of the values at the ROI. Defaults to {'xy_center':None,'width':20, 'fun_summary_frame':'min', 'fun_summary_frames':'median' }.
• test (bool, optional): test-mode. Defaults to False.
• force (bool, optional): over-write the output. Defaults to False.

Returns:

• dict: metadata

module htsimaging.endocytosis

module htsimaging.endocytosis.vid

To make the video of the timelapse images.

---

function make_gif

make_gif(
    cellcfg=None,
    frames: list = None,
    t_cor: DataFrame = None,
    img_bright=None,
    outd: str = None,
    particle2color: dict = None,
    test: bool = False,
    force: bool = False
)

Make a .gif file out of frames.

module htsimaging.endocytosis.viz

Visualizations.

---

function plot_properties_cell

plot_properties_cell(cellcfg, df2, cols_colorby, colx='x', coly='y')

Plot properties of the cell.

Args:

• cellcfg (type): config of a cell.
• df2 (type): input dataframe.
• cols_colorby (type): columns to color by.
• colx (str, optional): column with the x values. Defaults to 'x'.
• coly (str, optional): column with the y values. Defaults to 'y'.

---

function image_locate_particles

image_locate_particles(
    df1: DataFrame,
    frame,
    img_region,
    annotate_particles: str = False,
    fig=None,
    ax: Axes = None
) → Axes

Plot image with particles.

Args:

• df1 (pd.DataFrame): input dataframe.
• frame (type): image frame.
• img_region (type): regions in the image.
• annotate_particles (str, optional): annotate the paticles or not. Defaults to False.
• fig (type, optional): figure object. Defaults to None.
• ax (plt.Axes, optional): subplot object. Defaults to None.

Returns:

• plt.Axes: description

---

function image_trajectories

image_trajectories(
    dtraj: DataFrame,
    img_gfp=None,
    img_bright=None,
    label: bool = True,
    fig=None,
    ax: Axes = None
) → Axes

Plot trajectories.

Args:

• dtraj (pd.DataFrame): input dataframe with the trajectories.
• img_gfp (type, optional): channel image e.g. GFP. Defaults to None.
• img_bright (type, optional): segmentation image e.g. bright field. Defaults to None.
• label (bool, optional): label. Defaults to True.
• fig (type, optional): figure object. Defaults to None.
• ax (plt.Axes, optional): subplot object. Defaults to None.

Returns:

• plt.Axes: subplot

---

function plot_moving_particles

plot_moving_particles(
    t_cor: DataFrame,
    img_bright=None,
    frame=None,
    framei: int = 0,
    particle2color=None,
    test: bool = False,
    outd: str = None
)

Plot moving particles.

Args:

• t_cor (pd.DataFrame): input table
• img_bright (type, optional): segmentation raw image (e.g. bright field). Defaults to None.
• frame (type, optional): image frame. Defaults to None.
• framei (int, optional): image frame index. Defaults to 0.
• particle2color (type, optional): particle-wise colors. Defaults to None.
• test (bool, optional): test-mode. Defaults to False.
• outd (str, optional): path to the output directory. Defaults to None.

module htsimaging.lib.io

I/O

---

function read_image

read_image(imp: str)

Read image.

Args:

• imp (str): path to the image file.

Returns: np.array

TODOs: For a tiff file: from skimage.external import tifffile

---

function arr2vid

arr2vid(
    arr_list: list,
    regions: list,
    kins_mean: float,
    vid_fh: str,
    xpixels: list,
    ypixels: list,
    dpi: int = 100
) → str

From array to video.

Args:

• arr_list (list): list of frames.
• regions (list): regions
• kins_mean (float): kinetics
• vid_fh (str): video file path
• xpixels (list): pixels allong x-axis.
• ypixels (list): pixels allong y-axis.
• dpi (int, optional): DPI resolution. Defaults to 100.

Returns:

• str: path of the video

---

function makevid

makevid(
    gfp_list_stb: list,
    brf_list_stb: list,
    cmap_gfp: str,
    cmap_brf: str,
    vid_fh: str,
    conditionn: int = None,
    interval=None,
    dpi: int = 300
) → str

Convert to a video.

Args:

• gfp_list_stb (list): channel (e.g. GFP) images.
• brf_list_stb (list): segmented (e.g. bright-field) images.
• cmap_gfp (str): colormap for the channel images.
• cmap_brf (str): colormap for the segmented images.
• vid_fh (str): path to the video file.
• conditionn (int, optional): title. Defaults to None.
• interval (type, optional): inerval of the frames. Defaults to None.
• dpi (int, optional): DPI resolution. Defaults to 300.

Returns:

• str: path to the video file.

---

function nd2arr_list

nd2arr_list(nd_dh: str = None, nd_fns: list = [], nd_fh: str = None) → list

Raw image to list of arrays.

Args:

• nd_dh (str, optional): directory containing raw files e.g. nd2. Defaults to None.
• nd_fns (list, optional): file names. Defaults to [].
• nd_fh (str, optional): path to the files. Defaults to None.

Returns:

• list: list of arrays

---

function to_csv

to_csv(
    fh_xls='../test/test.xlsx',
    nd2_dh='/media/Transcend/20160219_000356_267',
    cores=16
)

Convert nd2 files to csv using parallel processing.

Args:

• fh_xls (str, optional): metadata file. Defaults to '../test/test.xlsx'.
• nd2_dh (str, optional): path of the directory containing raw images. Defaults to "/media/Transcend/20160219_000356_267".
• cores (int, optional): number of cores. Defaults to 16.

module htsimaging.lib

module htsimaging.lib.stat

Statistics.

---

function power

power(x, A, B)

power law equation.

---

function power_residuals

power_residuals(p, y, x)

Deviations of data from fitted 4PL curve

---

function power_peval

power_peval(x, p)

Evaluated value at x with current parameters.

---

function line

line(x, m, C)

power law equation.

---

function line_residuals

line_residuals(p, y, x)

Deviations of data from fitted 4PL curve

---

function line_peval

line_peval(x, p)

Evaluated value at x with current parameters.

---

function logistic4

logistic4(x, A, B, C, D)

---

function logistic4_residuals

logistic4_residuals(p, y, x)

Deviations of data from fitted 4PL curve

---

function logistic4_peval

logistic4_peval(x, p)

Evaluated value at x with current parameters.

---

function logistic5

logistic5(x, A, B, C, D, E)

---

function logistic5_residuals

logistic5_residuals(p, y, x)

Deviations of data from fitted 4PL curve

---

function logistic5_peval

logistic5_peval(x, p)

Evaluated value at x with current parameters.

---

function fit_power

fit_power(x, y, p0: list = [0, 1], plot: bool = False)

Fit power law.

Args:

• x (vector-like): x values.
• y (vector-like): y values.
• p0 (list, optional): starting parameters. Defaults to [0, 1].
• plot (bool, optional): to plot or not. Defaults to False.

Returns:

• tuple: outputs.

---

function fit_line

fit_line(x, y, p0: list = [0, 1], plot: bool = False) → tuple

Fit power law.

Args:

• x (vector-like): x values.
• y (vector-like): y values.
• p0 (list, optional): description. Defaults to [0, 1].
• plot (bool, optional): description. Defaults to False.

Returns:

• tuple: outputs

---

function get_slope

get_slope(df: DataFrame, ds: Series) → float

Get slope for a section of the line.

Args:

• df (pd.DataFrame): input dataframe.
• ds (pd.Series): section of the line.

Returns:

• float: slope.

---

function get_inflection_point

get_inflection_point(df: DataFrame, threshold_slope: float = 0.25) → DataFrame

Get inflation point.

Args:

• df (pd.DataFrame): input dataframe.
• threshold_slope (float, optional): threshold on the slope. Defaults to 0.25.

Returns:

• pd.DataFrame: output dataframe.

module htsimaging.lib.utils

Utilities for the image processing.

---

function filterframe

filterframe(frame, cutoff: float = 0)

Filter a frame.

Args:

• frame (array-like): input frame.
• cutoff (float, optional): cutoff on the values. Defaults to 0.

Returns:

• array-like: filtered frame.

---

function filterframes

filterframes(frames: list, cutoff: float = 0) → list

Filter the frames.

Args:

• frames (list): list of frames.
• cutoff (float, optional): threshold on the values. Defaults to 0.

Returns:

• list: list of frames.

---

function get_data_by_regions

get_data_by_regions(
    regions: list,
    img=None,
    prop_type: str = 'area'
) → DataFrame

Get properties by regions.

Args:

• regions (list): list of the regions.
• img (array-like, optional): input image. Defaults to None.
• prop_type (str, optional): property type. Defaults to 'area'.

Returns:

• pd.DataFrame: output dataframe.

---

function filter_regions

filter_regions(
    regions: list,
    kind='labeled',
    img=None,
    prop_type: str = 'area',
    mn: float = 0,
    mx: float = 0,
    test: bool = False,
    plotp: str = None
) → list

Filter regions.

Args:

• regions (np.array): segmented image, labeled with measure.label(regions).
• img (array-like, optional): image. Defaults to None.
• prop_type (str, optional): property type. Defaults to 'area'.
• mn (float, optional): minimum value. Defaults to 0.
• mx (float, optional): maximum value. Defaults to 0.
• test (bool, optional): test the filtering. Defaults to False.
• plotp (str, optional): path to the plot. Defaults to None.

Raises:

• ValueError: img is required if filtering is t be done by the intensity.

Returns:

• list: list of the filtered regions.

Notes:

Prefer regionprops_table which is new in sklean's version 0.16.

---

function smoothen

smoothen(img)

Smoothen the image.

Args:

• img (array-like): input image.

Returns:

• array-like: output image

---

function smoothenframes

smoothenframes(frames: list) → list

Smoothen the images.

Args:

• frames (list): list of frames.

Returns:

• list: list of frames.

---

function get_regions

get_regions(img)

Get regions.

Args:

• img (array-like): input image

---

function raw2phasecorr

raw2phasecorr(arr_list: list, clip: int = 0) → list

Correct for the relative translative offset by phase correlation between images.

Args:

• arr_list (list): list of frames.
• clip (int, optional): threshold. Defaults to 0.

Returns:

• list: output frames.

---

function phasecorr_with

phasecorr_with(imlist: list, imlist2: list = None, clip: int = 0)

Correct for the relative translative offset by phase correlation with a set of given images.

Args:

• imlist (list): test images
• imlist2 (list, optional): reference images. Defaults to None.
• clip (int, optional): threshold. Defaults to 0.

Returns:

• list: corrected images.

---

function imlistcropper

imlistcropper(imlist: list, loci: int) → list

Crop a list of images.

Args:

• imlist (list): list of images.
• loci (int): locations.

Returns:

• list: output images.

---

function imclipper

imclipper(im_stb, clip: float)

Crop an image.

Args:

• im_stb (array-like): input image
• clip (float): threshold.

---

function get_cellprops

get_cellprops(
    regions,
    intensity_imgtype2img,
    properties=['area', 'bbox_area', 'convex_area', 'eccentricity', 'equivalent_diameter', 'euler_number', 'extent', 'filled_area', 'label', 'major_axis_length', 'max_intensity', 'mean_intensity', 'min_intensity', 'minor_axis_length', 'orientation', 'perimeter', 'solidity', 'centroid']
) → DataFrame

Get cell properties.

Args:

• regions (list): regions in a frame.
• intensity_imgtype2img (type): intensities.
• properties (list, optional): description. Defaults to ['area', 'bbox_area', 'convex_area', 'eccentricity', 'equivalent_diameter', 'euler_number', 'extent', 'filled_area', 'label', 'major_axis_length', 'max_intensity', 'mean_intensity', 'min_intensity', 'minor_axis_length', 'orientation', 'perimeter', 'solidity', 'centroid', ].

Returns:

• pd.DataFrame: output dataframe.

---

function get_signal_summary_by_roi

get_signal_summary_by_roi(
    cellframes: list,
    xy_center: tuple = None,
    width: int = 20,
    fun_summary_frame: str = 'min',
    fun_summary_frames: str = 'median'
)

Place of the roi in the image is defined by

Args:

• cellframes (list): list of frames.
• xy_center (tuple, optional): position of the center. Defaults to None.
• width (int, optional): width of the ROI. Defaults to 20.
• fun_summary_frame (str, optional): function to summarise a frame. Defaults to 'min'.
• fun_summary_frames (str, optional): function to summarise a list of frames. Defaults to 'median'.

Returns: summary value

module htsimaging.segment

module htsimaging.segment.region

Processing of the segmented regions.

---

function segmentation2cells

segmentation2cells(
    imsegp: str,
    kind: str = 'yeast',
    fiterby_border_thickness: int = None,
    magnification: int = 100,
    test: bool = False,
    **kws: dict
) → list

Segment the image to the single cells.

Args:

• imsegp (str): description
• fiterby_border_thickness (int, optional): description. Defaults to 100.
• magnification (int, optional): description. Defaults to 100.
• plotp (str, optional): description. Defaults to None.

Returns:

• list: description

Examples:

1. Parameters: prop_type='area',mn=100,mx=8000 at 1.5X prop_type='area',mn=1500,mx=12000

---

function get_cellboxes

get_cellboxes(
    regions: list,
    cellbox_width: int = 150,
    test: bool = False
) → list

Get the bounding boxes of the cells.

Args:

• regions (list): regions.
• cellbox_width (int, optional): width of the bounding box of the cell. Defaults to 150.
• test (bool, optional): test-mode. Defaults to False.

Returns:

• list: list of the bounding boxes for cells.

---

function arr_list2regions

arr_list2regions(arr_list: list, time_increment: int) → tuple

Parameterized cell-segmentation for the time lapse images.

Args:

• arr_list (list): frames of images.
• time_increment (int): time interval.

Returns:

• tuple: regions and table with intensities.

module htsimaging.spt.io

I/O

---

function to_frames

to_frames(input_path: str, channeli=None)

Convert to frames.

Args:

• input_path (str): path to the raw data.

Returns:

• list: list of frames.

---

function expt_dh2expt_info

expt_dh2expt_info(expt_dh: str) → DataFrame

Make configuration using the directory structure for an experiment.

Args:

• expt_dh (str): str

Returns:

• pd.DataFrame: output dataframe.

---

function createinfo

createinfo(expt_dh: str) → str

Create information file.

Args:

• expt_dh (str): path to the directory containing the raw data.

Returns: path to the file containing the metadata.

module htsimaging.spt

module htsimaging.spt.stat

Statistical analysis of the single particle tracking.

---

function test_locate_particles

test_locate_particles(
    cellcfg: dict,
    params_locate: dict,
    frame=None,
    force: bool = False,
    test: bool = False
) → bool

Test locating of the particles.

Args:

• cellcfg (dict): the cell level configuration.
• params_locate (dict): parameters provided for the location.
• frame (np.array, optional): image frame. Defaults to None.
• force (bool, optional): over-write the outputs. Defaults to False.
• test (bool, optional): test mode. Defaults to False.

Returns: bool

---

function to_msd

to_msd(
    frames: list,
    coff_intesity_perc: float = 75,
    diameter=11,
    cores: int = 4,
    test: bool = False
) → tuple

MSD from the nd file.

Args:

• frames (str): 2D frames.

Returns:

• tuple: outputs.

---

function trim_returns

trim_returns(df1: DataFrame) → DataFrame

Trim images.

Args:

• df1 (pd.DataFrame): input dataframe.

Returns:

• pd.DataFrame: output dataframe.

---

function fill_frame_jumps

fill_frame_jumps(df1: DataFrame, jump_length) → DataFrame

Fill the frame jumps.

Args:

• df1 (pd.DataFrame): input dataframe.
• jump_length (type): length of the jump.

Returns:

• pd.DataFrame: output dataframe.

---

function cellcfg2distances

cellcfg2distances(
    cellcfg: dict,
    params: dict,
    subtract_drift: bool = False,
    test: bool = False,
    force: bool = False
)

Calculate distances from cell configuration.

Args:

• cellcfg (dict): configuration
• params (type, optional): parameters. Defaults to { 'locate':{'diameter':11, # round to odd number 'noise_size':1, 'separation':15, 'threshold':4000, 'preprocess':True, 'invert':False, 'max_iterations':50, 'percentile':0, 'engine':'numba', }, 'link_df':{ 'search_range':5, 'memory':1, 'link_strategy':'drop',}, 'filter_stubs':{'threshold':4}, 'get_distance_from_centroid':{'center':[75,75]}, }.
• force (bool, optional): over-write the outputs. Defaults to False.

---

function apply_cellcfgp2distances

apply_cellcfgp2distances(cellcfgp: str)

Wrapper around cellcfg2distances for multiprocessing.

Args:

• cellcfgp (str): path to the configuration file.

---

function get_distance_from_centroid

get_distance_from_centroid(df1: DataFrame, center: list = [75, 75]) → DataFrame

Get distance from the centroid.

Args:

• df1 (pd.DataFrame): input dataframe.
• center (list, optional): center point. Defaults to [75,75].

Returns:

• pd.DataFrame: output dataframe.

---

function distance_effective

distance_effective(particle, frame1, frame2, t_cor: DataFrame) → float

Effective distance between frames.

Args:

• particle : particle
• frame1 (np.array): a frame.
• frame2 (np.array): another frame.
• t_cor (pd.DataFrame): t_cor.

Returns:

• float: distance

---

function get_distance_travelled

get_distance_travelled(t_cor: DataFrame) → DataFrame

Distance travelled.

Args:

• t_cor (pd.DataFrame): input dataframe.

Returns:

• pd.DataFrame: output dataframe.

module htsimaging.viz.colors

GLobally used variables.

Global Variables

• r
• g
• b
• cmap_gfp_list

module htsimaging.viz.image

Visualization of the images.

---

function image_background

image_background(
    img_region=None,
    img=None,
    cmap: str = 'binary_r',
    alpha=1,
    linewidths=1,
    colors='cyan',
    kws_region={},
    show_scalebar=None,
    scalebar_color: str = 'w',
    show_cbar: bool = True,
    test=False,
    ax=None,
    **kws_img
) → Axes

Plot the image, to be used as a background to the annotations.

Args:

• img_region (type, optional): segmentation image. Defaults to None.
• img (type, optional): image with intensity values. Defaults to None.
• cmap (str, optional): colormap name. Defaults to 'binary_r'.
• alpha (int, optional): transparency. Defaults to 1.
• linewidths (int, optional): segmentation contour line width. Defaults to 1.
• colors (str, optional): color of the segmentation line. Defaults to 'cyan'.
• kws_region (dict, optional): parameters provided to the segmentation plot. Defaults to {}.
• show_scalebar (type, optional): show scale bar. Defaults to None.
• scalebar_color (str, optional): color of the scale bar. Defaults to 'w'.
• show_cbar (bool, optional): show colorbar. Defaults to True.
• test (bool, optional): test-mode. Defaults to False.
• ax (type, optional): subplot object. Defaults to None.

Keyword Args: parameters provided to the plt.imshow.

Returns: plt.Axes

---

function annot_cells

annot_cells(label_image, show_boxes: bool = False, ax: Axes = None) → Axes

Annotate the cells on an image.

Args:

• label_image (type): image with the labeled regions
• show_boxes (bool, optional): show boxes around regions. Defaults to False.
• ax (plt.Axes, optional): plt.Axes. Defaults to None.

Returns: plt.Axes

---

function image_regions_annotated

image_regions_annotated(
    img_region,
    img,
    show_boxes: bool = False,
    **kws_img
) → Axes

Image with the annotated regions. Usage: for QC of the segmentation.

Args:

• img_region (type): image with segmentated regions.
• img (type): image with intensity.
• show_boxes (bool, optional): whether to show the boxes around the regions. Defaults to False.

Keyword Args: parameters provided to the image_background function.

Returns: plt.Axes

module htsimaging.viz

module htsimaging.viz.stat

Visualization of the statistics.

---

function dist_signal

dist_signal(
    img,
    threshold: float = None,
    label_threshold: float = None,
    params_axvline: dict = {'color': 'r', 'linestyle': 'dashed'},
    ax: Axes = None,
    **kws
) → Axes

Plot the distribution of intensity.

Args:

• img (type): inpput image
• threshold (float, optional): threshold applied. Defaults to None.
• label_threshold (float, optional): label of the threshold. Defaults to None.
• params_axvline (type, optional): parameters provided to the vertical line plot. Defaults to {'color':'r','linestyle':'dashed'}.
• ax (plt.Axes, optional): subplot object. Defaults to None.

Keyword Args: parameters provided to the hist function.

Returns: plt.Axes

---

function plot_summary_stats

plot_summary_stats(input_paths: list, ax: Axes = None) → Axes

Plot summary stats for a set of images e.g. time-lapse images.

Args:

• input_paths (list): list of paths of the images.
• ax (plt.Axes, optional): subplot object. Defaults to None.

Returns: plt.Axes