vgeorgii / microsa

Python library designed for tissue microenvironment spatial analysis

Microsa

Project was developed by G.Vasiukov and S.Novitskiy

Microsa (Microenvironment spatial analysis) is a package of useful functions for analysis of fibrous components of tissue microenvironment and combine that analysis in spatial dependent manner. The purpose of presented package is to provide simplified tool which gives an opportunity to combine the analysis of cellular and non-cellular components of tissue microenvironment.

Utilization:

• Segmentation of fibril-like objects (tensor method) in 2D;
• Calculation of fibers’ centroid, length, width, angle and linearity in 2D;
• Estimation of fibers' features and providing a detailed report in pandas.DataFrame format;
• Implementation of spatial analysis between cellular and non-cellular objects.

Installation:

• Using pip:
  $ pip install microsaa
  

Requirements:

• Python 3.7;
• Numpy >= 1.14;
• SciPy >= 1.5.3;
• scikit-image >= 0.14;
• Pandas >= 1.1.3;
• Matplotlib >= 2.0.

Usage:

Open a grayscale image, perform filtering, binarization and segmentation of fibers, calculate geometrical and spatial features of fibers, perform spatial analysis for other objects (cells).

Fiber segmentation module:

• fibers_executor (image):
  

  Function mainly performs segmentation of fibers and extract parameters that are required for other functions like number of labels, distance between centroids etc.

  arguments: image – gray scale image to process

  function returns: 'skeleton': image with skeletonized objects, 'distance': distance from skeleton to the edge of original object (radius), 'skel_labels_pruned': pruned and labeled skeletonized objects, 'props_pruned': properties of labeled objects, 'nlabels_pruned': number of labeled objects

Fiber geometrical feature calculation:

• fibs_geom (executed_fibs, radius):
  

  Function returns dataframe which contains information about fibers

  arguments:

  • executed_fibs: array with calculated features of labeled fibers
  • radius: radius of neighborhood outline

  function returns:

  • pd.DataFrame with calculated fibers features (number, length, angle, strightness, thickness, linearity)

Spatial:

• fibs_spatial (cells_coords_list, executed_fibs, radius, cell_type = 'None', cell_type_list = 'None'):
  

  Function returns dataframe which contains information about neighboring cells, their type, and features

  arguments:

  • cells_coords_list: list of cells coords
  • executed_fibs: array with calculated features of labeled fibers
  • radius: radius of neighborhood outline
  • cell_type: default 'None', list of cell types for spatial analysis. 'All' make function perform calculation for all types of cell
  • cell_type_list: default 'None', list(column) with cell types

  function returns:

  • pd.DataFrame with calculatedd spatial information of neighboring cells

• cell_cell_spatial (cells_coords_list, radius, cell_type = 'None', cell_type_list = 'None', cell_feature_list = 'None'):
  

  Function returns dataframe which contains information about neighboring cells, their type, and features

  arguments:

  • cells_coords_list: list of cells coords
  • radius: radius of neighborhood outline
  • cell_type: default 'None', list of cell types for spatial analysis. 'All' make function perform calculation for all types of cell
  • cell_type_list: list(column) with cell types
  • cell_feature_list: list(colum) of feature of cells

  function returns:

  • pd.DataFrame with calculatedd spatial information of neighboring cells

• cell_fibs_spatial (executed_fibs, cells_coords_list, radius):
  

  Function returns dataframe which contains information about neighboring fibers and their features

  arguments:

  • executed_fibs: dictionary executed with fiber_executer function that contains information about segmented fibers
  • cells_coords_list: list with cells coordinates (y,x)
  • radius: radius of neighborhood outline

  function returns:

  • pd.DataFrame with calculatedd spatial information of neighboring fibers

Example of usage:

from microsaa import *

