The selection creator.

The automated detection process we use often generates a lot of spurious detections. In TrackMate we complemented it by adding feature filters just after the detection step. In TrackMate UI it takes the shape of filter windows, where the user can specify a feature and a threshold above or below which spots are rejected. The filters can be stacked to generate a more stringent filtering. This approach is like fishing with a small-hole net, then throwing back unwanted fishes to sea.

In Mastodon we take a somewhat different approach. We don’t have a filter interface, but instead work with a dedicated tool called the selection creator that we describe it here. It works differently from the interactive selection we have in TrackMate. Instead of manually clicking on spots or links, or drawing a selection rectangle in TrackScheme, you will enter an expression that will be parsed to generate a selection. The expression uses a basic language that allows translating criteria like select all spots that have an intensity larger than X and their links.

We thought this approach would be more convenient and powerful, and the selection is especially important in Mastodon. Indeed:

  • You can create a selection to tag several data items that follow a certain criterion.

  • The selection can be used as an input for the linking algorithms (see the getting started tutorial).

  • The BDV views can be used to only show the selection you just created.

  • The selection content can be inspected in the selection table and inspected with the grapher views.

The selection creator window.

We will be using the TRIF dataset from the cell tracking challenge for this tutorial. You can download it from Zenodo:

DOI

Download the .mastodon and the .xml files, and put them in the same folder. The image data is stored on the Pasteur BDV-server and Mastodon will stream the data from there.

The selection creator tool can be called from the Plugins > Selection Creator menu, but is also a tab in the Preferences window:

image

image

The window for the tool is very simple. It contains a text field for the expression, and another one that contains an editable description. The Run button evaluates the current expression, which results in an error or in the selection being modified. Several built-in examples are included, and there is a Help button that opens a document recapitulating the expression syntax.

Expression are stored and saved with the same menu that for the settings (TrackScheme styles, BDV render settings, etc). When you press the apply button, they are saved to a file in the .mastodon folder in your home folder, called selectioncreatorexpressions.yaml. For instance:

