Running CellTracksColab locally

Google Colab, while user-friendly, has some limitations, especially concerning data upload, data privacy, and reliance on Google's cloud services. To address these concerns, we offer the following options for running CellTracksColab locally: Jupyter Notebooks or using the Google Colab API with a local runtime.

Options for Running CellTracksColab Locally

1. Jupyter Notebooks:

• Full Privacy: Running the platform locally using Jupyter Notebooks ensures complete data privacy, as the data, code and analysis are kept on your local machine.
• Offline analysis: After installing CellTracksColab, this option allows for local analysis without requiring internet connection.
• Code Visibility: Although Jupyter Notebooks do not natively support hiding code, we have encapsulated the visible code within external functions. This significantly improves the clarity of the user interface and reduces potential intimidation for non-programmers, making the platform more user-friendly for all.

2. Google Colab with Local Runtime:

• Hybrid Solution: This approach leverages Google Colab's user-friendly interface while running computations on your local resources. This mitigates data privacy concerns and reduces dependency on Google's cloud services and data sharing.

📹 Video Tutorials

Tutorial: Using CellTracksColab locally with Jupyter

Tutorial: Using CellTracksColab Locally with Google Colab

Getting Started

1. Download the CellTracksColab Folder from GitHub

• Visit the CellTracksColab GitHub repository.
• Click on the green "Code" button and select "Download ZIP".
• Extract the downloaded ZIP file to a location on your computer.

2. Install Anaconda

• Anaconda is a distribution of Python and R for scientific computing and data science.
• Download Anaconda for your operating system.
• Follow the installation instructions for your operating system.

3. Install CellTracksColab

1. Open Anaconda Prompt

   • Open the Anaconda Prompt from your start menu (Windows) or applications folder (macOS/Linux).

2. Navigate to the CellTracksColab Folder

   • Use the cd command to change the directory to the location of the CellTracksColab folder you downloaded from GitHub. For example:

     cd C:\Path\To\CellTracksColab

   • Replace C:\Path\To\CellTracksColab with the actual path to the folder on your computer.

3. Install CellTracksColab

   • Run the following command to create the environment from the environment.yml file:

     conda env create -f environment.yml

   • During the installation the terminal may ask you to install a list of packages. Write y (for yes) and click on Enter. Once this process is finished, you will have a new conda environment called “celltrackscolab” with all the required dependencies.

4. Additional Information

   • For information on how to install an environment through the Anaconda GUI, check the Anaconda tutorial here.

Running CellTracksColab Notebooks in Jupyter Lab

1. Navigate to the CellTracksColab Folder

   • Open Anaconda Prompt and navigate to your CellTracksColab folder using the cd command. For example:

     cd C:/Users/YourUsername/Path/To/CellTracksColab

   • Replace C:/Users/YourUsername/Path/To/CellTracksColab with the actual path to the folder on your computer.

2. Activate the CellTracksColab Environment

   • Activate the environment by running the following command:

     conda activate celltrackscolab

3. Start Jupyter Lab

   • Start Jupyter Lab by typing:

     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.
   

4. Open the Notebook You Want to Run

   • Int he 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:
   

5. IMPORTANT notes when using the notebooks

• ⚠️ The first section (Part 0) of all notebooks is dedicated to setting up the Google Colab session. Skip these when running the notebooks locally.

• ⚠️ 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

   • Open Anaconda Prompt and navigate to your CellTracksColab folder using the cd command. For example:

     cd C:/Users/YourUsername/Path/To/CellTracksColab

   • Replace C:/Users/YourUsername/Path/To/CellTracksColab with the actual path to the folder on your computer.

2. Activate the Environment

   • Activate the environment by running the following command:

     conda activate celltrackscolab

3. Start Jupyter Lab and copy the Local Runtime Address

   • Start Jupyter Lab.

     jupyter lab

   • Jupyter will open in your browser. Please ignore it and go back to your Anaconda Prompt. There, copy the URL with the local runtime

   

4. 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.

5. 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.

     

6. Run the Notebook

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

   • ⚠️ IMPORTANT: The first section (Part 0) of all notebooks is dedicated to setting up the Google Colab session. Skip these when running the notebooks locally.

   • ⚠️ 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.

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

     

Troubleshooting with using Google Colab with Local Runtime:

To use a local runtime, Google Colab connects with HTTP. This traffic may not be enabled by default in some operating systems and browsers. To do so, an additional installation may be required:

1. Install Jupyter HTTP Over WebSockets in the CellTracksColab Environment

   • Activate the CellTracksColab Environment using the Anaconda Prompt or the terminal and install the jupyter_http_over_ws Python package.

     conda activate celltrackscolab
     pip install jupyter_http_over_ws

2. Enable the Extension

   • Enable the Jupyter HTTP over WebSockets extension:

     jupyter server extension enable --py jupyter_http_over_ws

3. Start Jupyter Notebook with Google Colab Access

   • Follow the same steps as in the section using Google Colab with Local Runtime, but rather than starting Jupyter Lab alone, you need to enable the connection with Google Colab:

     jupyter notebook --NotebookApp.allow_origin='https://colab.research.google.com' --port=8888 --NotebookApp.port_retries=0

     

   • Now you can follow the steps 4-6 from the previous section Running the CellTracksColab Notebook in Google Colab with Local Runtime.

⚠️ If you are still unable to connect make sure that your add blocker and any other privacy-enhancing tools in your browser are disabled for Google Colab to allow the connection with your local computing system.