import numpy as np
from skimage import io
from matplotlib import colors
from skimage.morphology import medial_axis
from skimage.measure import regionprops
from skimage.measure import label
from scipy import ndimage
from skimage.graph import route_through_array
from scipy.ndimage import binary_closing, binary_hit_or_miss
from skimage.filters import frangi
from scipy.spatial import distance
import pandas as pd
import matplotlib
from matplotlib import pyplot as plt

Importing image sample

img = io.imread('C:/Users/test_image.tif')
fig, ax = plt.subplots(figsize = (100,100))
ax = plt.imshow(img)

For example, we have dataframe with information about cells (localization (cells_coords), type of cell (cell_type), and features of cells (cell_feature_1, cell_feature_2))

Generating dataframe with random values

import random

dataframe = pd.DataFrame ()
dataframe['cells_coords'] = [[random.randint(0, len(img)-2), random.randint(0, len(img[0])-2)] for i in np.arange(500)]
cell_type_dict = {1 : 'green', 2 : 'red', 3 : 'yellow'}
dataframe['number'] = pd.DataFrame([random.randint(1, 3) for i in np.arange(500)])
dataframe['type'] = dataframe['number'].map(cell_type_dict)
dataframe.drop('number', axis=1, inplace = True)
dataframe['cell_feature_1'] = [random.randint(0, 100) for i in np.arange(500)]
dataframe['cell_feature_2'] = [random.randint(0, 100) for i in np.arange(500)]

Generating lists form dataframe columns

cells_coords = list(dataframe.loc[:, 'cells_coords'])
cell_type = list(dataframe.loc[:, 'type'])
cell_feature_1 = list(dataframe.loc[:, 'cell_feature_1'])
cell_feature_2 = list(dataframe.loc[:, 'cell_feature_2'])

Image filtering (Frangi filter implementation)

gray_frangi = np.array(frangi(img, sigmas=range(4, 6, 10), gamma = 25, black_ridges = False))
gray_frangi_bit = ((gray_frangi/255) > 0.000000001)
fig, ax = plt.subplots(figsize = (50,50))
ax = plt.imshow(gray_frangi_bit, cmap = 'gray')

Fibers skeletonization and labeling

fibere_exe = fibers_executor (gray_frangi_bit)
fig, ax = plt.subplots(figsize = (100,100))
ax = plt.imshow(np.multiply(fibere_exe['skel_labels_pruned'] > 0, 1), cmap = 'gray')
plt.axis('off')
plt.show()

Fiber geometry

fbs_mrph = fibs_geom (img, fibere_exe, 25)

Fiber spatial analysis

fib_spat = fibs_spatial (cells_coords, fibere_exe, 25, cell_type = 'All', cell_type_list = cell_type)

Cell spatial analysis

cell_cell_spt = cell_cell_spatial (cells_coords, 25, cell_type = 'All', cell_type_list = cell_type, cell_feature_list = [cell_feature_1, cell_feature_2])

cll_fbs_sptl = cell_fibs_spatial (fibere_exe, cells_coords, 25)

Visualization

vis = visualization (gray_frangi, cells_coords, cell_type, fibere_exe, 5)

microsa's Issues

unexpected keyword argument 'neighbors'

Hello, I am trying to replicate the analysis for this package, however when I reach the step for fibers skeletonization and labeling, in the first line of code to define fibre-exe I get a keyword argument error:
TypeError: label() got an unexpected keyword argument 'neighbors'

All packages are updated as required.

Image input

Hello again, could you please provide some details about the input image requirements of the package? It works with some of my images but not with others. How many different cell types should be in each image? I get a "ValueError: Unsupported dtype" error.

Expected running time

Hello everyone!

I have an image with a collagen signal which I am trying to process with this package. The dimensions of the image are 11273x13116. Could you say, what is the average time to process such an image?

Also, could you help me to understand one specific line in the example of usage:

gray_frangi_bit = ((gray_frangi/255) > 0.000000001)

How this threshold value (0.000000001) was found? Is it the best value for any input image?

Thanks,
Vladimir