Use cases

1. Giant cell tracking (data-based)¶

1.1. Using the interface¶

Problem: Track the surface area over time of one individual.

1. Launch the GUI:

Cellects

2. Load images via Data Localisation:

• Prefix: im
• Extension: .tif
• Arena number per folder: 1

3. Image analysis → apply config, validate specimen/arena, etc.

4. Video tracking → Done → Post processing → Read

5. Save one result to export CSV time series.

1.2. Using scripts (API)¶

This section runs with an example data set available here.

In [1]:

import os

from cellects.core.cellects_paths import DATA_DIR
from cellects.core.program_organizer import ProgramOrganizer
from cellects.core.cellects_threads import VideoTrackingThread
from cellects.display.image import show
from cellects.display.plot import curve
from cellects.image.morphological_operations import add_mask_contour

# 1. Set up parameters to find the data
po = ProgramOrganizer()
po.all['global_pathway'] = str(DATA_DIR / "single_experiment")
po.all['folder_number'] = 1
po.all['first_folder_sample_number'] = 1
po.all['radical'] = 'image'
po.all['extension'] = 'tif'
po.all['im_or_vid'] = 0

# 2. Run a video tracking pipeline
po.vars['convert_for_motion'] = {'lab': [0, 0, 1]}
video_tracking  = VideoTrackingThread(po)
video_tracking.pre_processing()
video_tracking.run_video_writing()
video_tracking.one_detection()
video_tracking.post_processing()

# 3. Display the last image with its segmentation contour
final_image = add_mask_contour(po.motion.visu[-1, :, :, ::-1], po.motion.segmented[-1])
show(final_image, axes=False, show=False)

# 4. Plot the growth curve
curve(y=po.motion.segmented.sum((1, 2)), y_label='Surface area (pixels)', x_label='Time (frames)')

import os from cellects.core.cellects_paths import DATA_DIR from cellects.core.program_organizer import ProgramOrganizer from cellects.core.cellects_threads import VideoTrackingThread from cellects.display.image import show from cellects.display.plot import curve from cellects.image.morphological_operations import add_mask_contour # 1. Set up parameters to find the data po = ProgramOrganizer() po.all['global_pathway'] = str(DATA_DIR / "single_experiment") po.all['folder_number'] = 1 po.all['first_folder_sample_number'] = 1 po.all['radical'] = 'image' po.all['extension'] = 'tif' po.all['im_or_vid'] = 0 # 2. Run a video tracking pipeline po.vars['convert_for_motion'] = {'lab': [0, 0, 1]} video_tracking = VideoTrackingThread(po) video_tracking.pre_processing() video_tracking.run_video_writing() video_tracking.one_detection() video_tracking.post_processing() # 3. Display the last image with its segmentation contour final_image = add_mask_contour(po.motion.visu[-1, :, :, ::-1], po.motion.segmented[-1]) show(final_image, axes=False, show=False) # 4. Plot the growth curve curve(y=po.motion.segmented.sum((1, 2)), y_label='Surface area (pixels)', x_label='Time (frames)')

2. Colony growth tracking (synthetic example)¶

Problem: Get the surface area over time of several appearing colonies.

This example is self-contained to produce graphical representation.

In [2]:

import numpy as np
from cellects.simulation.colonies import growing_colonies
from cellects.image.image_segmentation import convert_subtract_and_filter_video
from cellects.core.program_organizer import ProgramOrganizer
from cellects.video.motion_analysis import MotionAnalysis
from cellects.display.image import show
from cellects.display.plot import curve

# 1) Generate synthetic data
rgb_video = growing_colonies()

# 2) Set up parameters to find the data
po = ProgramOrganizer()
po.update_variable_dict()
po.get_first_image(rgb_video[0,...])

# 3) Segment the first image and compute other parameters
po.vars['several_blob_per_arena'] = True
po.fast_first_image_segmentation()
po.get_average_pixel_size()
po.save_origins_and_backgrounds_lists()
po.find_if_lighter_background()

# 4) Set up video tracking parameters
po.all['im_or_vid'] = 1
show_seg= False
po.vars['maximal_growth_factor'] = 0.5
po.vars['frame_by_frame_segmentation'] = True
po.vars['do_threshold_segmentation'] = False
po.vars['do_slope_segmentation'] = False
po.vars['specimen_activity'] = 'grow'
converted_video, _ = convert_subtract_and_filter_video(rgb_video, po.vars['convert_for_motion'])
videos_already_in_ram = [rgb_video, converted_video]
l = [0, 1, po.vars, True, False, show_seg, videos_already_in_ram]

# 5) Run motion analysis
ma = MotionAnalysis(l)

