MoMA usage - nimwegenLab/moma GitHub Wiki

WARNING: This document is outdated. It will be updated soon.

  • Check to what extent this document is still relevant. Compare it with the MoMA-introductiory-tutorial.md.
  • TODO: Remove module use-commands from this document. Refer instead to the setup instructions.

Table of contents

Setting up MoMA in `.bashrc` on Scicore

To use MoMA on Scicore you need to add the corresponding Modules to .bashrc in your home-folder. E.g. by running:

nano ~/.bashrc

There are three MoMA-instances on Scicore:

  1. stable: This is the most stable, current version. I will try my best not to break this version. To use in your `.bashrc` add:

    module use /scicore/home/nimwegen/GROUP/Moma/MM_Analysis/stable_current

  2. testing: This version is intended for testing by users. I will push versions with new features here for testing by users. Add:

     module use /scicore/home/nimwegen/GROUP/Moma/MM_Analysis/testing_current

  3. unstable: This is intended primarily for the developer to test things on scicore:

    module use /scicore/home/nimwegen/GROUP/Moma/MM_Analysis/unstable_current

Remarks:

  • The paths above are symbolic links to folder with the particular, current version. I keep backups of the version-folders for reproducibility.
  • I will update the versions that the symbolic links point to as they become available (e.g. a new stable version). If you need/want to continue using a particular version, you will need to point your .bashrc to that particular version directly. However, I would prefer that we do not do this, so that we continuously test new versions and avoid version fragmentation. If you still want to do it, let me know and we can set it up.
  • The versions of MoMA and U-Net deep-learning model and the used configuration file are output during export along with the analysis results. We therefore know, which version was used.

:warning: Adding a line to load the Moma module on bash startup might create conflict/slow down/reduce startup-times for bash-session in all other uses (VNC, Rstudio, etc). You should therefore consider running the above commands manually, when you need to use MoMA or (alternatively) only add them to your ~/.bashrc when you are regularly using MoMA during analysis-sessions (you can comment them out in meantime).

:warning: These Moma modules are incompatible with the "legacy" preprocessing module.

Running MoMA on GPU nodes

MoMA requires a GPU for running the deep-learning model fast. For this you need to run MoMA on GPU-nodes of Scicore.

Connecting

To connect to a GPU-node for starting a MoMA session by running these two commands in the same terminal:

moma_gpu_session_start
moma_gpu_session_connect

A session started with `moma_gpu_session_start` will time out after 6 hours. To create a session with a 24 hours timeout run:

moma_gpu_session_start -longsession

Please note:

  • A long session makes sense, when batch-tracking/-exporting many GLs (e.g. using the command moma_batch_run -track or `moma_batch_run -export`). It allows you to process 288 GLs assuming a (generous) processing time of 5 minutes/GL.
  • Please use the default 6 hours for shorter-lived interactive session, because long-running jobs on the cluster take longer to start and block the GPU node for longer times (which Scicore admins will not like, if the process is mostly idling).

Running MoMA

To run MoMA:

moma -i /scicore/home/nimwegen/micuby52/TemporaryFiles/20200616_get_gpu_to_work/test_data/20190515_hi1_med1_med2_rpmB_glu_gly_7_MMStack_Pos25_preproc_GL01/20190515_hi1_med1_med2_rpmB_glu_gly_7_MMStack_Pos25_preproc_GL01.tif

Disconnecting

To disconnect simple type `exit` twice, i.e.:

exit # <- exits SSH access to the GPU node
exit # <- exits the interactive SLURM session, which is was started by moma_gpu_session_start; if you do not do this, the session on the GPU node will continue existing and block resources there

The first command disconnects from the session on the GPU-node and the second one closes it.

MoMA config file

The default config file for MoMA is shown below. It lies in the directory `.moma` in home folder of the user.

MoMA config template

import_path=/scicore/home/nimwegen/GROUP/MM_Data/Theo/20210428/preprocess/20210428_Theo_process_positions__output__20210503-161334/Pos21/Pos21_GL17/20210428_glc_spcm_1_MMStack_Pos21_GL17.tiff   

GUI_NUMBER_OF_SHOWN_TIMESTEPS=23
GUI_SHOW_GROUND_TRUTH_EXPORT_FUNCTIONALITY=0

SEGMENTATION_MODEL_PATH=/scicore/home/nimwegen/GROUP/Moma/MM_Artifacts/unet_models/model_20210715_5b27d7aa/current_tensorflow_model.zip
CELL_DETECTION_ROI_OFFSET_TOP=120
THRESHOLD_FOR_COMPONENT_GENERATION=0.5
THRESHOLD_FOR_COMPONENT_SPLITTING=1.0
THRESHOLD_FOR_COMPONENT_MERGING=0.5
MAXIMUM_DOWNWARD_MOVEMENT=50

GUROBI_TIME_LIMIT=15.0
GUROBI_MAX_OPTIMALITY_GAP=0.99
ASSIGNMENT_COST_CUTOFF=2.0
LYSIS_ASSIGNMENT_COST=10.0
MAXIMUM_GROWTH_RATE=1.5
GL_OFFSET_TOP=-1000

