Browsing images

The lmcontrol provides functionality for embedding images into 3D space and viewing these images interactively.

Unless otherwise noted, this tutorial assumes your images are stored in a directory named ambr_images.

Cropping images

Before we can embed images though, you will need to locate the individual cells in each image and crop the image to focus on the cell. This can be achieved using the crop command.

lmcontrol crop ambr_images segmented_images

This command processes all TIFF files in the ambr_images directory. It does this by reading all files with the .tif extension in ambr_images. Cropped images are saved in the segmented_images directory with the same name they had in the original directory. For example, in this tutorial, the cropped image ambr_images/Rhodo1.tif will be saved to segmented_images/Rhodo1.tif.

For various reason, not all images can be segmented. Images that cannot be segmented can be saved in the output directory in the subdirectory unseg. To do this, you must provide the optional flag -u/--save-unseg.

By default, all images are cropped (if possible) and saved. This can be disabled with the flag -n/--no-tifs. This command will always save a single file containing all cropped images in a NPZ file named all_processed.npz in the specified output directory i.e. segmented_images/all_processed.npz in this example. In addition to the cropped images, all_processed.npz will contain cropped segmentation masks for each image.

Finally, you can pass through metadata to the the all_processed.npz file using the -m/--metadata flag. Eventually, you may want to merge multiple all_processed.npz files. Providing metadata for each file will enable you to distinguish individual images down the line. For example, you may want to keep track of experimental conditions for each sample, such as time point or bioreactor feed. You can pass these in as comma-separated key-value list e.g. key1=value1,key2=value2.

More info about lmcontrol crop is available in its usage statement.

Visualizing images

There are two important commands for visualizing images. The first command we will talk about, prep-viz will be used for building a visualization package, and the second command, emb-viz, will be the actual command for running the visualization application.

The first command is prep-viz. This command takes in multiple all_processed.npz files and merges them into a package.

lmcontrol prep-viz viz_pkg.npz segmented_images/all_processed.npz other_segmented_images/all_processed.npz

prep-viz works by computing a 3D embedding with UMAP. You can compute a 2D embedding by passing in the -2/--two-dim flag. Although UMAP is relatively fast and very good at keeping memory requirements low, this step can take awhile if you have many images.

This will output a visualization package to viz_pkg.npz that includes the embeddings to visualize, with any metadata found in the all_processed.npz files.

Although we do not use it in this example, we highly recommend you include the -c/--center flag to normalize each image. Without this, images can be embedding according to how light or dark the image is.

Launching the visualization application

Once we have our visualization package, we can view our data!

lmcontrol emb-viz viz_pkg.npz

This relies on the Dash for creating an interactive visualizer. Dash will provide a URL for accessing the interactive visualizer with your web browser. The output of this command should look something like this:

Dash is running on http://127.0.0.1:8050/

 * Serving Flask app 'LMControl Viz'
 * Debug mode: on

You can now point your browser at the provided URL and begin browsing your data!

You might find that it takes a while to load the visualization application or that there are simply too many data points. You can slim down the number of data points using the -s/--subsample. This will take a random subset of the size provided. Additionally, you can stratify the random subsample according to any given metadata you may have using the -l/--label flag.

Visualizing with Jupyter

This functionality can be carried out in a Jupyter notebook.

from lmcontrol.viz.interactive_viz import build_app
app = build_app("viz_pkg.npz")
app.run()