# 6) Show video segmentation mask (color represents time)
_ = show(np.cumsum(ma.binary, 0)[-1], axes=False, show=False)

# 7) Compute descriptors over time
po.vars['save_coord_specimen'] = False
ma.get_descriptors_from_binary()

# 8) PLot the total surface covered by colonies over time
curve(y=ma.one_row_per_frame['area_total'], y_label='Summed surface area (pixels)', x_label='Time (frame)')

import numpy as np from cellects.simulation.colonies import growing_colonies from cellects.image.image_segmentation import convert_subtract_and_filter_video from cellects.core.program_organizer import ProgramOrganizer from cellects.video.motion_analysis import MotionAnalysis from cellects.display.image import show from cellects.display.plot import curve # 1) Generate synthetic data rgb_video = growing_colonies() # 2) Set up parameters to find the data po = ProgramOrganizer() po.update_variable_dict() po.get_first_image(rgb_video[0,...]) # 3) Segment the first image and compute other parameters po.vars['several_blob_per_arena'] = True po.fast_first_image_segmentation() po.get_average_pixel_size() po.save_origins_and_backgrounds_lists() po.find_if_lighter_background() # 4) Set up video tracking parameters po.all['im_or_vid'] = 1 show_seg= False po.vars['maximal_growth_factor'] = 0.5 po.vars['frame_by_frame_segmentation'] = True po.vars['do_threshold_segmentation'] = False po.vars['do_slope_segmentation'] = False po.vars['specimen_activity'] = 'grow' converted_video, _ = convert_subtract_and_filter_video(rgb_video, po.vars['convert_for_motion']) videos_already_in_ram = [rgb_video, converted_video] l = [0, 1, po.vars, True, False, show_seg, videos_already_in_ram] # 5) Run motion analysis ma = MotionAnalysis(l) # 6) Show video segmentation mask (color represents time) _ = show(np.cumsum(ma.binary, 0)[-1], axes=False, show=False) # 7) Compute descriptors over time po.vars['save_coord_specimen'] = False ma.get_descriptors_from_binary() # 8) PLot the total surface covered by colonies over time curve(y=ma.one_row_per_frame['area_total'], y_label='Summed surface area (pixels)', x_label='Time (frame)')

3. Migrating cells tracking (synthetic example)¶

Problem: Get each cell direction.

This example is self-contained to produce graphical representation.

In [3]:

from cellects.simulation.migration import moving_cells
from cellects.image.image_segmentation import convert_subtract_and_filter_video
from cellects.core.program_organizer import ProgramOrganizer
from cellects.video.motion_analysis import MotionAnalysis
from cellects.display.image import show
from cellects.display.plot import plot_blob_directions, plot_spider_binned

# 1) Generate synthetic data
rgb_video = moving_cells()

# 2) Set up parameters to find the data
po = ProgramOrganizer()
po.update_variable_dict()
po.get_first_image(rgb_video[0,...])

# 3) Segment the first image and compute other parameters
po.vars['several_blob_per_arena'] = True
po.fast_first_image_segmentation()
po.get_average_pixel_size()
po.save_origins_and_backgrounds_lists()
po.find_if_lighter_background()

# 4) Set up video tracking parameters
po.all['im_or_vid'] = 1
show_seg= False
po.vars['maximal_growth_factor'] = 0.5
po.vars['frame_by_frame_segmentation'] = True
po.vars['do_threshold_segmentation'] = False
po.vars['do_slope_segmentation'] = False
po.vars['specimen_activity'] = 'move'
converted_video, _ = convert_subtract_and_filter_video(rgb_video, po.vars['convert_for_motion'])
videos_already_in_ram = [rgb_video, converted_video]
l = [0, 1, po.vars, True, False, show_seg, videos_already_in_ram]

# 5) Run motion analysis
ma = MotionAnalysis(l)

# 6) Compute descriptors over time
po.vars['save_coord_specimen'] = False
ma.get_descriptors_from_binary()

# 7) Display cell motion from the first to the last frame
blob_directions = plot_blob_directions(ma.cc_coord, ma.cc_centroids, max_colony_number=25, selection_criteria='lifetime')
show(blob_directions, axes=False, show=False)

# 8) Display cell motion from the first to the last frame
plot_spider_binned(ma.cc_centroids, num_intervals=10)

