Skip to content, Skip to search


Getting started with MaMuT

453 bytes removed, 10:02, 20 March 2018
Fix typo
This page contains a tutorial for the [[MaMuT]] plugin. It describes and document all its features using a publication related dataset.
== Publication. ==
If you find MaMuT useful for your research, please cite it:
''Reconstruction of cell lineages and behaviors underlying arthropod limb outgrowth with multi-view light-sheet imaging and tracking'', Carsten Wolff, Jean-Yves Tinevez, Tobias Pietzsch, Evangelia Stamataki, Benjamin Harich, Stephan Preibisch, Spencer Shorte, Philipp J Keller, Pavel Tomancak, Anastasios Pavlopoulos '''bioRxiv''' 112623; doi:{{Publication | MaMuT}}
=== The BigDataViewer framework and large, multi-view images. ===
The MaMuT viewer is really a BigDataViewer window, so if you are familiar with this plugin, everything you know applies there. If are not, here is a recapitulation of how the BigDataViewer works and how to interact with it.
A little word on the BigDataViewer: The BigDataViewer was made to deal with very large images of a sample possibly acquired from several different orientations (e.g. rotating the sample in a SPIM). These different orientations (or views, but here we use this word for another notion) of the data amount to a new dimension. This dimension if more complex to handle than e.g. multiple channels, because changing the acquisition orientation generates a data block which is not aligned with the other blocks (rotated, translated, and if you change the magnification, scaled), and does not have necessary the same size. As of today, only a limited numbers of image viewers can deal with multiple orientations, and the BigDataViewer is one of them.
* {{key press|Mousewheel}} Move along the Z-axis of the view. Press {{key press|Shift}} or {{key press|Control}} to change the speed.
* {{key press|Alt-Mousewheel}} (Mac and Linux) or {{key press|Ctrl-Shift-Mousewheel}} (Windows) Zoom in and out.
* {{key press|\textuparrowup}} / {{key press|\textdownarrowdown}} Zoom in / out. With {{key press|Shift}} fast zoom. With {{key press|Control}} slow zoom.
* {{key press|Left Drag}} Rotate around the point where the mouse was clicked.
* {{key press|X}} / {{key press|Y}} / {{key press|Z}} Select rotation axis.
* {{key press|\textleftarrowup}} / {{key press|\textrightarrowdown}} Rotate clockwise / counter-clockwise around the chosen rotation axis.
* {{key press|,}} / {{key press|.}} Move forward / backward along the z-axis.
* {{key press|Shift|X}} Rotate to the ZY-plane of the current source (look along the x-axis of the current source).
=== Configuring the source visibility and display. ===
Switching from one source to another is done with the numeric keys {{key press|1}} ... {{key press|0}} for up to 10 views. Pressing {{key press|F}} switches to the fused mode, where all sources are overlaid. You can add and remove sources from the fused view by pressing {{key press|Shift|1}} - etc. The color and brightness of each source are defined in the \textbf{'''brightness and color} ''' panel, brought by pressing the {{key press|S}} key.
Move the mouse pointer over the cell you want to annotation, and press {{key press|A}}. A magenta circle should appear, representing a cell or more generally, a spot. Spots are created, edited and removed using the following default key bindings:
\begin{myitemize} \item * {{key press|A}} to add a spot at the mouse location. \item * {{key press|D}} to delete the spot under the mouse location. \item * {{key press|Q}} / {{key press|E}} to decrease / increase the spot radius. Use {{key press|Shift}} / {{key press|Control}} to change the radius by a greater / smaller amount. \item * {{key press|Space}} is used to move a spot in the XY view plane: put the mouse pointer inside the spot you want to move, then press and hold space while moving the mouse. The spot will follow your mouse until you release the {{key press|Space}} key.\end{myitemize}
Spots represents point of interest (in our case, cells) under the shape of a sphere. You can change the sphere time-point, location and radius, but that's it. There is no object contour in MaMuT. Spots are drawn as circles in the MaMuT viewer, with the radius of their intersection with the view XY plane. If they are not intersecting with the view plane, they are drawn as small dots, as you can see by moving along Z a bit.
Now is a good time to talk a little bit on how we control the look of spots on the MaMuT viewer. All the MaMuT are in sync and they share common display settings. It is not possible to separately tune the display of each view. Display settings for spots can be tuned on the main GUI window, in the top part of the '''Views''' tab. Here you can toggle the visibility of all spots, make their name appear. The display radius simple change their apparent radius on the MaMuT viewer. This display setting has no impact on subsequent analysis and apart from visibility tidiness, it will have its utility later.
The spot coloring colouring uses the notion of ''numerical features''. In MaMuT, and as in TrackMate, each annotation object can have several numerical, scalar features associated. For instance a spot can have features like X, Y, Z for its position, etc. The drop-box menu \textbf{'''Set color by} ''' lets you choose the feature you want to use for the spot color. The color range below the menu shows you the min and max value for the feature you picked over all the dataset and interpolate from blue to red with a jet color-map. If you scroll through the menu, you can see that the features available are sorted in three categories: <tt style="font-size: 1.25em;">spot features</tt>, <tt style="font-size: 1.25em;">default</tt> and <tt style="font-size: 1.25em;">track features</tt>. <tt style="font-size: 1.25em;">Spot features</tt> is the category where you can find all the numerical features that relate to single spots, like their position, radius, ''etc.'' In <tt style="font-size: 1.25em;">default</tt>, colors colours are not picked from a numerical feature, but either all the same (uniform color) or set manually (we will see later how). The <tt style="font-size: 1.25em;">track feature category</tt> is special: it gives to spots the color taken from the feature of the ''track'' they belong to.
We propagate the identity of a cell over time using several spots in several time-points, connected from one to its successor by ''links''. Particle-linking algorithms are algorithms that find automatically what are the right links from one time-point to another given a set of spots spread over several time-points. Of course, the definition of "right" depends on the specificity of the algorithm. Tracking is the process of finding automatically all spots in an 2D+T or 3D+T image, and linking them. MaMuT does not do fully automatic tracking. It is a tool that specializes in manual or semi-automatic tracking, privileging data exploration and manual annotation on very large images. However, we will show in another tutorial how to import the results of automated tracking algorithms in MaMuT, so that they can be verified and curated. Here, we limit ourselves to manual and semi-automatic tracking.
A link is a directed relationship from a spot, called the source, to another spot, called the target. The source spot is always the predecessor in time, so links always point towards increasing time. All the spots that can be reached from a spot by crossing links form what is called a ''track''. In our case, a track represents a lineage from a single starting (founder) cell lineage.
The actual data structure behind the annotations in MaMuT (and TrackMate) is a ''simple directed graph''. A graph is a mathematical structure made of vertices (in our case, spots representing cells) connected by edges (in our case, links representing propagation of identify identity across several time-points). The graph is ''simple'' because it is forbidden to have more than one link between two spots, and that a link cannot link a spot to itself. It is ''directed'' because links have a direction, following increasing time. In MaMuT, we added an extra constraint that forbids the existence of a link between two spots belonging to the same time-point, but otherwise this data structure is very standard.
So a link can be created between any two spots, provided they do not belong to the same time-point. There is no other restriction. For instance, a spot can be the source of several links. If there is two outgoing links from a spot, they may represent a cell division (mother cell linked to its two daughters). Several source spots can be linked to a single common target spot, though the biological meaning of this is less evident. MaMuT does not put constraints on the number of links going from or to a spot. We reasoned that MaMuT is to be used to build generic graph-like annotations, and that the subsequent analysis should be specific to the biological context. For instance, for cell lineaging there should be at most two outgoing links from a source spot, and at most one ingoing link on a target spot.
* Press {{key press|L}} to add a link between these two spots, or to remove it already exists.
So here are the two new useful bindings for \textbf{'''editing links}''':
* {{key press|Shift-Left Click}} add and remove spots from the selection.
Note that when you create a link with this method, after link creating the selection is set to be made of only the last spot added. To create the next link, you just have to add the target spot to the selection, the source spot is already in. But still, after creating links over only 10 time-points, lets recognize let us admit that this is probably not the best quickest way to quickly create a lineage. This method is probably best suited to edit an existing annotation.
=== The auto-linking mode. ===
Press {{key press|Shift-L}} with a MaMuT viewer window active. A message should appear in the MaMuT viewer that states the auto-linking mode is now on. In this mode, a link is automatically created when you create a new spot between this spot and the last one in the selection. Then the selection is changed to be the last spot added. Using this, you can quickly create lineage by moving forward in time with the keyboard and creating spots by typing {{key press|A}}. You can also use {{key press|Double Click}} to create spots, but because a simple click would clear the selection, you have to hold the {{key press|Shift}} key down to use auto-linking with mouse clicks.
Try to use the auto-linking mode to create the cell lineage of the dividing cell above, this time following the other daughter cell. Move back to the first time-point, select the mother cell, move to the second time-point {{key press|M}} and add a spot {{key press|A}} or {{key press|Shift-Double Click}} on the cell location. Repeat by following the right daughter cell. You should end up with an annotation that resembles the following:
If you are on a time-point not a multiple of the time-step, the next key-press will move to the closest multiple. The goal of these commands is to quickly generate a lineage that extends deeply in time by skipping some frames. But the time-points we reach with these commands are always the same multiples, so the annotated frames are all the same when using the stepwise time browsing.
Below is an example from an actual annotation, peeking ahead the lineage visualizer we will describe in the next section. Inn In this view , cells are arranged by lineage, time running from top to bottom. Time-points are lines of alternating color. You can see that except when cells are dividing or when there is an ambiguity, this user only annotated time-points multiples of 5. This leads to a sparser annotation, generated faster.
* <tt style="font-size: 1.25em;">Show all entire tracks</tt> is the default and display all the whole tracks with no time cue.
* <tt style="font-size: 1.25em;">Show local tracks</tt> only shows a portion of the track which extend shortly before and after the current time-point. As the time distance increases, the track display fades in the image using transparency. You can control how much time context you want to display using the \textbf{'''Limit frame depth} ''' checkbox and the '''Frame depth''' field.
* <tt style="font-size: 1.25em;">Show local tracks, backward</tt> is similar, but only extends tracks backward in time (this mode is sometimes nicknamed 'dragon tail' in other softwares).
* <tt style="font-size: 1.25em;">Show local tracks, forward</tt> is the same thing, but forward in time.
* The numeric keypad numbers {{key press|6}}, {{key press|9}}, {{key press|8}}, {{key press|7}}, {{key press|4}}, {{key press|1}}, {{key press|2}} and {{key press|3}} are used to move as on a compass.
* {{key press|+}} zoom in.
* {{key press|{-}}} zoom out.* {{key press|{=}equals}} restores the zoom to its default level.
The top-left part of the TrackScheme window shows the outline of the graph. The blue square represents the current view and can be resized and moved around.
[[Image:bdv-MaMuT_TrackSchemeOutline.png |500px]]
=== Configuring TrackScheme look. ===
=== Managing a selection in TrackScheme. ===
[[TrackScheme]] is useful to build a selection and query its properties. As we said above, \TrackScheme does not abide any visibility setting. Spots and links are always visible, which is useful to build a selection. Spots and links are added to the current selection in a classical way:
* {{key press|Left-Click}} on a spot or link to set the selection with this spot or link. The selection is cleared before.
For instance, you can use it to only display a series of disjoint parts of a tracks:
=== TrackScheme info-pane and feature plots. ===
== \TrackScheme key-bindings. ==
\TrackScheme key-bindings cannot be remapped like for the MaMuT viewer. We list them here.
| style="padding: 5px;" | Center view on the last spot in current selection.
| style="padding: 5px;" | {{key press|+}} & {{key press|=equals}}
| style="padding: 5px;" | Zoom in.
| style="padding: 5px;" | Zoom out.
| style="padding: 5px;" | {{key press|Shift|=equals}}
| style="padding: 5px;" | Reset zoom.
| style="padding: 5px;" | Clear selection.
| style="padding: 5px;" | {{key press|\textuparrowup}} / {{key press|\textdownarrowdown}}
| style="padding: 5px;" | Move to the previous / next spot in time, within the current track.
| style="padding: 5px;" | {{key press|\textleftarrowleft}} / {{key press|\textrightarrowright}}
| style="padding: 5px;" | Move to the previous / next sibling, within the current track. Sibling are spots that belong to the same track and to the same time-point. For instance the two spots of two sister daughter cells.