Developer Information

This section contains information relevant for developing and extending Cellocity functionality. It also contains random tidbits of general information that I have uncovered during the development process of this framework. I present it here in the hope that someone may find it useful.

Contributing to Cellocity

Contributions are welcome and appreciated. Just fork the Github repository and create a pull request. Information on how to do so can be found here. Before you do so, please make sure that the documentation strings are written in reStructuredText so that Sphinx-autodoc can generate automatic API documentation. It would also be greatly appreciated if the general architecture of Channel, Analyzer, and Analysis objects is maintained.

Bug reports and feature requests

Bug reposts and feature requests can be submitted through Github.

A note on metadata and file formats

It goes without saying that you need to have a well calibrated microscope that writes correct metadata into your image files, in order to perform meaningful cell dynamics analysis. The minimal amount of information needed is data on the pixel size and the time resolution between frames. Image format specific metadata, such as Micromanager-metadata and IJmetadata contain this information and constitute the primary source used throughout Cellocity.

Micromanager saves its metadata in a private IFD tag (51123), which Tifffile reads in as a dict, accessible via tif.micromanager_metadata. The structure of the dictionary is, annoyingly, slightly different between the 1.4.23, 2.0-beta, and 2.0-gamma branches of Micromanager. In 1.4.23 and 2.0-gamma the frame interval is stored in tif.micromanager_metadata['Summary']['Interval_ms'], but in 2.0-beta it is stored in tif.micromanager_metadata['Summary']['WaitInterval']. The discrepancy is probably due to the fact that this value records the wait interval time between frames of the acquisition, not the actual frame interval. It is possible to setup an acquisition with a frame interval that the microscope physically cannot keep up with. Therefore, Cellocity performs an additional sanity check of the individual time stamps of the frames (see Channel.doFrameIntervalSanityCheck()), in order to make sure you do not run into this problem during analysis.

Pixel resolution in Micromanager vs ImageJ .tif files

Relevant standard tags in the TIFF specification are XResolution, YResolution, and ResolutionUnit. The resolution tags are rational numbers, meaning they are generated by dividing two 32-bit integer values. ResolutionUnit is specified as being either None, Inch or Centimeter. No other units are specified.

When Micromanager saves an ome.tif it writes a rounded off value into the XResolution and YResolution tif tags, and it sets the ResolutionUnit tag to CENTIMETER. This value carries less precision than the ‘PixelSizeUm’ entry in the custom TIFF-tag ‘MicroManagerMetadata’, but the TIFF is correctly readable with roughly intact size calibration data in any reader obeying the TIFF standard.

When ImageJ (v. 1.52p) saves a Hyperstack as tif, it writes the ‘Pixel Width’ and ‘Pixel Height’ values into the XResolution and YResolution tags with higher precision. However, it sets the ResolutionUnit tag to None, probably because microns, the standard micrograph unit, are not specified in the TIFF standard.

Creating your own image format reader

If you want to develop your own reader for your microscope raw data, I suggest you look up the Tiffile project. It already implements reading of many common tif-formats from multiple microscope vendors. It is a trivial addition to tweak the Channel object and create your own subclass version specific to your file format, since Channel objects are basically extensions of Tifffile objects.

Pragmatically, the easiest way to get your non-supported image data set into Cellocity is to open it in FIJI with the Bioformats importer and thereafter resave it as a hyperstack tif (making sure that the relevant image properties are set correctly). Then, you can use the ImageJ-reading capabilities built in to Cellocity and tiffile.

Detailed description of the 5-\({\sigma}\) correlation length analysis algorithm

The 5-\({\sigma}\) correlation length was defined as the largest distance, \(r\), where the average angle between two velocity vectors \(r\) micrometers apart was \(<90°\) with a statistical significance level of 5 \(\sigma\) \((p=3×10^{−7})\).

The algorithm steps:

  1. Select each of the \(N\) vectors along the top left to bottom right diagonal of the FlowAnalyzer output velocity vector array as \(\mathbf{v}_0\).
  2. For each \(\mathbf{v}_0\), expand linearly, one row/column position at a time, along the cardinal directions (up/down/left/right) and calculate the angle between \(\mathbf{v}_0\) and each of the vectors \(\mathbf{v}_r\), at each position. Do not include masked positions, or positions outside of the array. The angles \(\theta\) for each \(\mathbf{v}_0\) are calculated with the formula: \(\cos \theta = \frac{{\left\langle {{\mathbf{v}}_0 \ast {\mathbf{v}}_{{{r}}}} \right\rangle }}{{\left\langle {\left| {{\mathbf{v}}_0} \right| \ast \left| {{\mathbf{v}}_{{{r}}}} \right|} \right\rangle }}.\)
  3. Record all the angles and distances between \(\mathbf{v}_0\) and \(\mathbf{v}_r\) for each \(N\), and for each time point, \(t\).
  4. For each distance \(r\), and time point \(t\), average all the angles recorded at this distance: \(\theta \left( r \right) = \frac{1}{N} \ast \mathop {\sum }\limits_{i = 1}^N \cos ^{ - 1}\left( {\frac{{\left\langle {{\mathbf{v}}_0 \ast {\mathbf{v}}_{{{r}}}} \right\rangle }}{{\left\langle {\left| {{\mathbf{v}}_0} \right| \ast \left| {{\mathbf{v}}_{{{r}}}} \right|} \right\rangle }}} \right).\)
  5. Compute the angular velocity correlation length at each time point. This is defined as the maximum distance where \(\theta\) is \(<90°\) with a statistical significance of 5 \(\sigma\): \(C_{vv}\left( t \right) = \mathop{\max }\limits_{r \to \infty }\left( r \right)\left\{ {\mathrm{AVG}\left( \theta \right)\left( {\it r} \right) + 5 \ast \mathrm{SEM}(\theta ({\it r})) < 90^\circ } \right\}\)