Welcome to TubULAR’s documentation!#
What is it?#
TubULAR is a set of tools for working with 3D data of surfaces – potentially complex and dynamic – that can be described as tubes. Developing guts, neural tubes, and pumping hearts can all be treated as deforming tube-like surfaces. Mapping these surfaces to a fixed frame of reference allows us to follow the cells (or other objects) as they move in 3D with ease. With TubULAR, we can capture the tissue motion and quantify how it changes over time.
You can check out the preprint here: https://www.biorxiv.org/content/10.1101/2022.04.19.488840
Data for tutorials are available here: https://doi.org/10.6084/m9.figshare.c.6178351
The GitHub repository is here: https://github.com/npmitchell/tubular
Usage#
TubULAR is written in MATLAB. There are example scripts in the Tubular repository, in tubular/example/ (see the GitHub page here: https://github.com/npmitchell/tubular). The basic workflow of a typical pipeline is shown below:
Let’s get going#
Download TubULAR in Mac or Linux, navigate in Terminal to a path where you’d like to place the code, then clone the repository:
cd ~
git clone --recursive ssh://www.github.com/npmitchell/tubular
There is now a directory called tubular. Open up MATLAB and take a look at some example scripts to get familiar.
Updates to the code are installed running the following command from the tubular directory:
git pull
So now your tubular is definitely up-to-date. There are two linked repositories that are not pulled with this line: upon cloning TubULAR on your local machine, DECLab and TexturePatch, which are linked repositories within TubULAR, were pulled only because we used the --recursive option before. These two repositories are available here: http://github.com/DillonCislo/DEC and https://github.com/npmitchell/TexturePatch. Note that the example scripts expect these repositories to be populated in the folders called DECLab and TexturePatch, so if you didn’t clone with --recursive, you can clone them from Github and make sure their contents sit in those directories. To update them, run:
cd TexturePatch
git pull
cd ../DECLab
git pull
We have tried to keep dependencies to a minimum. One package that TubULAR will try to use if your surfaces are so “prickly” that they would cause potential issues is gptoolbox. This is a MATLAB package, but it has some mex files, which are MATLAB’s way of interfacing with custom C++ code. If that sounds complicated, don’t worry – all you need to do is additionally download a copy of gptoolbox and compile it by typing a few lines in a Terminal window. If you like, you can also skip this step, go straight to the examples and deal with any potential issues by tweaking TubULAR’s surface extraction parameters.
First download gptoolbox inside tubular/external/.
cd tubular/external/
Now that you’ve downloaded gptoolbox, check that you have CMake installed, since this does not come preinstalled on Mac OSX or Windows machines. To install CMake, follow the instructions here https://cmake.org/install/. Installation can take ~20 minutes. Then go into the mex folder and compile gptoolbox:
cd gptoolbox
cd mex
mkdir build
cd build
cmake ..
make
If this runs into trouble, it is possible that you may have to tweak the CMake file depending on your computer specs. StackExchange is a place to look for any errors you might get.
Ok, now we still have to compile the gptoolbox functions by running compile_mex.m in MATLAB, from the directory gptoolbox/external/toolbox_fast_marching.
In other words, open MATLAB, then open the script in tubular/external/gptoolbox/external/toolbox_fast_marching/compile_mex.m. Change the current working directory to the parent directory of this file (which is `tubular/external/gptoolbox/external/toolbox_fast_marching/''), then run the file. In our hands, this works on Linux and Mac operating systems, and we expect it should work on Windows as well. If these functions compile, then we're good to go with gptoolbox. If this compilation fails, you might get an error when running a script like ``Undefined function 'perform_front_propagation_3d' for input arguments of type 'double'.
TubULAR also uses CGAL, described in detail at https://www.cgal.org/. Installation instructions are at https://www.cgal.org/download.html.
Making pullback projections will require the Optimization Toolbox, and we also use Curve Fitting Toolbox (for smooth), Statistics and Machine Learning Toolbox (or you can just rip the function prctile for this one), and the Image Processing Toolbox. You can install these in MATLAB by clicking in the Home tab of the toolbar: Add-Ons > Get Add-Ons and searching for the Toolbox name. If you don’t have access to these toolboxes, you can get functions that do the trick ‘a la carte’.
TubULAR uses “under-the-hood” PIVLab commands for refinement of the stabilized coordinates after the smoothed (s,phi) coordinates are defined. To install PIVLab, click the APPS tab in MATLAB (next to PLOTS and EDITOR tabs), click ‘Get More Apps’ and search for PIVLab.
Now that you’ve downloaded TubULAR and gathered the dependencies, let’s look over the components of TubULAR and walk through an example.
Prerequisites#
This toolkit is written for MATLAB 2018 and above. The toolkit uses some external code included in the tubular/external/ directory, but also you will need to compile gptoolbox for some functionality (see above).
Components#
A typical Tubular pipeline uses several self-contained packages that we have included within TubULAR. We wrote two of these packages: DEC for flow field analysis on curved surfaces, and TexturePatch for surface visualization.
DEC computes fully covariant Discrete Exterior Calculus measures of flow.
TexturePatch visualizes volumetric data on meshes in 3D and handles texture mapping data from one space/surface to another, such as the example gut images shown below:
Let’s walk through an example or two#
Here are some full examples, starting with one of the midgut, which is in tubular/example/example_timeseries_gut11Timespoints.m. This script uses data stored on FigShare. Here is a page with the details:
Among the neat things output from this pipeline is a series of pullback images in which the cells of the tissue barely move. Check out this overlay of three timepoints 30 minutes apart in cyan, magenta, and yellow pulled back into the material frame of reference below. Notice how the cells lay on top of each other (white colors). Even though the shape is changing dramatically in 3D, the map to the plane stabilizes tissue motion. These images would be in mesh_output/gridCoords_nU0100_nV0100/PullbackImages_010step_pivPathlines_000150t0/.
Note that individual cells may still rearrange, but the mesoscale tissue motion is cancelled out, like in panels D-E of this image:
Here is an example with a synthetic dataset. Note that the file paths have to be changed at the top of the script to the place where you download the data.
Note that even a synthetic dataset with a topological change in winding number can be successfully handled, as shown in this image:
Here is a pipeline where we’re just interested in surface visualization:
Here is a very detailed example using the zebrafish heart data that highlights an alternative method for surface extraction.
FAQ / Common Debugging Issues#
Optional packages for extra functionality#
ImSAnE
ImSAnE is a tissue cartography package developed by Idse Heemskirk and Sebastian Streichan [1]. Users already familiar with the ImSAnE workflow can access all the power of TubULAR within ImSAnE. If you’ve never heard of this before, you can take a look at this paper for more details, or you can just skip this section without worry. To use ImSAnE with tubular or to use tubular inside ImSAnE, get the latest version of ImSAnE:
cd ~
git clone ssh://www.github.com/npmitchell/imsane
Then, before running an example script that uses ImSAnE, you’ll need to navigate to the ImSAnE repository in MATLAB and run setup.m from there.
Morphsnakes
Maybe you want some extra knobs to fine-tune your surfaces, beyond the built-in MATLAB activecontour implemented in the TubULAR pipeline. Morphsnakes was developed by Pablo Marquez-Neila, Luis Baumela and Luis Alvarez. The original version was posted to github here: <https://github.com/pmneila/morphsnakes>, but to use this with TubULAR and ImSAnE, we use a lightly modified version:
sudo pip3 install PyMCubes
git clone https://github.com/npmitchell/morphsnakes.git
cd morphsnakes
python3 setup.py develop
git clone https://github.com/npmitchell/morphsnakes_wrapper.git
sudo pip3 install h5py
sudo pip3 install seaborn
sudo pip3 install matplotlib
cd morphsnakes_wrapper
Edit run_morphsnakes.sh to your liking (setting paths to your data, parameters, etc). Then run it on your data as below. Documentation for parameters is in the bash script (run_morphsnakes.sh).:
bash run_morphsnakes.sh
Example usage with optional dependencies#
Using TubULAR within ImSAnE
To run ImSaNE using TubULAR’s functionality for surface detection and fitting, follow this template.
Conversely, to follow a TubULAR pipeline using an ImSaNE Experiment class instance, follow this template.
Overview of contents#
Principal contents: