ocbe-uio / cellmaptracer

A user-friendly tracking system for long-term migratory and proliferating cells

CellMAPtracer

CellMAPtracer: A user-friendly tracking tool for long-term migratory and proliferating cells.

Getting Started

CellMAPtracer is built using MATLAB (v 9.8) and can be freely obtained as: (A) a standalone executable program for Microsoft Windows, macOS or GNU/Linux; (B) a MATLAB App/Toolbox; and (C) the source MATLAB code.

(A) CellMAPtracer standalone executable program.

Navigate to https://github.com/ocbe-uio/CellMAPtracer/releases/tag/v1.0. Three assets of CellMAPtracer for Windows, Linux and macOS versions can be found and downloaded. After downloading the version compatible with your Operating System, users should uncompress the file and follow the instructions in the corresponding “readme.txt”.

(B) CellMAPtracer MATLAB App

To be able to run CellMAPtracer App within the MATLAB environment, users should follow three simple steps: 1) Download the “App” folder from the CellMAPtracer repository: https://github.com/ocbe-uio/CellMAPtracer. 2) In MATLAB, go to APPS tab and click 'Install App' and find ”CellMAPtracer.mlappinstall” then install it. 3) Open CellMAPtracer App from Application list in MATLAB.

C) CellMAPtracer from the source MATLAB code

To be able to run CellMAPtracer code, users should clone the CellMAPtracer repository from https://github.com/ocbe-uio/CellMAPtracer and then run “CellMAPtracer_Main.m” after opening a project in MATLAB.

Tracking single cells

CellMAPtracer is capable of loading multi-TIFF stacks (8 and 16 bits) of spatio-temporal live cell images as input for tracking. The output is an interactive multi-generation trajectory plot and 5 categories of trajectory data. The 5 categories include: all cells, dividing cells, non-dividing cells, daughter cells and dividing daughter cells. Each of these contains two spreadsheets. The first sheet contains the measurements of cell migration parameters such as the total distance, displacement, directionality and speed. The second sheet contains the x-y coordinates of tracked cells in the corresponding category.

CellMAPtracer FUCCI plug-in

The CellMAPtracer FUCCI plug-in enables users to profile the fluorescent signals of FUCCI‐expressing cells in 2-3 channel systems. It detects the cell cycle phase at any given time point throughout the course of the tracking. The input of the FUCCI plug-in is a multi-TIFF stack in RGB format of spatio-temporal live cell images which should be associated with the outcome of the tracking outcome of CellMAPtracer for the corresponding multi-TIFF stacks (8 and 16 bits). After loading the needed files and selecting the cell cycle detection method, the FUCCI phase algorithm automatically implements an internal RGB normalization. Users can inspect the normalized and the raw signals and monitor the detection of the cell cycle phases with a possibility of correcting the detection.

A list of suggested online visualization tools

https://huygens.science.uva.nl/PlotsOfData

https://goodcalculators.com/box-plot-maker

https://chart-studio.plotly.com/create/box-plot/#/

http://www.alcula.com/calculators/statistics/box-plot

The CellMAPtracer paper

Ghannoum S, Antos K, Leoncio Netto W, Gomes C, Köhn-Luque A, Farhan H. CellMAPtracer: A User-Friendly Tracking Tool for Long-Term Migratory and Proliferating Cells Associated with FUCCI Systems. Cells. 2021; 10(2):469. https://doi.org/10.3390/cells10020469

cellmaptracer's Issues

Multiple data folders

The repository currently has two folders containing data: "Example data", containing a small text file, and "data", containing three large TIFF files. Is that structrure OK or would all data be better organized into one folder?

RPE script generates warnings

The following code generates warnings:

CellMAPtracer/Wiki/RPE_trajectory_analysis.R

