Most updated version of BEHAV3D pipeline can be found here
BEHAV3D now runs on Google Colab, check it out here
BEHAV3D is dynamic immuno-organoid 3D imaging-transcriptomics platform to study tumor death dynamics; immune cell behavior and behavior-guided transcriptomics.
- Any type of multispectral time-lapse 3D (or 2D) imaging data, where objects such as cells or organoids are in co-culture or single culture.
- Any type of change of cell state that can be detected by a change in fluorescent intensity e.g. cell death, reporter, Ca2+ signalling
- Classification of different types of cell dynamics
- Correlation between dynamics of different cell types
- Interaction between cell types
- Predicted behavior states infered to transcriptomic data
BEHAV3D runs on R studio (version 4.0.2) and was tested on Windows 10.
Download the repository to your PC via direct dowload or git clone https://github.com/alievakrash/BEHAV3D.git in Git Bash.
See in each module and script the required libraries or install in R Studio libraries for all modules: devtools, dplyr, dtwclust, eulerr, ggplot2, ggpubr, ggrepel, gridExtra, hypergeo, kmodR, lme4, lmerTest, MESS, nlme, openxlsx, parallel, patternplot, pheatmap, plotly, plyr, png, purr, RColorBrewer, readxl, reshape2, rgeos, scales, Seurat, sp, spatstat, stats, tidyr, tidyverse, umap, VennDiagram, viridis, xlsx, zoo.
The current version of the pipeline works with objects (cells or organoids) time-lapse statistics that are aquired by tracking these objects in a commercially available software (Imaris, Oxford Instruments). However any type of time-lapse data can be processed with the pipeline, including measruements extract from MTrackJ (Fiji) or others. Main feature that is needed are coordinates for the objects and a common ID for the same object that is tracked over time. Aditional statistics describing the cell behavior such as speed, displacement are calculated by Imaris, however they can also be calculate by pre-processing algorithms from the cell coordinates. Statistics related to the expression of markers of interest (e.g live-dead cell dye) should be included to study the dynamic expression of these overtime. For statistics related to distance to organoids, use the min_intensity in ch X (corresponding to the channel number created by the Distance transformation Xtension. Rename it to be called dist_org.
In this repository we provide an example dataset consisting of a multispectral time-lapse 3D imaging dataset originated from a co-culture of engeneered T cells and Tumor derived organoids. Multispectral imaging allows to identify: Live/dead T cells; Live/Dead organoids. For downstream analysis of organoids: either individual tumor derived organoids are tracked overtime or the total organoid volume per well is tracked. For each generated object we acquire information on the dead cell dye intensity and position and volume of individual organoids. For downstream analysis of T cell: T cells are tracked overtime. For each Tracked T cell object we aquire, position per timepoint, speed, square displacement, distance to an organoid, dead dye intensity, major and minor axis length (used in some downstream analysis).
This repository contains a collection of scripts and example datasets enabling the following dowstream analysis. Follow the structure in the script folder for each module and each analysis type. Introduce the corresponding folder/ file direction on your own computer where required (note that to specify directory paths in R (/) forward slash is recommended):
- Batch import tracked organoids data:
-Run script batch_import_organoids_data_for_each_n
-Insert here the direction of the example dataset on your PC
Output files: Full_well_death_dynamics.rds and Individual_orgs_death_dynamics.rds
- Compute death dynamics per well:
-Run script Calculate_mean_dead_dye_perwell.R
-Insert here the direction of the processed dataframe Full_well_death_dynamics.rds on your PC
- Compute individual organoid death dynamics:
-Run script Individual organoids death dynamics.R
-Insert here the direction of the processed dataframe Individual_orgs_death_dynamics.rds
- Batch import tracked T cell data:
-Run script Import T cells data.R
-Insert here the direction of the example dataset on your PC.
-If you are processing a new dataset, check here for unique filenames. Each filename should correspond to a unique well and/or cell type processed. Then adjust and duplicate when necessary these, these and these lines. Adjust here the threshold distance to organoids to identify T cells that are interaction with an organoid. Duplicat and adjust these lines if you have new experiments to process. Due to variation in imaging settings and image processing this value might change from one experiment to another.
-Insert here and here where to store the output master_example_data and master_corrected3_example dataframes, respectively.
- Compute the Behavioral reference map generation (by Dynamic time warping):
-Run script Create_Behavioral_Reference_map.R
-Insert here the direction of your dataset used for reference map. In this case we use the example dataset, consisting of only two different wells. For the creation of a new reference map use a compilation of datasets with different cell types of interest (likely to have different behavioral signatures). If you are creating a new reference map, insert here the direction for your output dataframe.
- Backproject behavioral signatures in the imaging dataset:
-Run script Create_Behavioral_Reference_map.R
-Insert here the direction of master_example_data that is used to reconvert the unique TrackIDs that are created for processing back into the original TrackIDs, that will be used for backprojection.
-For each well of interest adapt here with the corresponding "ranks" and output direction.
- Predict T cell behavior classification for new datasets, based on the Behavioral reference map :
-Import your new dataset as indicated above
-Run script Random_forest_classifier
-Insert here the direction of the Behavioral_Referance_map on your PC.
-Insert here the direction of your imported new dataset. For testing use the provided example dataset: master_corrected3_example
This module integrates information from single cell sequencing and behavioral profiling, by predicting in a behavioral phenotype of single cells in scRNA seq data. For more information see Figure 3 in https://www.biorxiv.org/content/10.1101/2021.05.05.442764v2
- Compute behavioral probability map for scRNA seq data:
-Run script Behavioral-guided transcriptomics
-Insert here the directory containing the scRNA seq dataset containing pseudotime trajectory on your PC.
-Insert here the direction of csv file containing the proportion of behavioral signatures epr experimental condition, calculated in silico based on imaging data.
-Insert here the direction of the folder containing a set of probability maps quantified with different cluster resolutions.
-Check here if any of the behavioral signatures has extreme outlier probability values due to skewed distributions and transformed to a maximal cutoff value as shown here
-Insert here the directory to store the output Seurat object.