from cellects.simulation.migration import moving_cells from cellects.image.image_segmentation import convert_subtract_and_filter_video from cellects.core.program_organizer import ProgramOrganizer from cellects.video.motion_analysis import MotionAnalysis from cellects.display.image import show from cellects.display.plot import plot_blob_directions, plot_spider_binned # 1) Generate synthetic data rgb_video = moving_cells() # 2) Set up parameters to find the data po = ProgramOrganizer() po.update_variable_dict() po.get_first_image(rgb_video[0,...]) # 3) Segment the first image and compute other parameters po.vars['several_blob_per_arena'] = True po.fast_first_image_segmentation() po.get_average_pixel_size() po.save_origins_and_backgrounds_lists() po.find_if_lighter_background() # 4) Set up video tracking parameters po.all['im_or_vid'] = 1 show_seg= False po.vars['maximal_growth_factor'] = 0.5 po.vars['frame_by_frame_segmentation'] = True po.vars['do_threshold_segmentation'] = False po.vars['do_slope_segmentation'] = False po.vars['specimen_activity'] = 'move' converted_video, _ = convert_subtract_and_filter_video(rgb_video, po.vars['convert_for_motion']) videos_already_in_ram = [rgb_video, converted_video] l = [0, 1, po.vars, True, False, show_seg, videos_already_in_ram] # 5) Run motion analysis ma = MotionAnalysis(l) # 6) Compute descriptors over time po.vars['save_coord_specimen'] = False ma.get_descriptors_from_binary() # 7) Display cell motion from the first to the last frame blob_directions = plot_blob_directions(ma.cc_coord, ma.cc_centroids, max_colony_number=25, selection_criteria='lifetime') show(blob_directions, axes=False, show=False) # 8) Display cell motion from the first to the last frame plot_spider_binned(ma.cc_centroids, num_intervals=10)

4. Network detection (data-based)¶

Problem: Study growth to find its higher rate

This section runs with an example data set available here.

In [4]:

from numba.typed import Dict, List
import pandas as pd
from cellects.core.cellects_paths import DATA_DIR
from cellects.display.image import show, draw_graph
from cellects.display.param import firebrick_rgb
from cellects.image.network_functions import NetworkDetection
from cellects.io.load import readim
from cellects.image.morphological_operations import add_mask_contour, keep_one_connected_component
from cellects.image.network_functions import get_skeleton_and_widths, EdgeIdentification
from cellects.display.image import display_network_methods

# 1. Read one image
im_path = str(DATA_DIR / "single_experiment" / "image25.tif")
img = readim(im_path)

# 2. Convert the image to greyscale
greyscale = img.mean(-1)
lighter_background = True

# 3. Run network detection
NetDet = NetworkDetection(greyscale)
NetDet.get_best_network_detection_method()

# 4. Display the result of all methods
display_network_methods(NetDet)

# 5. Select a good one (here the 2nd) and keep the largest connected component
binary_network = keep_one_connected_component(NetDet.all_results[2]['binary'])

# 6. Display the network contour on the original image
final_image = add_mask_contour(img[:, :, ::-1], binary_network, color=firebrick_rgb)
show(final_image, axes=False, show=False)

# 7. Compute the skeleton of the network
pad_skeleton, pad_distances, pad_origin_contours = get_skeleton_and_widths(binary_network)

# 8. Identify all elements of the graph from that skeleton
edge_id = EdgeIdentification(pad_skeleton, pad_distances)
edge_id.run_edge_identification()
edge_id.make_vertex_table()
edge_id.make_edge_table(greyscale)

# 9. Name the content of the tables with pandas
vertex_table = pd.DataFrame(edge_id.vertex_table, columns=["y", "x", "vertex_id", "is_tip", "origin", "vertex_connected"])
edge_table = pd.DataFrame(edge_id.edge_table,
                          columns=["edge_id", "vertex1", "vertex2", "length", "average_width", "intensity",
                                   "betweenness_centrality"])

# 10. Display the graph
graph = draw_graph(img, vertices=vertex_table, edges=edge_table)
show(graph, axes=False, show=False)

