Running CellTracksColab locally

Google Colab, while user-friendly, has some limitations, especially concerning data upload, data privacy, and reliance on Google's cloud services. CellTracksColab can therefore also run entirely on your own computer. The notebooks are the same ones used in Colab: they detect automatically whether they run in Colab or locally.

Options for Running CellTracksColab Locally

1. Desktop app (recommended)

• No setup: A one-click installer for Windows, macOS and Linux that bundles Python, JupyterLab and all dependencies (built with LabConstrictor).
• Full privacy and offline analysis: Data, code and analysis stay on your computer.
• Built-in updates: The Welcome notebook lists all notebooks and checks for updates.

2. Your own conda environment

• Full control: For users who prefer to manage Python themselves or want to develop new analyses.
• Full privacy and offline analysis: As with the desktop app, everything stays on your computer.

3. Google Colab with Local Runtime:

• Hybrid Solution: Uses Google Colab's interface while running computations on your local resources (using the conda environment from option 2). This mitigates data privacy concerns and reduces dependency on Google's cloud services.

📹 Video Tutorials

Tutorial: Using CellTracksColab locally with Jupyter

Tutorial: Using CellTracksColab Locally with Google Colab

ℹ️ These tutorials were recorded with an earlier version of CellTracksColab. The workflow is the same, but use the commands on this page.

Option 1: Desktop app

1. Install CellTracksColab by following the installation guide for your operating system. All installers are also on the Releases page.
2. Launch CellTracksColab from the Start Menu (Windows), the Applications folder (macOS) or your applications menu (Linux). A terminal window opens: keep it open while you work. JupyterLab then opens in your browser with the Welcome notebook.
3. Open a notebook by clicking Open the Notebook next to the analysis you want in the Welcome dashboard.
4. Run the notebook cell by cell. Code cells may be hidden; see how to run notebooks in the desktop app.

More information: Using the notebooks after installation · Desktop app troubleshooting.

Option 2: Your own conda environment

1. Download CellTracksColab from GitHub

• Visit the CellTracksColab GitHub repository.
• Click on the green "Code" button and select "Download ZIP", then extract the ZIP file to a location on your computer.
• Or, if you use git:

  git clone https://github.com/CellMigrationLab/CellTracksColab.git

2. Install conda

• We recommend Miniforge, a minimal conda installer that uses the conda-forge channel. Anaconda or Miniconda also work.
• Follow the installation instructions for your operating system.

3. Create the CellTracksColab environment

1. Open a terminal

   • On Windows, open the Miniforge Prompt (or Anaconda Prompt) from the Start Menu. On macOS/Linux, open a terminal.

2. Navigate to the CellTracksColab folder

   • Use the cd command to go to the folder you downloaded (the one that contains environment.yaml). For example:

     cd C:\Path\To\CellTracksColab

3. Create and activate the environment

   • This creates an environment called celltrackscolab with Python 3.12 and JupyterLab:

     conda env create -f environment.yaml
     conda activate celltrackscolab

4. Install the CellTracksColab dependencies and code

   • Install the Python packages used by the notebooks and the celltracks package itself (stored in src/celltracks/):

     pip install -r requirements.txt
     pip install -e .

   • If you have an NVIDIA GPU, you can use pip install -r requirements_gpu.txt instead of requirements.txt.

You only need to do this once. To update CellTracksColab later, download the latest version (or run git pull), activate the environment and run the two pip install commands again.

Running CellTracksColab Notebooks in Jupyter Lab

1. Navigate to the CellTracksColab folder and activate the environment

   cd C:/Users/YourUsername/Path/To/CellTracksColab
   conda activate celltrackscolab

2. Start Jupyter Lab

   jupyter lab

   • Jupyter Lab will open in your default web browser. You should also see a landing page similar to the image below:

   

   • On this landing page, you will find the URL (Local Runtime Address) with a port (e.g., 8888) and a token that can be used to interact with Jupyter Lab in your preferred web browser.
   

3. Open the Notebook You Want to Run

   • In the web browser, navigate to the notebook you want to run and open it by double-clicking it. The interface should look similar to the image below:
   
   • And the opened notebook should look like this:
   
   • The notebooks are in the notebooks folder, one folder per notebook (for example notebooks/CellTracksColab_TrackMate/CellTracksColab_TrackMate.ipynb).

4. IMPORTANT notes when using the notebooks

• The Load key dependencies cell (section 1.1) detects that it is running locally and skips the Colab-only installation and Google Drive steps, so you can run all cells in order.

• Enter the paths of folders on your computer in the text boxes (on Windows and Linux you can also pick them with the folder selector).

• ⚠️ NOTE: ⚠️ In Jupyter Lab some of the generated plots may be displayed in the log window, which is minimized at the bottom of your screen. To see the plots enlarge your log window:

  • Find the minimized log window in the bottom left corner and let it open to see the plots being generated.

    

Running the CellTracksColab Notebook in Google Colab with Local Runtime

1. Navigate to the CellTracksColab folder and activate the environment (created in Option 2)

   cd C:/Users/YourUsername/Path/To/CellTracksColab
   conda activate celltrackscolab

2. Start Jupyter Lab allowing connections from Google Colab and copy the Local Runtime Address

   jupyter lab --no-browser --ServerApp.allow_origin='https://colab.research.google.com' --port=8888 --ServerApp.port_retries=0

   • Copy the URL with the token printed in the terminal (for example http://localhost:8888/lab?token=...).

   

3. Open the Desired Notebook in Google Colab

   • Go to the start page of this wiki and open the desired notebook in Google Colab or upload one of your local notebooks to Google Colab.
   • ⚠️ NOTE: The notebook from Google Colab is not stored locally on your machine. Therefore, we strongly recommend you download or save it from Colab once the analysis is concluded.

4. Connect to Local Runtime from Colab

   • In Google Colab, click on the "Connect" button in the top right corner, then select "Connect to local runtime."

   • Paste the URL of your local runtime copied from the console and click "Connect."

     

   • Allow Google Colab to connect to your local runtime.

     

5. Run the Notebook

   • Follow the instructions provided in the notebook for running analyses.

   • Because the code runs on your computer, the Load key dependencies cell treats it as a local session: it uses the environment you installed and your local folders (Google Drive is not mounted).

   • ⚠️ NOTE: When running the notebooks this side panel might open, but can be ignored:

     

Troubleshooting with using Google Colab with Local Runtime:

• Make sure you started Jupyter Lab with the --ServerApp.allow_origin='https://colab.research.google.com' option shown above, and that you pasted the full URL including the token.
• ⚠️ If you are still unable to connect make sure that your ad blocker and any other privacy-enhancing tools in your browser are disabled for Google Colab to allow the connection with your local computing system.