Merge pull request #80 from mastodon-sc/track-matching-docs

Add track matching docs
mastodon-sc · Dec 19, 2024 · da8c190 · da8c190
2 parents 2eab3dc 34dc802
commit da8c190
Show file tree

Hide file tree

Showing 3 changed files with 90 additions and 1 deletion.
diff --git a/README.md b/README.md
@@ -267,6  267,82 @@ Example: ![sort_lineage_tree_cell_life_cycle_duration.gif](doc/treesmanagement/s
 
 ## Spatial track matching
 
 * This command allows comparing the lineages of two similarly developing embryos stored in two Mastodon projects.
 * By analyzing the spindle directions, the plugin tries to find the corresponding cells in both embryos.
 
 ### Pre-conditions
 
 The following conditions need to be met for the algorithm to work:
 
 * Both projects should show stereotypically developing embryos.
 * The first frame should show both the embryos at a similar developmental stage. The frame number that is considered
   the first frame can be set by the user.
 * Root nodes must be labeled, and the labels should match between the two projects.
 * There needs to be at least three tracks with cell divisions, that can be paired based on their names.
 * Note: The plugin ignores tracks that have no cell divisions.
 
 ### Operations based on the correspondence information
 
 The plugin allows performing various operations based on the correspondence information, such as:
 
 * Couple projects:
     * Spot highlighting and focus are synchronized between the two projects.
     * Navigation to a clicked spot is synchronized for the selected `sync group`.
     * Synchronization works best between the TrackScheme Branch and TrackScheme Hierarchy windows.
     * Synchronization is only implemented for spots, not for links.
 * Sort TrackScheme based on the correspondences
     * Orders the descendants in the TrackScheme of the chosen project such that their order matches the order in the
       other project.
 * Copy cell names
     * The correspondences are on the level of cells. This is why all the spots that belong to the same cell will get
       the same label. Labels of individual spots can not be copied.
     * The label of the first spot of a cell is assumed to be the cell name.
     * This assumption is different from the TrackScheme Branch. Which actually shows the label of the last spot as
       the label of the branch.
 * Copy tags between the corresponding cells in both embryos:
     * Use the found correspondences to copy a tag set from one project to the other.
     * The correspondences are on the level of cells / branches thus tags are only copied if the entire cell / branch
       is tagged. Tags on individual spots are not copied.
 * Plot cell division angles
     * Show a plot of angles between paired cell division directions over time
 * Add angles to table
     * Stores the angles between paired cell division directions as a feature in both projects.
 * Color paired lineages
     * Creates a new tag set `lineages` in both projects. Lineages with the same root node label get a tag with the
       same color.
 
 ### Parameters and Track Matching Methods
 
 * project A: the first project to compare
 * project B: the second project to compare
 * First frame: The first time point of a project to be used for the registration.
     * This is useful if
         * both projects start at different stages of development
             * e.g. one project starts at the 4-cell stage and the other at the 8-cell stage
             * in this case, the user can set the first frame of both projects to the same stage (i.e. the 8-cell stage)
         * there are less than three cells in the first time point
             * in this case, the user can set the first frame to a later time point where there are at least three cells
               in both projects.
 * Spatial track matching method:
     * Fixed spatial registration based on root cells
         * Pairs of root cells with the same name are used to estimate the transformation between the two embryos.
     * Dynamic spatial registration based on root cells and their descendants
         * Pairs of root cells with the same name in both projects and respective descendants are used to estimate the
           transformation between
           the two embryos. The transformation is stabilized by averaging over the descendants of the root cells.
     * Dynamic spatial registration based on "landmarks" tag set
         * The user can define "landmark" spots in both projects. These spots need to be tagged with the same tag of a
           tag set called "landmarks" in both projects. The transformation is estimated based on the positions of the
           landmarks.
 
 ### Example
 
 * project A (left
   side): [Phallusia mammillata](https://github.com/mastodon-sc/mastodon-example-data/blob/master/astec/Pm01.mastodon)
 * project B (right
   side): [Phallusia mammillata](https://github.com/mastodon-sc/mastodon-example-data/blob/master/astec/Pm02.mastodon)
 * Visualisation: ![spatial_track_matching.gif](doc/spatialtrackmatching/spatial_track_matching.gif)
 
 ## Export measurements
 
 ### Export spot counts per lineage

diff --git a/doc/spatialtrackmatching/spatial_track_matching.gif b/doc/spatialtrackmatching/spatial_track_matching.gif
diff --git a/src/main/java/org/mastodon/mamut/tomancak/trackmatching/SpatialTrackMatchingFrame.java b/src/main/java/org/mastodon/mamut/tomancak/trackmatching/SpatialTrackMatchingFrame.java
@@ -28,6  28,7 @@
  */
 package org.mastodon.mamut.tomancak.trackmatching;
 
 import java.awt.Font;
 import java.text.NumberFormat;
 import java.util.ArrayList;
 import java.util.List;
@@ -39,6  40,7 @@
 import javax.swing.JFormattedTextField;
 import javax.swing.JFrame;
 import javax.swing.JLabel;
 import javax.swing.JSeparator;
 import javax.swing.JTextArea;
 import javax.swing.JTextPane;
 import javax.swing.JToggleButton;
@@ -157,6  159,11 @@ public SpatialTrackMatchingFrame( Listener listener )
 		setLayout( new MigLayout( "insets dialog, fill" ) );
 
 		add( introductionTextPane(), "span, grow, wrap, width 0:0:" );
 		add( new JSeparator(), "span, grow, wrap" );
 
 		JLabel parametersLabel = new JLabel( "Parameters:" );
 		parametersLabel.setFont( parametersLabel.getFont().deriveFont( Font.BOLD ) );
 		add( parametersLabel, "span, wrap" );
 		add( new JLabel( "Select Mastodon projects to match:" ), "span, wrap" );
 		add( new JLabel( "project A:" ) );
 		comboBoxA.addActionListener( ignore -> updateEnableComponents() );
@@ -175,11  182,16 @@ public SpatialTrackMatchingFrame( Listener listener )
 		firstTimepointB.setToolTipText( FIRST_TIMEPOINT_TOOLTIP );
 		enableDisable.add( firstTimepointB );
 
-		add( new JLabel( "Spatial registration method:" ) );
 		add( new JLabel( "Spatial track matching method:" ) );
 		spatialRegistrationComboBox.setSelectedItem( SpatialRegistrationMethod.DYNAMIC_ROOTS );
 		add( spatialRegistrationComboBox, "wrap" );
 		enableDisable.add( spatialRegistrationComboBox );
 
 		add( new JSeparator(), "span, grow, wrap" );
 		JLabel operationsLabel = new JLabel( "Operations:" );
 		operationsLabel.setFont( operationsLabel.getFont().deriveFont( Font.BOLD ) );
 		add( operationsLabel, "span, wrap" );
 
 		add( new JLabel( "Tag unmatched & flipped cells:" ), "gaptop unrelated" );
 		add( newOperationButton( "in both projects", TAG_CELLS_TOOLTIP, listener::onTagBothClicked ), "split 3" );
 		add( newOperationButton( "project A", TAG_CELLS_TOOLTIP, listener::onTagProjectAClicked ) );
@@ -203,6  215,7 @@ public SpatialTrackMatchingFrame( Listener listener )
 		add( syncGroupButtons.get( 0 ), "split 3" );
 		add( syncGroupButtons.get( 1 ) );
 		add( syncGroupButtons.get( 2 ), "wrap" );
 		add( new JSeparator(), "span, grow, wrap" );
 		logArea = new JTextArea( 3, 50 );
 		logArea.setEditable( false );
 		add( logArea, "gaptop unrelated, span, grow" );