>> pwd
/Users/tinevez/.mastodon
>> cat selectioncreatorexpressions.yaml
Vertices with a tag
--- !selectioncreatorsettings {name: Spots with 1 link in frame 25, expression: vertexFeature('Spot
    N links') == 1 & vertexFeature('Spot frame') == 25, description: Spots with 1
    link in frame 25.}
--- !selectioncreatorsettings {name: Vertices with 1 link minus those in frame 25,
  expression: (vertexFeature('Spot N links') == 1) - (vertexFeature('Spot frame')
    == 25), description: Vertices with 1 link minus those in frame 25.}

Selection based on spot feature values.

Let’s see how we can select spots based on numerical features. We will be mainly playing with the expression field. First, in the top drop-down list, select the builtin example called X larger than 100, then click the Run button. This should be displayed:

image

And in a BDV window, you should see that most of the spots have been selected, saved for a few.

image

Let’s have a look at the expression we used. In the selection creator, you enter expressions that are evaluated for all the data items. The expression must evaluate to a boolean answer: a true or false answer for each of the data item currently in mastodon. In our example we have:

vertexFeature('Spot position', 'X') > 100.

The keyword vertexFeature is a function that will fetch numerical values from a spot feature, for all spots. The arguments of this function are first, the feature name (Spot position) and second, the projection name X.

Indeed, many features aggregates several projections. A projection is a component of a feature that is always a real scalar. For instance, the Spot position feature is composed of 3 projects: X, Y and Z. See the part on numerical feature computation in the tutorial on the table views for more details. Anyway, we need to remember that the vertexFeature function will return a scalar value for all spots, so it needs a feature projection to be specified.

In the last part of the expression, we have a boolean comparison resulting in a boolean result: > 100. (the dot only stresses that 100 is floating point number). So with this expression, all the spots that have a X position larger than 100 will evalute to true with this expression, and therefore will be added to the selection.

We use thestrictly great than operator >, but any comparison operator would have worked:

  • > strictly greater than

  • < strictly smaller than

  • >= greater than

  • <= smaller than

  • == equal to

  • != different from

This is the basis for the whole selection creator framework. You can enter any kind of mathematical expression based on the keyword supported, and it will be turned in a selection if it evaluates to a boolean results.

Let’s make errors.

Because the selection creator accepts expressions that can be anything, it is likely that we will have error messages at some point. Let’s spend some time generating errors on purpose.

First let’s try removing the comparison:

vertexFeature('Spot position', 'X')

If we click the Run button we get the following error message:

Evaluation failed. Got unexpected result: 
VertexFeature( Spot position → X, 256609 )

This is expected. The selection creator expects expressions to evaluate to booleans. When we removed the comparison operator (< 100.) we returned the X position for the 256609 spots in the model, and the selection creator does not know how to turn this into a selection. So we need to remember that we always need to use expressions that evaluates to booleans.

Let’s test an expression without specifying the projection name in the vertexFeature function:

vertexFeature('Spot position') > 100.

Now we get:

Evaluation failed. Incorrect syntax: Calling vertexFeature: 
The projection key 'Spot position' is unknown to the feature 
'Spot position'.

Here the selection creator complains because we did not specify the projection in the call. It then tried to find a projection with name identical to the feature name (Spot position) and could not find one. So it complained. We would get the same error message if we tried calling the function with the name of a projection that does not exist. For instance vertexFeature('Spot position', 'U') > 100.

A similar error would be triggered when calling a feature that does not exist. For instance:

vertexFeature('Tralala', 'X') > 100.

returns the error message:

Evaluation failed. Incorrect syntax: Calling vertexFeature: The 
feature 'Tralala' is unknown to the feature model.

Importantly, the same error message is triggered when you call the function with a feature that has not been computed yet. For instance, in the Mastodon file you just downloaded, all feature are computed exccept one: Track N spots. If we try to select short tracks with the valid expression that follows:

vertexFeature('Track N spots') < 20

we would get the same error message (feature unknown). To fix this, you need to go to the Feature computation tool, make sure the Track N spots feature computer is selected and click Compute. After this, the expression will evaluate to a selection correctly:

Evaluation successful. Selection has now 33316 spots and 0 edges.

Why are the functions called vertexFeature and edgeFeature?

In the Mastodon application we deal with data items called spots and links. The data model of Mastodon is a mathematical graph in which a cell in one frame is a vertex. The same cell in the next frame is another vertex, and the two vertices are connected by an edge. Tracks are built by all the vertices connected by edges. Spots and links are specialized versions of the vertices and edges of the graph used in the Mastodon application. But the selection creator is built for any kind of graph that uses the Mastodon API, not only the one in the application we document here. For this reason, the syntax of the functions adopted the most general terms: vertex and edge, but for us, they points to features of spots and links.

Building selection based on tags.

We can also use tags in our expressions. The main function to do so is tagSet. It returns the tags of the specified tag-set for all the spots and links. To create a selection from them, you simply need to check what ones are equal to a certain tag with the equality == operator. For instance the expression:

tagSet('Reviewed by') == 'JY'

will retrieve all the tags in the tag-set called Reviewed by, and data items (spots and links) that are tagged with JY in this tag-set will be selected. But with our current Mastodon project it returns an error:

Evaluation failed. Incorrect syntax: The tag-set 'Reviewed by' is 
unknown to the tag-set model.

Indeed, the tag-set Reviewed-by does not exist.

The function tagSet returns spots and links altogether. If you want to retrieve only the spots or only the edges separately, there are two functions: vertexTagSet and edgeTagSet. Otherwise they work like the tagSet function and can be substituted with the same syntax.

There are also special switches to return data items that have no tag in a tag-set or that are tagged with anything in a tag-set.

  • ~tagSet('Reviewed by') will return all the data items that are tagged with any tag in the Reviewed by tag-set. It matters not what tag, but there must be one.

  • !tagSet('Reviewed by') is the converse: it will return all the data items that are not tagged in the Reviewed by tag-set.

And of course, these two switches can be used with the vertexTagSet and edgeTagSet functions.

Combining expressions.

Since we use boolean expressions we can combine them using logic operator. The first ones are the and and or operators & and |. For instance, to select all spots that have 1 link and that are in frame 25, we write the following:

vertexFeature('Spot N links') == 1 & vertexFeature('Spot frame') == 25

To select all spots that have 1 link or that are in frame 25, we use the | operator instead:

vertexFeature('Spot N links') == 1 | vertexFeature('Spot frame') == 25

There are other operators which functions have been extended to have a proper meaning with the selection creator. For instance, the above expression is identical to select all spots that have 1 link, and adding the spots that are in frame 25. So when it comes to selection, this works as in an addition, and we could write similarly:

vertexFeature('Spot N links') == 1 + vertexFeature('Spot frame') == 25

But we get an error:

Evaluation failed. Incorrect syntax: Improper use of the 'add' 
operator, not defined for Integer and VertexFeatureVariable. Use 
brackets to clarify operator priority.

Here the expression parser is confused due to the classical operation priority of the the + and - operators. We need to use brackets to specify we operate on the results of the feature filtering:

(vertexFeature('Spot N links') == 1) + (vertexFeature('Spot frame') == 25)
Evaluation successful. Selection has now 21814 spots and 0 edges.

The + operator gives the same results that the | operator, they just operate with different priorities.

The subtract operator - is used to remove data items from a selection. As for the + operator, it needs brackets to operate properly. For instance, to remove the spots that belong to the frame 25 from the selection of spots that have 1 link, we write:

(vertexFeature('Spot N links') == 1) - (vertexFeature('Spot frame') == 25)
Evaluation successful. Selection has now 19397 spots and 0 edges.

And of course, you can combine expressions using features or tags:

(vertexFeature('Spot N links') == 1) - (tagSet('Reviewed by') == 'JY')

Editing the selection.

Let’s say you already have a selection, and want to alter it with an expression. There are 3 functions that return the content of the current selection and let you modify it. As such, they are not exacly functions, but can be considered as variables in an expression.

The selection variable simply returns the list of data items that are currently selected. It can then be combined with another expression. For instance, to remove from the selection all the spots that have 2 links, use this expression:

selection - ( vertexFeature('Spot N links') == 2 )

Of course, because running it will modify the selection, such expressions might have different outcome if you run it several times in a row.

The vertexSelection and edgeSelection variables work like their selection counterpart, but are limited to return only the spots, respectively the links, of the current selection.

Morphing a selection.

All the expressions we have seen above works like a boolean operation on an array. Except that in our case we have spots and links, and that each have their own separated set of features. This separation is problematic if we want to create selection of spots based on the features of their links, or if we want to include in the selection the links of the spots we selected. To workaroudn this, the selection creator ships the morph function.

The morph function is a bit special as it is able to change the type of data items that are selected, based on their relations. It is with this function that you will select the links of a spot. For instance:

morph(vertexSelection, 'incomingEdges')

will select the incoming links of the spots currently in the selection. The vertices themselves will not be included in the final selection.

The morph function need two inputs:

  • a selection (it can result from tagSet('TS') == 'A', vertexFeature('F', 'FP') > 3, selection, …);

  • a list of tokens that specify how to morph the selection.

In the above example, the token was incomingEdges which takes all the incoming links of the spots currently selected, and nothing else (not even the spots initially selected). The supported morph tokens, or morphers are the following:

  • toVertex includes the spots currently selected in the morph result. When this morpher is not present, the selected spots are removed from the target selection.

  • incomingEdges includes the incoming links (backward in time) of the selected spots.

  • outgoingEdges includes the outgoing links (forward in time) of the selected spots.

  • toEdge includes the links of the source selection in the target selection. When this morpher is not present, the selected links are removed from the target selection.

  • sourceVertex includes the source spots of the selected links. The source spot of a link is the one backward in time.

  • targetVertex includes the target spots of the selected links. The target spot of a link is the one forward in time.

  • wholeTrack includes the whole track of the selected spots and links.

You can combine several morphers, if you put them as a list between brackets. For instance:

morph( vertexFeature('Spot N links') == 3, ('toVertex', 'outgoingEdges') )

will select the spots that have 3 links, and return them plus their outgoing links.

Summary.

Functions and variables.

Function

Usage

vertexFeature('Spot feature name', 'Projection name')

Returns the values of the specified spot feature and projection. To be used with a comparison operator on a numerical value like >, <, >=, <=, == or !=.

edgeFeature('Link feature name', 'Projection name')

The same, but for link features.

tagSet('Tag set name')

Returns the tag of all data items for the specified tag-set. To be used with the equality operator ==, comparing to a tag belonging to the specified tag set (tagSet('TS') == 'T').

vertexTagSet('Tag set name')

The same, but only returns the spots in the comparison.

edgeTagSet('Tag set name')

The same, but only returns the links in the comparison.

selection

Returns the content of the current selection.

vertexSelection

Returns only the spots in the current selection.

edgeSelection

Returns only the links in the current selection.

morph

Change the type of data items that are selected, based on their relations. To use with the morphers described below.

Morphers.

Morpher name

Effect

toVertex

Include the spots currently selected in the morph result. When this morpher is not present, the selected spots are removed from the target selection.

incomingEdges

Include the incoming links (backward in time) of the selected spots.

outgoingEdges

Include the outgoing links (forward in time) of the selected spots.

toEdge

Include the links of the source selection in the target selection. When this morpher is not present, the selected links are removed from the target selection.

sourceVertex

Include the source spots of the selected links. The source spot of a link is the one backward in time.

targetVertex

Include the target spots of the selected links. The target spot of a link is the one forward in time.

wholeTrack

Include the whole track of the selected spots and links.