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.

.. _IMC segmentation pipeline: https://github.com/BodenmillerGroup/ImcSegmentationPipeline
.. _CellProfiler: https://cellprofiler.org
.. _squidpy: https://github.com/theislab/squidpy
.. _anndata: https://github.com/theislab/anndata

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 :class:`imctoolkit.MultichannelImage` class, for example:

.. code-block::

    from imctoolkit import MultichannelImage

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

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

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

.. code-block::

    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
:class:`imctoolkit.ImageSingleCellData` objects, which are be created as follows:

.. code-block::

    import tifffile

    from imctoolkit import ImageSingleCellData

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

.. note::

    The :attr:`img` parameter of :func:`imctoolkit.ImageSingleCellData.__init__` is not restricted to
    :class:`imctoolkit.MultichannelImage` instances, but also accepts e.g. xarray DataArrays.

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

.. code-block::

    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 :class:`imctoolkit.ImageSingleCellData` class also provides access to region
properties of the cell mask (lazy and cached):

.. code-block::

    print(data.regionprops_table)

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

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

.. code-block::

    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 :class:`imctoolkit.SpatialCellGraph` class, for example:

.. code-block::

    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 :attr:`data` parameter of :func:`imctoolkit.SpatialCellGraph.__init__` is not restricted to
    :class:`imctoolkit.SpatialSingleCellData` instances, but also accepts e.g. pandas DataFrames.

The resulting :class:`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:

.. code-block::

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

.. note::

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