The Cellocity API Reference

The channel module

class cellocity.channel.Channel(chIndex, tiffFile, name, sliceIndex=0)

Base Class to keep track of one channel (t,x,y) of microscopy data.

Channel Objects are created from tifffile.Tifffile and act as shallow copies of the TiffPage objects making up the channel, until a Numpy array is generated by ‘getArray’. Then self.array is populated by a Numpy array from the raw image data, using the ‘asarray’ function in ‘tiffile.Pages’. Only a single z-slice and channel are handled per Channel object. A reference to the base ‘tifffile.Tifffile’ is stored in self.tif.

There are currently two very similar subclasses of Channel, MM_Channel, and IJ_Channel to handle Micromanager OME-TIFFs and ImageJ hyperstacks, respectively.

Parameters:
  • chIndex (int) – index of channel to create, 0-based.
  • tiffFile (:class:'tifffile') – TiffFile object to extract channel from
  • name (str) – name of channel, used in Analysis output
  • sliceIndex (int) – z-slice to extract, defaults to 0
doFrameIntervalSanityCheck(maxDiff=0.01)

Performs sanity check on frame intervals.

Checks if the intended frame interval from metadata matches the actual frame interval from individual frame time stamps. If the mean difference is more than maxDiff the function returns False. Defaults to allowing a 1% difference between mean actual frame interval and intended frame interval by default.

Parameters:maxDiff (float) – Maximum allowed difference between actual frame intervals and the intended interval, expressed as a fraction.
Returns:True if the fraction of actual and intended frame intervals is below maxDiff.
Return type:bool
fixFrameInterval()

Replaces the intended frame interval with the actual.

Use this method in case the self.doFrameIntervalSanityCheck() method fails. The method overwrites the intended frame interval stored in self.finterval_ms with the actual, as calculated from the mean of all time stamp deltas.

Returns:New frame interval
Return type:float
getActualFrameIntevals_ms()

Returns the intervals between frames in ms as a list.

Note that the length of this list is 1 shorter than the number of frames because frame intervals are calculated. Returns None if only one frame exists in the channel.

Returns:list of time intervals between frames, None if self.array contains fewer than 2 frames.
Return type:list
getArray()

Returns channel image data as a numpy array.

Method populates the array from self.pages first time it is called.

Returns:Channel image data as 3D-numpy array
Return type:numpy.ndarray (type depends of original format)
getElapsedTimes_ms()

Returns a list of elapsed times in ms from the start of image acquisition.

Values are extracted from image timestamps. Note that this is only possible for MicroManager based Channels (and other timestamped formats). Since ImageJ does not store this information the frame interval value is trusted and used to calculate elapsed times.

Returns:Timestamps of channel frames from the start of the acquisition.
Return type:list
getIntendedFrameInterval_ms()

Returns the intended frame interval as recorded in image metadata.

Returns:interval between successive frames in ms
Return type:int
getPages()

Returns the TiffPages that make up the channel data

Returns:a list of the TiffPages extracted from the Tifffile used to create the Channel
Return type:list
getTemporalMedianChannel(**kwargs)

Returns a new MedianChannel object where self.array has been replaced with temporal median filtered channel data

kwargs and defaults are: {doGlidingProjection = True, frameSamplingInterval=3, startFrame=0, stopFrame=None} Defaults to a gliding 3 frame temporal median of the whole channel if no kwargs are given.

Returns:A MedianChannel object based on the current channel where self.array has been replaced by a numpy array of the type float32 representing the temporal median of Channel data.
Return type:MedianChannel
getTiffFile()

Returns the Tifffile objedt that the Channel is based on.

Returns:Tifffile-object used when Channel was created
Return type:object tifffile.Tifffile
trim(start, stop)

Trims the channel from start frame to stop frame, removing pages and array pages outside the given range.