from numba.typed import Dict, List import pandas as pd from cellects.core.cellects_paths import DATA_DIR from cellects.display.image import show, draw_graph from cellects.display.param import firebrick_rgb from cellects.image.network_functions import NetworkDetection from cellects.io.load import readim from cellects.image.morphological_operations import add_mask_contour, keep_one_connected_component from cellects.image.network_functions import get_skeleton_and_widths, EdgeIdentification from cellects.display.image import display_network_methods # 1. Read one image im_path = str(DATA_DIR / "single_experiment" / "image25.tif") img = readim(im_path) # 2. Convert the image to greyscale greyscale = img.mean(-1) lighter_background = True # 3. Run network detection NetDet = NetworkDetection(greyscale) NetDet.get_best_network_detection_method() # 4. Display the result of all methods display_network_methods(NetDet) # 5. Select a good one (here the 2nd) and keep the largest connected component binary_network = keep_one_connected_component(NetDet.all_results[2]['binary']) # 6. Display the network contour on the original image final_image = add_mask_contour(img[:, :, ::-1], binary_network, color=firebrick_rgb) show(final_image, axes=False, show=False) # 7. Compute the skeleton of the network pad_skeleton, pad_distances, pad_origin_contours = get_skeleton_and_widths(binary_network) # 8. Identify all elements of the graph from that skeleton edge_id = EdgeIdentification(pad_skeleton, pad_distances) edge_id.run_edge_identification() edge_id.make_vertex_table() edge_id.make_edge_table(greyscale) # 9. Name the content of the tables with pandas vertex_table = pd.DataFrame(edge_id.vertex_table, columns=["y", "x", "vertex_id", "is_tip", "origin", "vertex_connected"]) edge_table = pd.DataFrame(edge_id.edge_table, columns=["edge_id", "vertex1", "vertex2", "length", "average_width", "intensity", "betweenness_centrality"]) # 10. Display the graph graph = draw_graph(img, vertices=vertex_table, edges=edge_table) show(graph, axes=False, show=False)

Out[4]:

(<Figure size 300x245 with 1 Axes>, <Axes: >)

5. Sigmoid growth (synthetic example)¶

Problem: Compute growth rate from sigmoid-like data (delayed growth and ending plateau)

This example is self-contained to produce graphical representation.

In [5]:

import numpy as np
from cellects.video.growth_features import find_growth_features
from cellects.display.plot import plot_growth_features

x = np.linspace(0, 15, 300)
y = 1 / (1 + np.exp(-x + 6))
time_step = 0.5
first_growth = 0.1
growth_features = find_growth_features(y=y, time_step=time_step, first_growth=first_growth, first_frame=1)
plot_growth_features(y, time_step, growth_features)

import numpy as np from cellects.video.growth_features import find_growth_features from cellects.display.plot import plot_growth_features x = np.linspace(0, 15, 300) y = 1 / (1 + np.exp(-x + 6)) time_step = 0.5 first_growth = 0.1 growth_features = find_growth_features(y=y, time_step=time_step, first_growth=first_growth, first_frame=1) plot_growth_features(y, time_step, growth_features)

Small task examples¶

Task 1: Write a timelapse video from images¶

Problem: Convert a set of images into a timelapse video.

To use this functionality, install Cellects and run the following python code:

from cellects.io.save import write_video_from_images
write_video_from_images("path/to/images")

Task 2: Extracting image capture timings¶

Problem: Get the capture timing of every image using their exif data

To use this functionality, install Cellects and run the following python code:

from cellects.io.save import extract_time
times = extract_time("path/to/images")

Task 3: Getting the greyscale video(s) of arena(s)¶

Problem: Convert a set of images into greyscale videos, making one per arena

To use this functionality, install Cellects and run the following python code:

In [6]:

from cellects.core.program_organizer import ProgramOrganizer
from cellects.core.cellects_paths import DATA_DIR
from cellects.core.cellects_threads import VideoTrackingThread
from cellects.display.image import show

po = ProgramOrganizer()
po.all['global_pathway'] = str(DATA_DIR / "single_experiment")
po.all['folder_number'] = 1
po.all['first_folder_sample_number'] = 1
po.all['radical'] = 'image'
po.all['extension'] = 'tif'
po.all['im_or_vid'] = 0
# Set the arena id to run
po.all['arena'] = 1
# Create a video tracking instance
video = VideoTrackingThread(po)
video.pre_processing()
video.load_one_arena()
_ = show(video.po.motion.converted_video[-1, :, :], cmap="grey", axes=False, show=False)

from cellects.core.program_organizer import ProgramOrganizer from cellects.core.cellects_paths import DATA_DIR from cellects.core.cellects_threads import VideoTrackingThread from cellects.display.image import show po = ProgramOrganizer() po.all['global_pathway'] = str(DATA_DIR / "single_experiment") po.all['folder_number'] = 1 po.all['first_folder_sample_number'] = 1 po.all['radical'] = 'image' po.all['extension'] = 'tif' po.all['im_or_vid'] = 0 # Set the arena id to run po.all['arena'] = 1 # Create a video tracking instance video = VideoTrackingThread(po) video.pre_processing() video.load_one_arena() _ = show(video.po.motion.converted_video[-1, :, :], cmap="grey", axes=False, show=False)

Removing temporary files¶

In [7]:

from cellects.io.save import tear_down_temp_files
tear_down_temp_files()

from cellects.io.save import tear_down_temp_files tear_down_temp_files()