Introduction to Cellocity

A 30 second pitch

Cellocity is a bioimage analysis tool for quantifying confluent cell layer dynamics. The main advantages of Cellocity is its ability to work on unlabeled Brightfield time lapse microscopy data, and to both quantify and visualize abstract optical flow analyses to the user.

Example output

Figure showing simulated raw data (left), a vector field visualization (center), and a heat map encoding speeds (right).

Installing Cellocity

Cellocity is available on the Python package index and the latest release can be installed using pip:

pip install cellocity

You can also clone the Github repository if you are interested in getting the current development version of Cellocity:

git clone https://github.com/Oftatkofta/cellocity.git cellocity
cd cellocity
pip install -e .

Cellocity requires Python (>3.7), tifffile (2020.5.5), python-OpenCV (4.2.0.34), OpenPIV (0.21.3), Numpy (1.18.4), Pandas (1.0.3) to function correctly. Additionally, you need Matplotlib (3.2.1) and Seaborn (0.10.1) in order to visualize the validation output. If you perform a pip install from PyPi, all dependencies will be installed automatically.

Citing Cellocity

If you have found Cellocity useful in your project and want to cite it, you can use our JOSS publication [![DOI](https://joss.theoj.org/papers/10.21105/joss.02818/status.svg)](https://doi.org/10.21105/joss.02818)

Cellocity development history

Cellocity has been developed over multiple years and several projects. The nucleus was developed in Stig Ove Bøe’s research group at Oslo University Hospital and at the Nanoscopy Gaustad imaging core facility at the University of Oslo. Many of Cellocity’s core algorithm implementations and methods, such as the 5-sigma correlation length analysis, were presented in a Nature Communications publication in 2018 [3].

The framework is currently being used and further developed as the analysis backbone for studies of microbial interactions with the gut epithelium in the Sellin Laboratory at Uppsala University.

Cellocity backbone

Cellocity is built on top of Christoph Gohlke’s Tifffile library and uses the Tifffile object to read input and write output files. Cellocity also relies heavily on OpenCV [1] and OpenPIV [5] for optical flow analysis and output visualizations. NumPy [6] is used internally for image data manipulation in the form of numpy.ndarrays, and matplotlib is used to generate output plots [2].

Cellocity architecture

The core element in Cellocity is the Channel object, which represents one Z-plane of one time lapse image channel. Channel objects also handle image pre-processing, such as temporal or spatial median filtering. Channel objects are given as input to Analyzer objects, which perform specific analyses on the data. Analyzer objects can then, in turn, be given to Analysis objects, which take care of performing further analyses, such as calculating the alignment index, instantaneous order parameter (\({\psi}\)), and correlation length.

Overview of Cellocity architecture

Figure showing the overall object architecture of Cellocity.

Examples of algorithms and vector field quantifications implemented

Instantaneous Order Parameter (\({\psi}\))

\({\psi}\) = 1 corresponds to a perfectly uniform velocity field, where all the cells move in the same direction and with the same speed, while \({\psi}\) \({\approx}\) 0 is expected for a randomly oriented velocity field. See [4] for details.

Alignment Index

The Alignment Index describes how well each vector in a vector field aligns with the average velocity vector. See [4] for further details.

5-\({\sigma}\) correlation length

5-\({\sigma}\) correlation length is a way to measure the correlation length in large vector fields. It finds the average distance at which the direction of velocities are no longer significantly different at a level of 5 standard deviations (\({\sigma}\)). The algorithm was originally presented and utilized in [3]. A more detailed description can be found in the Developer Information.

Examples

Simple file loading example:

from cellocity.channel import Channel
from tifffile import Tiffile

tif = Tifffile(myFile)
channel_1 = Channel(0, tif, "channel name") #0-indexed channels, meaning ch1 in ImageJ

Simple pre-processing example:

from cellocity.channel import MedianChannel

#Trim Channel to frame 2-40
channel_1.trim(2, 41)
#3-frame gliding temporal median projection by default
channel_1_median = MedianChannel(channel_1)

Simple optical flow calculation example:

from cellocity.analysis import FarenbackAnalyzer

flow_Ch1 = FarenbackAnalyzer(channel_1_median, "um/min")
flow_Ch1.doFarenbackFlow()

Simple analysis data readout example:

from cellocity.analysis import FlowSpeedAnalysis

    speed_analysis_Ch1 = FlowSpeedAnalysis(flow_Ch1)
    speed_analysis_Ch1.calculateAverageSpeeds()
    speed_analysis_Ch1.saveCVS("/path/to/savefolder")

For more detailed examples please check out the tutorial section.

Support

If something is unclear or if you are in need of support, please contact the developer by creating a new support issue.

References

1

Gary Bradski. The OpenCV Library. Dr. Dobb’s Journal of Software Tools, 25:120–125, 2000.

2

John D. Hunter. Matplotlib: a 2d graphics environment. Computing in Science & Engineering, 9(3):90–95, 2007. doi:10.1109/MCSE.2007.55.

3(1,2)

Emma Lång, Anna Połeć, Anna Lång, Marijke Valk, Pernille Blicher, Alexander D. Rowe, Kim A. Tønseth, Catherine J. Jackson, Tor P. Utheim, Liesbeth M. C. Janssen, Jens Eriksson, and Stig Ove Bøe. Coordinated collective migration and asymmetric cell division in confluent human keratinocytes without wounding. Nature communications, 9(1):3665, 2018. doi:10.1038/s41467-018-05578-7.

4(1,2)

Chiara Malinverno, Salvatore Corallino, Fabio Giavazzi, Martin Bergert, Qingsen Li, Marco Leoni, Andrea Disanza, Emanuela Frittoli, Amanda Oldani, Emanuele Martini, Tobias Lendenmann, Gianluca Deflorian, Galina V. Beznoussenko, Dimos Poulikakos, Ong Kok Haur, Marina Uroz, Xavier Trepat, Dario Parazzoli, Paolo Maiuri, Weimiao Yu, Aldo Ferrari, Roberto Cerbino, and Giorgio Scita. Endocytic reawakening of motility in jammed epithelia. Nature materials, 16(5):587–596, 2017. doi:10.1038/nmat4848.

5

Zachary J. Taylor, Roi Gurka, Gregory A. Kopp, and Alex Liberzon. Long-duration time-resolved piv to study unsteady aerodynamics. IEEE Transactions on Instrumentation and Measurement, 59(12):3262–3269, 2010. doi:10.1109/TIM.2010.2047149.

6

Stefan van der Walt, S Chris Colbert, and Gael Varoquaux. The numpy array: a structure for efficient numerical computation. Computing in Science Engineering, 13(2):22–30, 2011. doi:10.1109/MCSE.2011.37.