CELL_LABELS=dead;dying;fading;shrinking;dividing
EXPORT_ASSIGNMENT_COSTS=0
EXPORT_SPINE_MEASUREMENT=0
EXPORT_ORIENTED_BOUNDING_BOX_MEASUREMENT=1
SPINE_MEASUREMENT_MEDIALLINE_OFFSET_FROM_CONTOUR_ENDS=3.5
SPINE_MEASUREMENT_ENDPOINT_ORIENTATION_AVERAGING_WINDOWSIZE=5
SPINE_MEASUREMENT_POSITION_AVERAGING_MAXIMUM_WINDOWSIZE=21
SPINE_MEASUREMENT_POSITION_AVERAGING_MINIMUM_WINDOWSIZE=5
INTENSITY_FIT_RANGE_IN_PIXELS=100
INTENSITY_FIT_ITERATIONS=500
INTENSITY_FIT_PRECISION=0.001
INTENSITY_FIT_INITIAL_WIDTH=5.5


OPTIMISATION_INTERVAL_LENGTH=-1
GUI_CONSOLE_WIDTH=600
GUI_POS_Y=24
GUI_POS_X=0
GUI_HEIGHT=1056
GL_WIDTH_IN_PIXELS=20
GUI_WIDTH=1920
DEFAULT_PATH=/home/micha
GUI_OPTIMIZE_ON_ILP_CHANGE=0

I categorize the settings conceptually in setting that affect:

  • graphical user interface (GUI)
  • generation of components/segmentation
  • generation and optimization of the tracking problem
  • exporting the results

Explanation:

  • graphical user interface:
    • GUI_NUMBER_OF_SHOWN_TIMESTEPS \[\]
    • GUI_OPTIMIZE_ON_ILP_CHANGE: Controls if optimization will be performed on each user-modification during curation.
  • GUROBI_TIME_LIMIT: Time limit for the tracking optimization.
  • EXPORT_ASSIGNMENT_COSTS: Controls if assignment costs should be exported. This is a developer option and should not be modified.
  • THRESHOLD_FOR_COMPONENT_SPLITTING: Sets an upper threshold for component generation. Pixel probabilities above this threshold will be set to 1. Reducing this below 1 can avoid the generation of spurious child components and thus reduce the depth of the component tree, which is particularly useful for dataset with filamenting cells. However, setting this value too low can create issues, when correct child components are not generated. A good initial value is >0.99 when using this option.
  • SPINE_MEASUREMENT_POSITION_AVERAGING_MINIMUM_WINDOWSIZE: Minimum windows size for the window averaging the medial line positions in the calculation of the spine-length measurement.
  • SPINE_MEASUREMENT_POSITION_AVERAGING_MAXIMUM_WINDOWSIZE: Maximum windows size for the window averaging the medial line positions in the calculation of the spine-length measurement.
  • SPINE_MEASUREMENT_MEDIALLINE_OFFSET_FROM_CONTOUR_ENDS: Minimal distance between the end of the medial line and the cell contour at either end of the cell.
  • THRESHOLD_FOR_COMPONENT_GENERATION [0.5; DO NOT CHANGE]: The threshold that is used to generate components.  This value should not be changed from the default of .5, because it affects the measured cell-area/-size.
  • MAXIMUM_DOWNWARD_MOVEMENT: (added in version v0.9.3) This parameter sets by how many pixel a cell is allowed to move downwards. Assignments with a position difference larger than this (between source and target) will not be considered. The unit pixels. If the parameter is not set in the config-file, it will default to 50.

Selecting the U-Net deep-learning model

The setting SEGMENTATION_MODEL_PATH in mm.properties sets the path to the UNet model file:

SEGMENTATION_MODEL_PATH=/scicore/home/nimwegen/GROUP/Moma/MM_Artifacts/unet_models/model_20210715_5b27d7aa/current_tensorflow_model.zip

 Available models are stored under:

/scicore/home/nimwegen/GROUP/Moma/MM_Artifacts/unet_models

Currently we are using a single model for all our analysis. The latest model (as of 2022-12-01) is `model_20210715_5b27d7aa`.

Gurobi

MoMA uses the Gurobi Optimizer for optimizing linear programming problem during tracking. It therefore requires a valid Gurobi license. This version is continuously updated by Scicore admins.

If needed you can change the path to the used Gurobi license by changing in, e.g.

/scicore/home/nimwegen/GROUP/Moma/MM_Analysis/stable_current/myGurobi

the following line:

setenv  GRB_LICENSE_FILE        "/export/soft/source/g/Gurobi/gurobi.lic"

Doing this you can e.g. use a personal, academic license that you can obtain for free at gurobi.com. Note, however, that the license is host-specific and will stop working, when you try to run Gurobi on a host that is different from the one with which you acquired the license. Therefore you cannot use it on GPU nodes, because the GPU-nodes change between sessions. Also GPU nodes do not have access to the internet, which is required for obtaining a personal license.