Lines 196 to 238 in fd99ce8

	for (j in 1: length(DFF)){
	parents<-c()
	Offspring<-c()
	col=c()
	test<-sub("*\\..d*$", "", unlist(DFF[[j]]))
	for (i in 1:length(test)){
	if (!test[i]==DFF[[j]][i]){
	parents<-c(parents,test[i])
	Offspring<-c(Offspring,DFF[[j]][i])
	}
	}
	d = tibble(Offspring,parents)
	d2 = data.frame(from=d$parents, to=d$Offspring)
	g=graph_from_data_frame(d2)
	ordered.vertices <-get.data.frame(g, what="vertices")
	for (n in 1: length(parents)){
	if (Offspring[n] %in% parents){
	col=c(col,Offspring[n])
	}
	}
	COLOR<-c(rep("gray",length(ordered.vertices[,1])))
	for (i in 1:length(ordered.vertices[,1])){
	if (ordered.vertices[i,1]%in% col){
	COLOR[i]="lightgreen"
	}
	}
	TTT<-TT/TT[which.max(TT)]
	E(g)$weight <- TTT
	set.seed(100)
	test.layout <- layout_(g,with_dh(weight.edge.lengths = TTT))
	test.layout[,1]<-test.layout[,1] * 2
	test.layout[,2]<- test.layout[,2] *3.5
	pdf(paste0(j,".plot.pdf"))
	par(mar=c(0,0,0,0)+.1)
	plot(g,layout=test.layout,edge.arrow.size=0.64,edge.arrow.width = 2,edge.width=3.5,vertex.shape="circle",vertex.size=22,edge.color="black",
	vertex.color=adjustcolor(COLOR, alpha.f = .999),vertex.label.cex=0.65,vertex.label.font=2,vertex.label.color="black")
	dev.off()
	}

The warnings are the same, occur once per loop, and are of the following form:

In eattrs[[name]][index] <- value :
number of items to replace is not a multiple of replacement length

It's a bit cryptic, but the problem might be on any of the lines containing an assignment (<-).

These warnings end up showing on section 2 of the Wiki.

Not able to select cells to start a tracking sequence

Hi,

I used CellMapTracer over the last few months and it has been very helpful to my live-cell imaging analyses so far. Thank you for creating such a user-friendly tool.

Recently, I can't seem to select cells to begin a tracking sequence. When I click on "Track Single Cell," the window that opens up the first image of the multipage-TIFF appears, then I select a cell, but once I hit enter to begin tracking that cell, the window disappears without opening the tracking window. At this point the "Track Single Cell" button becomes grey and I can't try to select another cell. I was working directly from my laptop (version 12.4 mac) on the CellMAPtracer app (the standalone executable program). When this started to happen, I uninstalled the app and reinstalled it on MATLAB, but the same thing happens when I use cellmaptracer as a MATLAB app.

I was wondering if this might be a bug or if anyone knows what causes this issue

Thank you,
Maha

I cannot run this app

I ran the shell script on Mac, but it shows './run_CellMAPtracer.sh: line 29: ./CellMAPtracer.app/Contents/MacOS/CellMAPtracer: Permission denied'

Update README with new links and FUCCI info

From @alvarokoh's email:

update the Readme file with the new links and information about the new software features (FUCCI analysis).

@SystemsBiologist, do you need any help with this? I am not sure exactly what links and info should be added.

It would be best if this is done before we publish the new release, otherwise the updated README will not be part of it.

Loading image sequence or video file to track

Thanks for sharing your valuable codes. I provide some suggestion and some question.
suggestion:
I suggest you put a demo of your work in GitHub and also give some more explanation on how to use the software.
For example, upload a video or image in GitHub. Then use it in the software and show the results in the demo.
Question:
There is a menu in the software for load image that actually loads a tif image. How to track with a still image? it seems that for tracking application, a sequence of images or a video file is needed. How can i input my image sequence or video file into software?
Thank you very much and looking forward to hearing from you.
Regards

macOS version missing FUCCI plug-in

Summary

Please consider adding the FUCCI plug-in to the macOS version of CellMAPtracer, or at least making it clear that the function is not supported for that OS.

Original discussion

    how do I load the FUCCI plug-in on the CellMAPtracer MATLAB app?

Originally posted by @shreyasimodak in #4 (comment)

Add more colors to GUI

So far GUI is mainly gray. It could be nice to add more colors for instance some of the grey shadows in the Calculated Tracks and Cells Track Analysis could be in a light color, ( for instance light orange or similar). The Track Single Cell button could also be highlighted in some more strong color

Fix version number in title

Summary

Even though we've installed CellMAPtracer 1.1, the title bar shows "1.00" (Linux and macOS). This is very confusing, since there's no other indication about which version we're running.

Original discussion

    how do I load the FUCCI plug-in on the CellMAPtracer MATLAB app?

Originally posted by @shreyasimodak in #4 (comment)