Particle tracking tutorial

From Endrov



These screencasts exemplify the tool and how it is used:

Introduction and definition

Particle tracking is the process of following "particles" (an abstract notation for objects) in space over time. Endrov has it's root in 'C.elegans' cell tracking, and thus we also call this "lineaging".

A particle consist of

  • X,Y,Z,radius for some timepoints. We call these keyframes
  • Name of children (=new particles) formed by division)
  • Name of parents (=particles fused to create this particle)
  • An optional end-time when the particle stops exists
  • "Fate" - this can be used for anything
  • "Expression levels" - originally used for quantifying gene expression patterns, but they can be used for anything

Thus a particle can either split or fuse into new particles over time.

A particle is live (exists) from the first keyframe to either

  • it stops existing according to the optional end time
  • the first keyframe of a child

whichever comes first. If a particle is drawn stippled or not at all then it is not live. When you are done with your lineaging there should be no stippled particles except for the first ones in a recording. This definition means that unless you explicitly need your final particles to end, you never need to manually set the end-time.

The annotation process

This tutorial is about manual tutorial (automatic tools exist but we don't consider them reliable enough for general use). When you have several particles, lineaging ends up being a non-linear process; sometimes you start from a time-point and go forward, sometimes you go from the interesting final particle and backwards, and sometimes something in between. You might have to guess at a lineage only to correct it later or proceed while waiting to mark some nuclei. The lineage plugin was designed with all this in mind.

Forward lineaging is the process of lineaging from the first particles and tracking down all the children. Backwards lineaging is the other direction. There are no settings associated with the two ways of working, but this terminology will still be used.

There are three windows you need to know about:

  • The 2D viewer - This is the primary working window for working on the annotation.
  • The 3D viewer - Mainly for your visual perusal. However, it is also possible to do lineaging here to improve the resolution (add a 3D rendered channel for this). Our experience is however that lineaging in 2D is more efficient.
  • The lineage window - Once you have tracked down the coordinates then this will be the main tool for studying the tree (branching/fusing) structure.

You want to have all windows open at the same time, or at least the image and lineage window at a minimum. Dual monitors help. Multiple image windows help if you have several channels.

Prepare for lineaging

We assume that you have managed to imported your data and set the correct resolution. We cannot emphasize enough that the resolution need be set before any lineaging is done. Also, if you have multiple channels, align them first. There is a tool for this, or it can be done in the imageset meta window.

Note that all keys here may be changed. For convenience, you should add script bindings for the most common operations.

Annotate your first particle - basic manipulation

1. In the 2D viewer, select Lineage.New lineage. 2. Go to the frame and middle Z of the nucleus you wish to define. 3. Using left button, click and drag from the one side to the other in the nucleus. Release and the particle is there. 4. Go up and down in Z to confirm that the sphere fits (well enough). If not, your resolution setting is wrong. Correct this immediately.

You may want to fine-tune your definition. To do this, click the particle to select it:

  • To move it: Press the left mouse button and drag
  • To resize it: Click and hold the resize icon. Then move mouse up and down
  • To set the current Z as the midplane: Press the Z icon

Make sure you are in the same frame as the one you defined the particle in at all times.

Forward Lineaging

Move to the next frame. Decide which particle has moved enough that they need an update. Then use the fine-tuning procedure from the last section.

Note that Endrov interpolates data between keyframes. Sometimes it can be worth moving several keyframes before updating, and then go back to correct only the ones which has changed in a non-linear manner. This generates potentially smaller data files and you might get your job done faster.

If you are annotating a cell and it undergoes apoptosis then select, right click, and set the end-time. You can open the same dialog to remove the end time.

There are several ways to handle dividing particles. Our preference is to annotate the two new particles (annotate them at the same time). Then use shift-left-click to select all 3 particles. Right-click and select 'associate parent'. You can use the Lineage viewer to see that the operation worked out. You can use right-click to disconnect the parent later if you assumption turned out to be wrong.

If you really have no clue about parental relation then I suggest you just create new particle. The parent will stay as it is still live; if you find it annoying then temporarily give the parent an end-time to make it stop showing up later.

Backward Lineaging

First make sure you understand forward lineaging. Backward lineaging is similar. When you move backwards you will see that particles becomes stippled. This is because they are not "live" (=they do not really exist at this time). You can make them live back to the current frame by fine-tuning them the same way as for forward lineaging.

There is an inverse to splitting a particle: select two particles, right-click and select 'create parent'. The current frame will step back one step and a parent with all selected particles as children has been created. You can of course do this manually as well, linking the particles in the lineage window.

Lineage viewer operations

Some operations can only be performed in the lineage viewer. Only some examples will be provided here; for example, you can right-click on lineage tree to bring up a menu:

  • Delete keyframe: Deletes one key frame
  • Split here: If you accidentally continue to lineage into one of the children, you can split the keyframes into this particle, and put the rest into a new child. This operation does the work.

Rename template for 'C.elegans'

In the rename dialog, there is the 'Load template' feature. It allows you to select an OST XML file with an existing lineage. It will then give suggestions for names based on the name of the parent. This helps in particular for 'C.elegans' as you no longer will need to look up the nomenclature.