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
-
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
, ifFalse
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).
- Parameters
analyzer – Analyzer object
-
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
-
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.
- Parameters
analyzer – Analyzer object
-
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 & 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 :param kwargs: Additional arguments passed to self._draw_flow_frame() :type kwargs: dict
- 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 & 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 scalebar represent with its length the unit is set by the unit
given to the Analyzer :param kwargs: Additional arguments passed to self._draw_flow_frame() :type kwargs: dict
- 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.
- Parameters
analyzer – Analyzer object
-
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. IfTrue
(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
-
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
-
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
analyzer (analysis.FlowAnalyzer) – FlowAnalyzer
analyzername (str) – Name of FlowAnalyzer
- 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
- 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