rainbow-optical-flow 2022.4.6

Description:

rainbowopticalflow 2022.4.6

Rainbow








Software for automated Air-Liquid Interface cell culture image analysis using deep optical flow. See below for more details.
Table of contents

Installation
Usage
Additional Information
Examples
Community Guidelines
License
Software Paper
Our Team
Acknowledgements

Installation
Rainbow can be installed on Linux, Windows & macOS and supports Python 3.8 and above. We recommend installing and running Rainbow within a virtual environment. Although it is not a requirement, we also recommend installing and running Rainbow on a GPU-enabled system to minimize processing times.


Download and install Python (Rainbow was tested using Python version 3.8.10).


Launch the terminal (Linux and macOS users) or command prompt (Windows users). The proceeding commands will be entered into the opened window1.


(Optional but recommended) Create and activate a virtual environment called 'rainbow-env' in your desired directory:
python -m venv rainbow-env
. rainbow-env/bin/activate (Linux and macOS users) or rainbow-env\Scripts\activate.bat (Windows users)
python -m pip install -U pip


Install PyTorch by specifying your system configuration using the official PyTorch get started tool and running the generated command:



For example, Windows users without a GPU (i.e. CPU only) will run:
pip install torch torchvision torchaudio


Next, proceed wth either option A or B.
Option A - Install from PyPI
This is the simplest and fastest way to install Rainbow, recommended for normal users.


Install Rainbow:
pip install rainbow-optical-flow


Option B - Install from Source
Developers may wish to install Rainbow from source. Please ensure Git and Git LFS are installed before proceeding.


Clone this repository into your desired directory:
git clone https://github.com/AlphonsG/Rainbow-Optical-Flow-For-ALI.git


Navigate into the cloned directory:
cd Rainbow-Optical-Flow-For-ALI


Install Rainbow:
pip install -e .


Finalize the installation by running the following commands:
git submodule sync

git submodule update --init --recursive



Notes:


1Confirm the correct python version for Rainbow has been installed using the python -V command in the terminal. If this command does not report the correct python version, try using the python3 -v command instead. If the second command produces the expected result, replace all python and pip commands in this guide with python3 and pip3, respectively.


The virtual environment can be deactivated using:
deactivate


If Rainbow fails to install on Linux, it may be because wxpython could not be built (look for clues in the error messages printed on the terminal e.g. "Running setup.py install for wxpython ... error"). Instead, try installing wxpython first by following these instructions (specifically "Yes, we have Linux Wheels. Sort of.") and then attempt to install Rainbow again via pip install rainbow-optical-flow (option A) or pip install -e . (option B).


Usage
Command Line Interface (CLI)
Once installed, Rainbow can be used through a CLI. Run rainbow --help or rainbow -h (within the rainbow-env environment if applicable) for a list of available command arguments and descriptions.
To test Rainbow using an example Air-Liquid Interface cell culture image series, follow the instructions under option B of the installation procedure (except for step 7) and run the following commands in the terminal:
cd rainbow
rainbow ../examples/example_image_series ../misc/configs/default_config.yaml

After processing is finished, a folder containing similar outputs (e.g. a HTML report, videos, images, CSV files) to those in this example output folder should be generated in this folder.
Graphical User Interface (GUI)
Once installed, Rainbow can be be used through a GUI, which can be launched by running the command rainbow (within the rainbow-env environment if applicable).
To test Rainbow using an example Air-Liquid Interface cell culture image series, follow the instructions under option B of the installation procedure (except for step 7) and run the following commands in the terminal::
cd rainbow
rainbow

Then, in the GUI that opens, select this folder as the input image series and this file as the configuration file in the GUI under 'Required Arguments' and click the 'Start' button. After processing is finished, a folder containing similar outputs (e.g. a HTML report, videos, images, CSV files) to those in this example output folder should be generated in this folder.
Additional Information
Optical Flow
Rainbow uses a deep learning model called GMA to compute the optical flow in an image series. This model can be replaced with any other method for computing optical flow by writing a custom class that implements the base_model interface (gma.py is an example of that).
Analysis
Rainbow can automatically generate an analysis report after computing the optical flow in an image series. A base report file that can be modified is provided here as a Jupyter notebook. The path of a Jupyter notebook needs to specified in the config for automatic report generation (default provided).
Scripts
The scripts folder contains python scripts to enable additional functionality such as the ability to combine reports from multiple experiments into one file for simpler viewing and comparisons. Run python <script-name>.py --help in the terminal to view the usage instructions for a script.
Automated Testing
To perform and check the status of the automated tests locally, run the command pytest in the terminal, with Rainbow installed, from the root directory of this repository after cloning.
Examples
Examples of some of the data generated by Rainbow can be seen below.
Raw Image Series (left) and Rainbow Optical Flow Visualisation (Right)

Magnitude Heatmaps (Left) and Quiver Plots (Right) Across Image Series

Experimental Methods
Primary tracheobronchial epithelial cells were isolated through trans‐laryngeal, non‐bronchoscopic cytologic brushings via an endotracheal tube from two children (3.3 and 4.1 years), as previously described (Looi et al., 2018; Martinovich et al., 2017). The use of tracheobronchial epithelial cells for these studies were approved by the Human Research Ethics Committees of St John of God Hospital and The University of Western Australia. Cells were imaged (20x objective) on day 2 post air-lift for 2.5 hrs every 8 mins with a Nikon C2+ inverted microscope incubated at 37° C with humidified 95% air/5% CO2 using an Okolab live cell imaging chamber to generate time lapse images of maximally migrating cells as previously described (Park et al., 2015; Mitchel et al., 2020). The example image series provided in this repository contains 20 image frames at 1280 x 1024 px resolution.
References
Looi,K. et al. (2018) Effects of human rhinovirus on epithelial barrier integrity and function in children with asthma. Clinical & Experimental Allergy, 48, 513–524.
Martinovich,K.M. et al. (2017) Conditionally reprogrammed primary airway epithelial cells maintain morphology, lineage and disease specific functional characteristics. Scientific Reports, 7, 17971.
Mitchel,J.A. et al. (2020) In primary airway epithelial cells, the unjamming transition is distinct from the epithelial-to-mesenchymal transition. Nature Communications, 11, 5053.
Park,J.-A. et al. (2015) Unjamming and cell shape in the asthmatic airway epithelium. Nature Materials, 14, 1040–1048.
Community guidelines
Guidelines for third-parties wishing to:

Contribute to the software
Report issues or problems with the software
Seek support

can be found here.
License
MIT License
Software Paper
Title
Rainbow: Automated Air-Liquid Interface Cell Culture Analysis Using Deep Optical Flow
Access
https://joss.theoj.org/papers/10.21105/joss.04080
Our Team
Learn more
Acknowledgements

https://github.com/philferriere/tfoptflow
https://docs.opencv.org/3.4/d4/dee/tutorial_optical_flow.html
https://github.com/zacjiang/GMA