README

Last Edited: July 18, 2025 (Migrate3D version 2.5)

Migrate3D

Migrate3D is a Python program that streamlines and automates biological object motion (e.g. cell migration) analysis, returning meaningful metrics that help the user evaluate biological questions. This program does not handle imaging data, only previously generated tracking data, so it is not meant to replace functions already performed very well by programs such as Imaris, Arivis Pro, CellProfiler, TrackMate etc. Migrate3D’s purpose is to take the tracks produced from any of these programs and quickly and easily process the data to generate various metrics of interest in a transparent and tunable fashion, all done through an intuitive graphical user interface (GUI). In addition to motion analysis, Migrate3D can also detect and quantify object-object interactions, such as contacts or attractions.

These results can be used in downstream analyses to compare different conditions, categories of objects, etc. The calculated metrics are all adapted from existing reports in the literature where they were found to have biological significance. Migrate3D not only calculates simple metrics such as track velocity and arrest coefficient, but more complex ones such as straightness index (i.e. confinement ratio), mean squared displacement, turning angles, etc., and includes adjustable constraints and filters to ensure that clean results are produced.

Migrate3D requires a .csv file input that contains data from object movements through two- or three-dimensional space. After execution, the program will return a set of .xlsx files, each with several worksheets, containing track-by-track summary metrics, mean squared displacement analysis, etc.

If the user imports a Categories .csv file (simply listing the category for each object ID), two additional analyses will be performed: dimensionality reduction using principal component analysis (PCA), and decision tree analysis using XGBoost. There is no guarantee that these will be performed in a statistically-sound way, that is left up to the user to ensure, but the libraries used to perform these analyses are widely used.

A limitation of the program is that it does not currently handle cell divisions (or fusions) in any intelligent way, so the user needs to separate all such tracks at the split/merge point so that each track only represents one cell. (Note: a record of which daughters belong to which parent cell can easily be kept using a simple numbering system within the track’s Name field.)

Migrate3D was developed by Menelaos Symeonides, Emily Mynar, Matthew Kinahan, and Jonah Harris at the University of Vermont, funded by NIH R21-AI152816 and NIH R56-AI172486 (PI: Markus Thali). We welcome feedback and intend to continue developing and supporting the program as resources allow.

Input Files

A Segments input file is required to run Migrate3D. Optionally, a Categories input file can be provided to perform additional analyses. In both cases, the program will "guess" which columns contain which data, but if this fails, you can select them through a drop-down box in the GUI. These input files can be stored in any folder.

Segments

The Segments input file should be a .csv with five columns (or four for 2D data): object ID, time, X, Y, and Z coordinates. Please ensure that column headers are in the first row of the .csv file input. Note that the Time column is expected to contain a "real" time value (e.g. number of seconds), not just the timepoint index.

