Quickstart

Context

While imctoolkit is agnostic to the image acquisition modality and can be used to process any type of segmented multiplexed images, its main focus lies on processing Imaging Mass Cytometry (IMC) data. Specific to IMC data processing, imctoolkit bridges image segmentation (e.g., using the IMC segmentation pipeline) and downstream single-cell data analysis.

Most tasks enabled by imctoolkit could also be achieved using other tools and frameworks such as CellProfiler. However, imctoolkit provides a pure “pythonic” framework for IMC data processing, without relying on heavy external dependencies.

Note

The imctoolkit package was developed at the same time as the powerful squidpy package. Unlike squidpy, imctoolkit solely focuses on core data processing tasks and does not cover data analysis aspects. As squidpy builds on anndata and imctoolkit can export single-cell data to that format, squidpy and imctoolkit are interoperable.

Loading images

imctoolkit supports a variety of data formats, including raw data files generated by IMC. To load an image, just call the corresponding function of the imctoolkit.MultichannelImage class, for example:

from imctoolkit import MultichannelImage

img = MultichannelImage.read_tiff('/path/to/image.ome.tiff')

This will return an imctoolkit.MultichannelImage instance that holds the image data in imctoolkit.MultichannelImage.data as xarray.DataArray for further use.

For convenience, basic properties of the image can be accessed through the imctoolkit.MultichannelImage instance, for example to access the channel names:

print(img.channel_names)

Extracting single-cell data

The single-cell data for a given image and a corresponding cell mask can be accessed through imctoolkit.ImageSingleCellData objects, which are be created as follows:

import tifffile

from imctoolkit import ImageSingleCellData

mask = tifffile.imread('/path/to/mask.tiff')
data = ImageSingleCellData(img, mask)

Note

The img parameter of imctoolkit.ImageSingleCellData.__init__() is not restricted to imctoolkit.MultichannelImage instances, but also accepts e.g. xarray DataArrays.

imctoolkit.ImageSingleCellData exposes a range of properties to extract single-cell intensity data for the provided image/cell mask pair, either as xarray.DataArray or as pandas.DataFrame (properties suffixed by _table). For example, to extract the channel-wise mean intensities per cell:

print(data.mean_intensities_table)

Note

These properties will be computed upon first access (lazy), and at first access only (cached).

In addition to intensity properties, the imctoolkit.ImageSingleCellData class also provides access to region properties of the cell mask (lazy and cached):

print(data.regionprops_table)

The list of available region properties is a subset of scikit-image’s supported region properties. It defaults to imctoolkit.ImageSingleCellData.DEFAULT_REGION_PROPERTIES and can be customized at instantiation using the region_properties attribute of imctoolkit.ImageSingleCellData.__init__().

All single-cell information accessible through imctoolkit.ImageSingleCellData can be exported to a number of data formats for further data analysis, for example:

data.to_anndata(cell_properties=True, cell_channel_properties=True).write('/path/to/data.h5ad')

Warning

Export operations evaluate all lazy properties of this class and thus require sufficient computational resources (both memory and processing power).

Constructing spatial cell graphs

To construct spatial cell graphs (“neighborhood graphs”) from single-cell data, simply call the appropriate construct_ function of the imctoolkit.SpatialCellGraph class, for example:

from imctoolkit import SpatialCellGraph

dist_mat = data.compute_cell_border_distances()
graph = SpatialCellGraph.construct_dist_graph(data, dist_mat, 15, cell_channel_properties=True)

Note

The data parameter of imctoolkit.SpatialCellGraph.__init__() is not restricted to imctoolkit.SpatialSingleCellData instances, but also accepts e.g. pandas DataFrames.

The resulting imctoolkit.SpatialCellGraph objects hold the cell data and an adjacency matrix, and can be exported to popular graph data formats for further analysis, for example:

graph.to_igraph().write_graphml('/path/to/graph.graphml')

Note

The exported graph will contain all single-cell data as node attributes.