Package: rainbow-optical-flow
RainbowSoftware for automated Air-Liquid Interface cell culture image analysis using deep optical flow. Seebelowfor more details.Table of contentsInstallationUsageAdditional InformationExamplesCommunity GuidelinesLicenseSoftware PaperOur TeamAcknowledgementsInstallationRainbow can be installed on Linux, Windows & macOS and supports Python 3.8 and above. We recommend installing and running Rainbow within avirtual 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 installPython(Rainbow was tested usingPython version 3.8.10).Launch the terminal (LinuxandmacOSusers) or command prompt (Windowsusers). 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(LinuxandmacOSusers) orrainbow-env\Scripts\activate.bat(Windowsusers)python -m pip install -U pipInstall PyTorch by specifying your system configuration using the officialPyTorch get started tooland running the generated command:For example, Windows users without a GPU (i.e. CPU only) will run:pip install torch torchvision torchaudioNext, proceed wth either option A or B.Option A - Install from PyPIThis is the simplest and fastest way to install Rainbow, recommended for normal users.Install Rainbow:pip install rainbow-optical-flowOption B - Install from SourceDevelopers may wish to install Rainbow from source. Please ensureGitandGit LFSare installed before proceeding.Clone this repository into your desired directory:git clone https://github.com/AlphonsG/Rainbow-Optical-Flow-For-ALI.gitNavigate into the cloned directory:cd Rainbow-Optical-Flow-For-ALIInstall Rainbow:pip install -e .Finalize the installation by running the following commands:git submodule sync

git submodule update --init --recursiveNotes:1Confirm the correct python version for Rainbow has been installed using thepython -Vcommand in the terminal. If this command does not report the correct python version, try using thepython3 -vcommand instead. If the second command produces the expected result, replace allpythonandpipcommands in this guide withpython3andpip3, respectively.The virtual environment can be deactivated using:deactivateIf Rainbow fails to install on Linux, it may be becausewxpythoncould 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 installingwxpythonfirst by followingtheseinstructions (specifically "Yes, we have Linux Wheels. Sort of.") and then attempt to install Rainbow again viapip install rainbow-optical-flow(option A) orpip install -e .(option B).UsageCommand Line Interface (CLI)Once installed, Rainbow can be used through a CLI. Runrainbow --helporrainbow -h(within therainbow-envenvironment 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 theinstallationprocedure (except for step 7) and run the following commands in the terminal:cd rainbow
rainbow ../examples/example_image_series ../misc/configs/default_config.yamlAfter processing is finished, a folder containing similar outputs (e.g. a HTML report,  videos, images, CSV files) to those inthisexample output folder should be generated inthisfolder.Graphical User Interface (GUI)Once installed, Rainbow can be be used through a GUI, which can be launched by running the commandrainbow(within therainbow-envenvironment if applicable).To test Rainbow using an example Air-Liquid Interface cell culture image series, follow the instructions under option B of theinstallationprocedure (except for step 7) and run the following commands in the terminal::cd rainbow
rainbowThen, in the GUI that opens, selectthisfolder as the input image series andthisfile 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 inthisexample output folder should be generated inthisfolder.Additional InformationOptical FlowRainbow uses a deep learning model calledGMAto 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 thebase_modelinterface (gma.pyis an example of that).AnalysisRainbow can automatically generate an analysis report after computing the optical flow in an image series. A base report file that can be modified is providedhereas a Jupyter notebook. The path of a Jupyter notebook needs to specified in the config for automatic report generation (default provided).ScriptsThescriptsfolder 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. Runpython <script-name>.py --helpin the terminal to view the usage instructions for a script.Automated TestingTo perform and check the status of the automated tests locally, run the commandpytestin the terminal, with Rainbow installed, from the root directory of this repository after cloning.ExamplesExamples 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 SeriesExperimental MethodsPrimary 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.ReferencesLooi,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 guidelinesGuidelines for third-parties wishing to:Contribute to the softwareReport issues or problems with the softwareSeek supportcan be foundhere.LicenseMIT LicenseSoftware PaperTitleRainbow: Automated Air-Liquid Interface Cell Culture Analysis Using Deep Optical FlowAccesshttps://joss.theoj.org/papers/10.21105/joss.04080Our TeamLearn moreAcknowledgementshttps://github.com/philferriere/tfoptflowhttps://docs.opencv.org/3.4/d4/dee/tutorial_optical_flow.htmlhttps://github.com/zacjiang/GMA