All relevant properties are also trimmed and the Channel name is appended with “_TRIM-‘start`-stop

Parameters:
  • start (int) – start frame of trim (0-indexed)
  • stop (int) – stop frame of trim (not included)
Returns:

None, trims Channel in place

class cellocity.channel.MedianChannel(channel, doGlidingProjection=True, frameSamplingInterval=3, startFrame=0, stopFrame=None)

A subclass of Channel where the channel array has been temporal median filtered.

Temporal median filtering is very useful when performing optical flow based analysis of time lapse microscopy data, because it filters out fast moving free-floating debris from the dataset. Note that the median array will be shorter than the original array. In the default case, if a temporal median of 3 frames is applied, then the the output array will contain 3-1 = 2 frames less than the input if a gliding projection (default) is performed.

Parameters:
  • channel (Channel object) – Parent Channel object for the MedianChannel
  • doGlidingProjection (bool) – Should a gliding projection be used? Defaults to True, if False a binned projection is performed, this will also recalculate the frame interval.
  • frameSamplingInterval (int) – How many frames to use in temporal median projection, defaults to 3
  • startFrame (int) – Start frame of median projection
  • stopFrame (int or None) – Stop frame of median projection (non inclusive), defaults to None i.e. all frames
getTemporalMedianFilter(doGlidingProjection, startFrame, stopFrame, frameSamplingInterval)

Returns a temporal median filter of the parent Channel.

The function runs a gliding N-frame temporal median on every pixel to smooth out noise and to remove fast moving debris that is not migrating cells.

Parameters:
  • doGlidingProjection (bool) – Should a gliding (default) or binned projection be performed?
  • stopFrame (int) – Last frame to analyze, defaults to analyzing all frames if None.
  • startFrame (int) – First frame to analyze.
  • frameSamplingInterval (int) – Do median projection every N frames.
Returns:

Numpy array

Return type:

numpt.ndarray

cellocity.channel.normalization_to_8bit(image_stack, lowPcClip=0.175, highPcClip=0.175)

Function to rescale 16/32/64 bit arrays to 8-bit for visualizing output

Defaults to saturate 0.35% of pixels, 0.175% in each end by default, which often produces nice results. This is the same as pressing ‘Auto’ in the ImageJ contrast manager. numpy.interp() linear interpolation is used for the mapping.

Parameters:
  • image_stack (Numpy array) – 3D Numpy array to be rescaled
  • lowPcClip (float) – Fraction for black clipping bound
  • highPcClip (float) – Fraction for white/saturated clipping bound
Returns:

8-bit numpy array of the same shape as image_stack

Return type:

numpy.dtype(‘uint8’)

cellocity.channel.rehape3DArrayTo6D(array_3d)

reshapes 3D (t, x, y) array to (t, 1, 1, x, y, 1).

Used when saving ImageJ compatible tifs using Tifffile where dimensions have to be in TZCYXS order.

Parameters:array_3d – 3D numpy array
Returns:None
cellocity.channel.reshape6DArrayTo3D(array_6D)

Undoes what reshape3DArrayTo6D does to the shape of the array.

Parameters:array_6D – 6D numpy array
Returns:

The analysis module

class cellocity.analysis.AlignmentIndexAnalysis(analyzer)

Calculates the alignment index for the flow vectors in a FlowAnalyzer object.

Alignment index (AI) is defined as in Malinverno et. al 2017. For every frame the AI is the average of the dot products of the mean velocity vector with each individual vector, all divided by the product of their magnitudes.

The alignment index is 1 when the local velocity is parallel to the mean direction of migration (-1 if antiparallel).

calculateAlignIdxs()

Calculates the aligment index for each pixel in base FlowAnalyzer flow array and populates self.alignment_idxs

Returns:numpy array with same size as analyzer flows, where every entry is the alignment index in that pixel
Return type:numpy.ndarray
calculateAverage()

Calculates the average alignment index for each time point in self.alignment_idxs

Returns:self.avg_alignment_idxs, 1D numpy.ndarray of the same length as self.alignment_idxs
Return type:numpy.ndarray
getAvgAlignIdxAsDf()

Returns frame and average alignment index for the frame as a Pandas DataFrame.

Returns:DataFrame with 1 column for average aligmnent index and index = frame number
Return type:pandas.DataFrame
getAvgAlignIdxs()

Returns average alignment indexes for Analyzer

Returns:
saveArrayAsTif(outdir, fname=None)

Saves the alignment index array as a 32-bit tif with imageJ metadata.

Pixel intensities encode alignment indexes.

Parameters:
  • outdir (pathlib.Path) – Directory to store file in
  • fname – Filename, defaults to Analysis channel name with appended tags +_ai.tif if None
Returns:

None

saveCSV(outdir, fname=None, tunit='s')

Saves a csv of average aligmnent indexes per frame in outdir.

Parameters:
  • outdir (pathlib.Path) – Directory where output is stored
  • fname (str) – filename, defaults to channel name + ai.csv
  • tunit (str) – Time unit in output one of: “s”, “min”, “h”, “days”
Returns:

class cellocity.analysis.Analysis(analyzer)

Base object for handling data output and analysis and of Analyzer classes.

Parameters:analyzer – Analyzer object
getAnalyzer()

Returns the Analyzer that the Analysis is based on.

Returns:the Analyzer that the Analyser is based on.
Return type:Analyzer
getChannelName()

Returns the name of the channel that the base Analyzer, in turn, is based on.

Returns:self.name of the Channel that the base Analyzer is based on.
Return type:str
class cellocity.analysis.Analyzer(channel)

Base object for all Analysis object types, handles progress updates.

Parameters:channel (class:channel.Channel) – A Channel object
getProgress()

Returns current progress in the interval 0-100.

Returns:Percentage progress of analysis
Return type:float
resetProgress()

Resets progressbar to 0

Returns:
updateProgress(increment)

Updates self.progress by increment

Parameters:increment
Returns:
class cellocity.analysis.FarenbackAnalyzer(channel, unit)

Performs OpenCV’s Farenbäck optical flow anaysis.

Parameters:
  • channel – Channel object
  • unit – (str) “um/s”, “um/min”, or “um/h”
doFarenbackFlow(pyr_scale=0.5, levels=3, winsize=15, iterations=3, poly_n=5, poly_sigma=1.2, flags=0)

Calculates Farenback flow for a single channel time lapse with validated default parameters.

returns numpy array of dtype int32 with flow in the unit px/frame Output values need to be multiplied by a scalar to be converted to speeds.

class cellocity.analysis.FiveSigmaAnalysis(flowanalyzer, maxdist=None)

Calculates the 5-sigma corrleation length for each frame of flow (see Lång et. al 2018 or the documentation for a more detailed explanation).

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})\).

Parameters:
  • flowanalyzer (analysis.FlowAnalyzer) – a FlowAnalyzer object
  • maxdist (int) – Maximum distance (in pixels) to test if None defaults to max(flow width, height)
calculateCorrelationAllFrames(n_sigma=5)

Calculates correlation length for all flow frames

Parameters:n_sigma
Returns:
calculateCorrelationOneFrame(frame, n_sigma=5)
Parameters:
  • frame – (flow) frame to calculate correlation length for
  • n_sigma – Number of standard deviations to consider significant
Returns:

getCorrelationLengths()

Returns correlation lengths as a dictionary frame:correlation_length_in_um

Returns:
getCorrelationLengthsAsDf(tunit='s')

Returns a Pandas DataFrame with index:time in “tunit” and Correlation length.

Parameters:tunit – Time unit in output one of: “s”, “min”, “h”, “days”
Returns:pandas.Dataframe
saveCSV(outdir, fname=None, tunit='s')

Saves a csv of correlation lengths per frame in outdir.

Parameters:
  • outdir (pathlib.Path) – Directory where output is stored
  • fname (str) – filename, defaults to channel name + _Cvv.csv
  • tunit (str) – Time unit in output one of: “s”, “min”, “h”, “days”
Returns:

class cellocity.analysis.FlowAnalysis(analyzer)

Base object for analysis of optical flow and PIV.

Works on FlowAnalyzer objects, such as FarenbackAnalyzer and OpenPIVAnalyzer. Needs a 4D (t, x, y, uv) numpy array representing a time lapse of a vector field to initialize.

draw_all_flow_frames(scalebarFlag=False, scalebarLength=10, **kwargs)

Draws flow on a black background as an 8-bit array.

Draws a subset of the flow as lines on top of a black background. Because the flow represents what happens between frames, the flow is not drawn on the last frame of the channel, which is discarded. Creates and populates self.drawnframes to store the drawn array. If the underlying channel object is 16-bit, it will converted to 8bit with the channel.normailzation_to_8bit() function.

Parameters:
  • scalebarFlag (bool) – Should a scale bar be drawn on the output?
  • scalebarLength – What speed should the scale bar represent with its length the unit is set by the unit given to the Analyzer
  • kwargs (dict) – Additional arguments passed to self._draw_flow_frame()
Returns:

8bit numpy array

draw_all_flow_frames_superimposed(scalebarFlag=False, scalebarLength=10, **kwargs)

Draws flow superimposed on the background channel as an 8-bit array.

Draws a subset of the flow as lines on top of the background channel. Because the flow represents what happens between frames, the flow is not drawn on the last frame of the channel, which is discarded. Creates and populates self.drawnframes to store the drawn array. If the underlying channel object is 16-bit, it will converted to 8bit with the channel.normailzation_to_8bit() function.

Parameters:
  • scalebarFlag (bool) – Should a scale bar be drawn on the output?
  • scalebarLength – What speed should the scale bar represent with its length the unit is set by the unit given to the Analyzer
  • kwargs (dict) – Additional arguments passed to self._draw_flow_frame()
Returns:

8bit numpy array

saveFlowAsTif(outpath)

Saves the drawn frames as an imageJ compatible tif with rudimentary metadata.

Parameters:outpath (Path object) – Path to savefolder
Returns:None
class cellocity.analysis.FlowAnalyzer(channel, unit)

Base object for all optical flow analysis object types.

Stores UV vector components in self.flows as a (t, x, y, uv) numpy array. Also calculates and stores a scaling factor that converts flow from pixels per frame to distance/time.

Parameters:unit (str) – must be one of [“um/s”, “um/min”, “um/h”]
get_flow_shape()

Returns the shape of self.flows

Returns:the shape of self.flows
Return type:tuple
get_pixel_size()

Returns the pixel size in um of the Analyzer.

Some type of Analyzers, such as the OpenPivAnalyzer change the pixel size of the array by downsampling.

Returns:pixel size in um of the Analyzer
Return type:float
get_u_array(frame)

Returns the u-component array of self.flows at frame

Parameters:frame (int) – frame to extract u-component matrix from
Returns:u-component of velocity vectors as a 2D NumPy array
Return type:numpy.ndarray
get_v_array(frame)

Returns the v-component array of self.flows

Parameters:frame (int) – frame to extract v-component matrix from
Returns:v-component of velocity vectors as a 2D NumPy array
Return type:numpy.ndarray
class cellocity.analysis.FlowSpeedAnalysis(analyzer)

Handles all analysis and data output of speeds from FlowAnalyzers.

Calculates pixel-by-pixel speeds from flow vectors.

calculateAverageSpeeds()

Calculates the average speed for each time point in self.speeds

Returns:self.avg_speeds
Return type:1D numpy.ndarray of the same length as self.speeds
calculateHistograms(hist_range=None, nbins=100, density=True)

Calculates a histogram for each frame in self.speeds

Parameters:
  • hist_range (tuple) – Range of histogram, defaults to 0-max
  • nbins (int) – Number of bins in histogram, defaults to 100
  • density (bool) – If False, the result will contain the number of samples in each bin. If True (default), the result is the value of the probability density function at the bin, normalized such that the integral over the range is 1.
Returns:

self.histograms

Return type:

tuple (numpy.ndarray, bins)

calculateSpeeds(scaler=None)

Calculates speeds from the flows in parent Analyzer

Turns a (t, x, y, uv) flow numpy array with u/v component vectors in to a (t, x, y) speed array. Populates self.speeds. Scales all the output by multiplying with scaler, defaults to using the self.scaler from the base FlowAnalyzer object if the scaler argument is None.

self.scaler is the scalar quantity that converts flow vectors from the general unit of pixels/frame in to the desired output unit, such as um/s.

:returns self.speeds :rtype: numpy.ndarray

getAvgSpeeds()

Returns average speed per frame as a 1D Numpy array.

Returns:average speed per frame
Return type:numpy.ndarray (1D)
getAvgSpeedsAsDf()

Returns frame and average speed for the frame as a Pandas DataFrame.

Returns:DataFrame with 1 column for average speed and index = frame number
Return type:pandas.DataFrame
getSpeeds()

Returns self.speeds.

Calculates self.speeds with default values if it has not already been calculated.

Returns:self.speeds as a 3D Numpy array
Return type:numpy.ndarray (3D)
saveArrayAsTif(outdir, fname=None)

Saves the speed array as a 32-bit tif with imageJ metadata.

Pixel intensities encode speeds in the chosen analysis unit

Parameters:
  • outdir (pathlib.Path) – Directory to store file in
  • fname – Filename, defaults to Analysis channel name with appended tags +_speeds-SizeUnit-per-TimeUnit.tif if None
Returns:

None

saveCSV(outdir, fname=None, tunit='s')

Saves a csv of average speeds per frame in outdir.

Parameters:
  • outdir (pathlib.Path) – Directory where output is stored
  • fname (str) – filename, defaults to channel name + speeds.csv
  • tunit (str) – Time unit in output one of: “s”, “min”, “h”, “days”
Returns:

class cellocity.analysis.IopAnalysis(flowanalyzer)

Calculates the instantaneous order parameter (iop) for each frame of flow (see Malinverno et. al 2017 for a more detailed explanation).

The iop is a measure of how similar the vectors in a field are, which takes in to account both the direction and magnitudes of the vectors. iop is always between 0 and 1, with iop = 1 being a perfectly uniform field of identical vectors, and iop = 0 for a perfectly random field.

Parameters:flowanalyzer (analysis.FlowAnalyzer) – a FlowAnalyzer object
calculateIops()

Calculates the IOP for each frame in base FlowAnalyzer flow array and populates self.iops

Returns:list of the IOP from each frame
Return type:list
getIops()

Returns the instantaneous order parameter for Analyzer

Returns:list of instantaneous order parameters
Return type:list
getIopsAsDf()

Returns frame and iop for the frame as a Pandas DataFrame.

Returns:DataFrame with 1 column for iop and index = frame number
Return type:pandas.DataFrame
saveCSV(outdir, fname=None, tunit='s')

Saves a csv of the iop per frame in outdir.

Parameters:
  • outdir (pathlib.Path) – Directory where output is stored
  • fname (str) – filename, defaults to channel name + iop.csv
  • tunit (str) – Time unit in output one of: “s”, “min”, “h”, “days”
Returns:

class cellocity.analysis.OpenPivAnalyzer(channel, unit)

Implements OpenPIV’s optical flow anaysis.

Parameters:
  • channel – Channel object
  • unit – (str) “um/s”, “um/min”, or “um/h”
doOpenPIV(**piv_params)

The function does PIV analysis between every frame in input Channel.

It populates self.flows with the u and v components of the velocity vectors as two (smaller) numpy arrays. An additional array, self.flow_coorinates, with the x and y coordinates corresponding to the centers of the search windows in the original input array is also also populated.

Parameters:piv_params (dict) – parameters for the openPIV function extended_search_area_piv
Returns:(u_component_array, v_component_array, original_x_coord_array, original_y_coord_array)
Return type:tuple

The validation module

cellocity.validation.combine_lcorr_and_process_time_to_df(lcorrdf, processtimedict, file_name, analyzer_name)

Performs combination and mutation of correlation length dataframe to simplify visualization and plotting Used by run_5sigma_validation as a helper function.

cellocity.validation.convertChannel(fname, finterval=1)

Converts a mulitiposition MM file to a timelapse Channel with finterval second frame interval.

Parameters:
  • fname – Path to file
  • finterval – desired frame interval in output Channel, defaults to 1 second
Returns:

Channel

Return type:

channel.Channel

cellocity.validation.convertMedianChannel(fname, finterval=1)

Converts a mulitiposition ome.tif MM file to a timelapse MedianChannel with finterval second frame interval.

Parameters:
  • fname – Path to file
  • finterval – desired frame interval in output Channel, defaults to 1 second
Returns:

MedianChannel with default 3-frame gliding window

Return type:

channel.MedianChannel

cellocity.validation.get_data_as_df(analyzer, analyzername)

Creates FlowSpeedAnalysis(), AlignmentIndexAnalysis() and IopAnalysis() from a FlowAnalyzer.

Calculates average frame speeds and alignment indexes and returns a DataFrame with the results.

Parameters:
Returns:

pd.DataFrame containing results and information derived from channel.name

Return type:

pandas.DataFrame

cellocity.validation.make_ai_plot(df)

Generates a plot comparing average frame alignment indexes from dataframe

cellocity.validation.make_channels(inpath)

Creates a list of Channel objects from files in inPath.

Parameters:inpath – Path
Returns:list of Channels
Return type:list
cellocity.validation.make_fb_flow_analyzer(ch)

Creates a FarenbackAnalyzer and performs optical flow calculations with default settings in um/s.

Parameters:ch – channel.Channel
Returns:anlysis.FarenbackAnalyzer
cellocity.validation.make_iop_plot(df)

Generates a plot comparing instantaneous order parameters

cellocity.validation.make_lcorr_plot(lcorrdf)

Generates a plot comparing correlation lengths between analyzers and magnifications

cellocity.validation.make_lcorr_proces_time_plot(lcorrdf)

Generates a bar plot comparing correlation length processing times for the two analyzers.

cellocity.validation.make_piv_analyzer(ch)

Creates an openPivAnalyzer and performs optical flow calculations with default settings in um/s.

Parameters:ch – channel.Channel
Returns:anlysis.OpenPivAnalyzer
cellocity.validation.make_proces_time_plot(df)

Generates a bar plot comparing processing times for the two analyzers.

cellocity.validation.make_speed_plot(df)

Generates a plot comparing average frame flow speeds from dataframe

cellocity.validation.processAndMakeDf(ch_list)

Creates analyzers from and runs test functions on a list of Channels.

Parameters:
  • ch_list (list) – List of Channel objects
  • outpath (pathlib.Path) – Path where to save output
Returns:

Pandas DataFrame with data from analysis

Return type:

pandas.DataFrame

cellocity.validation.run_5sigma_validation(inpath, outpath)

Runs the vaildation of the 5sigma analysis on files in inpath, saves figures and a csv in outpath.

Parameters:
  • inpath – input Path
  • outpath – output Path
Returns:

None

cellocity.validation.run_base_validation(inpath, outpath)

Runs the basic validation on data in inpath, saves figures and csv files in outpath.

Parameters:
  • inpath – input Path
  • outpath – output Path
Returns:

None