If an object has non-consecutive timepoints assigned to it (i.e. if an object's track has gaps), the object will be dropped and not analyzed at all, unless the interpolation option is used. The IDs of dropped objects will be recorded in the results output (along with any objects dropped due to the "Minimum Max. Euclidean" filter) in the sheet "Removed Objects". If interpolation is enabled, any missing timepoints will be linearly interpolated and the object will be used as normal.

Installing and Running Migrate3D

These installation instructions involve the use of the command line. If you are not familiar with using the command line, just copy each line and paste into your prompt/terminal and press Enter. Once the process is complete, you will be able to paste in the next line and press Enter, and so on. If "sudo" is used, you will need to enter your account password to proceed.

On Windows (tested in Windows 10 and 11)

First, download and install the latest version of Miniconda3 for Windows using all the default options during installation: https://docs.conda.io/projects/miniconda/en/latest/index.html
From the Start menu, open the Anaconda Prompt that was just installed. Create a folder for Migrate3D and navigate to it:

mkdir Migrate3D
cd Migrate3D

Download Migrate3D from GitHub, extract the ZIP file, and navigate into the subfolder that was just created:

curl -LJO https://github.com/msymeonides/Migrate3D/archive/main/Migrate3D-main.zip
tar -xvzf Migrate3D-main.zip
cd Migrate3D-main

Set up a virtual environment (venv) and activate it:

conda update conda
conda create --name Migrate3D
conda activate Migrate3D

Note: if you would like to exit the venv, i.e. return to the base Anaconda prompt, simply enter:

conda deactivate

Install the required dependencies:

conda install pip
pip install -r requirements.txt

Note that these packages are only installed within the venv you just created and will not affect your base python installation.

Finally, to run Migrate3D:

python %USERPROFILE%\Migrate3D\Migrate3D-main\main.py

Remember to open the Anaconda Prompt and activate the Migrate3D venv next time you want to run Migrate3D:

conda activate Migrate3D
python %USERPROFILE%\Migrate3D\Migrate3D-main\main.py

In the prompt, you will see a notification that the GUI is now available ("Dash is running on http://127.0.0.1:5555/"). You can now go to this address in your web browser to access the Migrate3D GUI.

Note that the output result spreadsheets will be saved under C:\Users\your_username\Migrate3D\Migrate3D-main.

On macOS (tested in Catalina 10.15.7):

First, download and install the latest version of Miniconda3 for macOS (the pkg version will be easiest to install): https://docs.conda.io/projects/miniconda/en/latest/index.html
Open a Terminal. Create a folder for Migrate3D and navigate to it:

mkdir Migrate3D
cd Migrate3D

Download Migrate3D from GitHub, extract the ZIP file, and navigate into the subfolder that was just created:

curl -LJO https://github.com/msymeonides/Migrate3D/archive/main/Migrate3D-main.zip
tar -xvzf Migrate3D-main.zip
cd Migrate3D-main

Set up a virtual environment (venv) and activate it:

conda create --name Migrate3D
conda activate Migrate3D

Note: if you would like to exit the venv, i.e. return to the base Anaconda prompt, simply enter:

conda deactivate

Install the required dependencies:

sudo xcode-select --install
conda install pip
pip3 install -r requirements.txt

Note that these packages are only installed within the venv you just created and will not affect your base python installation.

Finally, to run Migrate3D:

python3 ~/Migrate3D/Migrate3D-main/main.py

Remember to first activate the Migrate3D venv next time you want to run Migrate3D before executing the main script:

conda activate Migrate3D
python3 ~/Migrate3D/Migrate3D-main/main.py

In the prompt, you will see a notification that the GUI is now available ("Dash is running on http://127.0.0.1:5555/"). You can now go to this address in your web browser to access the Migrate3D GUI.

Note that the output result spreadsheets will be saved under /Users/your_username/Migrate3D/Migrate3D-main/.

On Linux (tested in Linux Mint 22.1):

It is easiest to do everything in the terminal, so begin by opening a Terminal window.

Python 3 is already installed in Linux Mint. Begin by checking the installed version of python:

python3 --version

On a fresh installation of Linux Mint 22.1, that should return "Python 3.12.3". Python versions 3.13.x and 3.11.x will also work, but earlier versions may not. If you have an earlier version of python, you may need to update it before proceeding.

If you have not previously configured a python virtual environment (venv) or installed python packages using pip, you will first need to get set up to do that (if you are already set up for that, skip to step 4).

First, update your system:

sudo apt update
sudo apt upgrade

Then install some necessary packages (this is all one line, paste the whole thing in one go):

sudo apt install build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev \
libsqlite3-dev curl git libncursesw5-dev xz-utils tk-dev libxml2-dev \
libxmlsec1-dev libffi-dev liblzma-dev python3.12-venv

Now we need to configure PyEnv to be able to set up a venv:

curl https://pyenv.run | bash
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.profile
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.profile
echo 'eval "$(pyenv init -)"' >> ~/.profile

Now log out of your Linux account and log back in, then open

Migrate3D

Install / Use

README

README

Migrate3D

Input Files

Segments

Categories

Installing and Running Migrate3D

On Windows (tested in Windows 10 and 11)

On macOS (tested in Catalina 10.15.7):

On Linux (tested in Linux Mint 22.1):