iTReX: interactive Therapy Response eXploration
iTReX is an interactive analysis and visualization web application for mono- and combination therapy data. This user manual provides examples and step-by-step instructions to demonstrate screening data exploration and analysis.
iTReX modules are organized by tabs as shown below:
Home: the tab for uploading input files and setting analysis parameters.
QCN-, MRA-, CRA-mod: the three main modules, Quality Control and Normalization (QCN), Monotherapy Response Analysis (MRA), and Combination therapy Response Analysis (CRA) allow the exploration of therapy response data.
HitNet- and Omics-mod: two additional modules that allow generation and exploration of sample-specific drug-drug interaction networks.
About and FAQs: tabs providing further information about the iTReX app, terms of use, the developers and frequently asked questions (FAQs).
Proceed to Data Preparation and General Definitions
Data Preparation and General Definitions
Data Preparation
Input data must be provided in the form of a plate layout, defining therapies and concentrations for each plate well, and readout value. This section explains data formats and offers example data that can be used as templates. If any terms are unclear, you will find a list of general definitions at the end of this section.
Layouts
Each experiment is described by one layout file, which defines the layout of the plate(s) used for screening one sample. Layout files are worksheets in long-table format that must include the following columns.
Note that for a single sample, Sample and Readout columns can be filled in the layout file: for cohort analyses, they must be provided separately in the form of matrix files.
| Column | Details |
|---|---|
| Plate |
Plate numbers (1, 2, 3, …) or identifiers (such as P1, P2, P3, …) Plates will be sorted by this field, so plate replicates can be indicated by suffixes (1A, 1B, 2A, 2B, …). |
| Row | Well row coordinates (A, B, C, …) |
| Column | Well column coordinates (1, 2, 3, …) |
| Sample |
Sample identifiers Will be ignored and populated from matrix files names when using separate matrix readout files. |
| WellType |
“therapy” (for therapies under study), “pos” (positive controls), “neg” (negative controls), “TRC” (therapy controls), or other. “therapy”, “pos” and “neg” well types are mandatory, all others optional. “therapy” and “TRC” may have arbitrary numbers of replicates, but need to have exactly 5 different concentrations. Other well types can be freely defined. For example, empty wells (“empty”) could include only media, while untreated wells (“untreated”) could include the untreated sample in media. To avoid edge effects, it is recommended to use “empty” or “untreated” edge wells. Other than that, there are no restrictions regarding which well position can be of which well type. |
| Treatment | Treatment identifier (such as name of library therapy, control, …) |
| Concentration | Concentration of applied therapy |
| Replicate | Replicate numbers (1, 2, 3, …) |
| AddOn |
Combination therapy identifier (such as combination drug name) Used to indicate combination therapies; should be left empty for monotherapy analysis. |
| Readout |
Integer readouts, such as plate reader counts or image-based quantification results Will be ignored and populated from matrix files when using separate matrix readout files. |
Readouts
Readouts must be prepared as .xlsx spreadsheets or .txt text files, using one file per plate. Import from .txt files support many, but not all available raw-data formats – if in doubt, use the provided templates. Readouts from experiments with multiple plates per sample, or multiple samples (/cohort/), must be combined in one .zip archive.
Please name your spreadsheets or text files according to the following scheme: SampleID_PlateNumber, avoiding underscores in the plate identifiers SampleID (the underscore should only be used to separate the SampleID and PlateNumber).
Detailed instructions about all possible data uploads are also available in the iTReX app via dropdown buttons near each browse button.
Demonstration datasets are available below to explore the iTReX app using each of the following screen types:
1. Monotherapy, single sample (single file: Layout + Readouts)
2. Combination therapy, single sample, separate matrix files:
- Layout
- Readouts
3. Monotherapy, multiple samples (cohort), separate matrix files:
- Layout
- Readouts
General Definitions
Therapy: Any kind of chemical or physical perturbation assessed in a cell-based in vitro setting (i.e., low to high-throughput drug screening and profiling using approved or investigation drugs or chemical probes in specific concentrations/therapy units; radiation therapy applied in gray doses in vitro; etc.).
Monotherapy: Assessing the effect of a single agents (drug; radiation; chemical prob) in a concentration/dose range. This includes assessing multiple single agents in a multi-well setting. (i.e. test of a drug library of hundreds of agents).
Combination therapy: Combination of at least 2 therapy partners (i.e drug A + drug B, drug + radiation, etc.) Note, that currently combination therapy allows to analyze the combination of 2 therapy partners only in which one partner is applied in a single, fixed concentration combined with concentration series of therapy partner 2. Analysis modules for the combination of more than 2 partners and multiple concentration matrix screens are subject of current developments.
Sample: Any sample that is subject of your therapy tests: i.e. cell line, patient-derived xenografts, primary tumor or tissue sample.
Reference Sample(s): Any sample(s) that you would like to use as a reference to compare to and for which you have tested the therapy/therapies. You can use this to estimate the selectivity of the therapy, i.e. on a tumor sample vs a healthy reference sample or selectivity of the therapy on a specific entity/cell line etc by calculating a selective drug sensitivity score (sDSS; Yadav et al. 2014). You must run the analysis of the reference sample(s) before running the analysis of your sample of interest.
Positive controls (pos): Any toxic compound that kills most of the cells. This is used as a background signal control for normalization and serves as general cell death control. Example: Benzethonium Chloride.
Negative controls (neg): Any solvent that should not have an effect on the cells, ideally this is the solvent that is used for dilution of the therapeutic agents. Example: DMSO.
Therapy controls (TRC): Any therapy or compound that you would like to use as a control to assess the quality of the dose response curve and specific cell death response. Example: Staurosporine (STS).
Amin: Minimum activity threshold of the therapy as used by Yadav et al. (2014).
Cohort: x number of samples screened with the same layout and therapies. Multiple samples can be uploaded at once using a zip file and explored as a “cohort” in the MRA and CRA modules. Cohort results can be visualized as heatmap for comparison of sample sensitivities within one cohort.
1. Therapy Response Uploads and Analysis Parameters: Home
1- Select the number of samples to be analyzed: “Single Sample” or “Cohort”.
2- If the analysis includes a single sample only, the layout and readout files can be uploaded as a “Single File” (Layout Table including Readouts) or as “Separate Files” (Layout Table and Readout Matrices).
iTRex is able to process data from any plate layout format (e.g; 96, 384, 1536 .. etc, well plates).
3- Upload the layout table and/or readout matrices as indicated in the data preparation section of this user manual.
4- If reference sample(s) is/are available, please check the “Upload Reference Sample(s)” box.
5- Select the type of readout measures of the screen: “Cell Viability” or “Cell Death”.
6- Select the concentration unit used in the screen layout uploaded. “Nanomolar (nM)” is the default setting of iTReX according to the available demo layout. There are multiple alternative options provided such as “Molar (M)” or “Gray (Gy)”, or a “Custom Unit” can be selected and any used concentration unit can be typed into a text box.
7- Select the type of normalization. Normalization is computed based on negative and positive controls, and can be applied group-wise based on up to two columns of the layout table: Plate normalizes each plate (which may represent a replicate, as in the demo file) individually, across treatments; Treatment normalizes each treatment (which may represent a cell name, depending on the content of the Treatment column in your layout table) individually, across plates; Both normalizes each treatment on each plate individually.
8- Select the preferred DSS activity threshold (Amin) setting. “Variable 10% of Imax” is the default recommended setting of iTReX. There are multiple alternative options provided such as:
“Constant 10% Inhibition”: This sets the Amin to a fixed value of 10% as implemented in (Yadav et al., 2014).
“Constant 0% Inhibition”: This sets the Amin to a fixed value of 0%.
“Flexible threshold”: By setting this option a slider bar will appear, where you can set any other value according to the biological hypothesis / interest of the project.
9- Start of Analysis:
The analysis can be performed in “One-Click” or “Stepwise”.
“One-Click”: Runs the QCN, MRA modules and the CRA module in case a combotherapy is uploaded in one click. A progress bar indicates the progress of the analysis. The progress bar will disappear and a DONE message will appear as soon as the analysis is completed. After the analysis is completed, head to the “QCN-mod” tab to explore the quality control output, the “MRA-mod” tab to explore the monotherapy analysis output and the “CRA-mod” for combotherapy exploration if present. A results exploration section of the three modules is available in section 2 of this user manual.
“Stepwise”: Analyzes the therapy response step-by-step. Head to the “QCN-mod” tab first to perform the quality control analysis. The “QCN-mod” has to run before the “MRA-mod”. It is recommended to check the quality of your raw data first before moving to any further output. After running the “QCN-mod”, head to the “MRA-mod” and click “run analysis” to run the module, similarly this applies to the “CRA-mod” in case a combotherapy is uploaded. The MRA-mod must run before the CRA-mod in case a combotherapy is analyzed using a stepwise analysis.
After running iTReX QCN and MRA modules using the “One-Click” or “Stepwise” analysis type, the “HitNet” and/or “Omics” modules can be used to visualize sample specific networks.
2. Therapy Response Results Exploration: QCN-, MRA-, and CRA-mod
QCN-mod
- Screen Summary
The quality control summary table includes the mean, standard deviation, the coefficient of variation for each measured well type, the Z-prime and robust Z-prime per plate and the mean of each score respectively of the full screen.
Screen Z-prime higher than 0.5 are considered to be of very good quality, while a Z-prime less than 0 is considered to be of poor quality.
- Raw Count Distribution
This plot is generated to check the mean raw counts and intensity read of the plate reader for each plate.
- Plate Layout
The plate layout plot visualizes the position of each well type on the plate, where the visualized layout must match the screened and uploaded layout.
- Well Distribution
The raw count distribution per well is visualized for each plate, where the negative and positive controls uploaded should show a distinctive difference to ensure a high quality screen normalization.
- Replicate Scatter Distribution
A correlation plot for duplicates is visualized if replicates of therapies (i.e duplicates of each drug and concentration) are present. A correlation coefficient (R2) higher than 0.7 indicates a high quality control screen.
- Controls QC
The viability of positive and negative controls are visualized at there relevant well positions. All positive control wells should show low viability (blue), while negative control wells must indicate a greater viability value with the continuous color scale (white-red) for a high quality screen.
- Viability Heatmap
Normalized and unNormalized viability heatmaps to visualize the overall data per well.
- Therapy Control Response
Fitted dose response curve of the therapy controls uploaded (if any). This curve acts as a positive control to the fitting of a positive treatment and indicates the quality of the screen post normalization.
MRA-mod
Sample Screen: the sample screen tabset visualizes the MRA-mod output of one sample. In case a cohort analysis is uploaded, please select the sample of interest to be visualized.
- MRA Therapy Parameters
The MRA tabulated output, where the columns indicate the following result parameters:
| Column | Detail |
|---|---|
| Drug.ID | Therapy numbers (alphabetical ordering) |
| Drug.Name | Therapy names |
| abs_IC(50/25/75) | Concentration at 50%/25%/75% inhibition (based on the fitted dose-response curve) |
| rel_IC50 | Concentration at midpoint between Imin and Imax (based on the fitted dose-response curve) |
| Slope | Hill slope of the fitted dose-response curve |
| Imin | Minimum possible attainable percent inhibition |
| Imax | Maximum possible attainable percent inhibition |
| MIN.Conc.tested.nM | Minimum tested concentration (in nM) |
| MAX.Conc.tested.nM | Maximum tested concentration (in nM) |
| DSS_asym | Asymmetric Drug Sensitivity Score |
| PI(n) | Percent inhibition at nth concentration |
| GOF | Goodness of fit |
| Amin | DSS activity threshold (based on user selection in the Home tab) |
| DSS_asym_adj | DSS_asym adjusted based on GOFs |
| controlDSS | DSS_asym of healthy controls (uploaded in the Home tab) |
| sDSS_asym | Selective DSS_asym (difference between DSS_asym of samples and controls) |
| controlDSS_adj | DSS_asym of healthy controls adjusted based on GOFs |
| sDSS_asym_adj | Selective DSS_asym adjusted based on GOFs (difference between DSS_asym_adj of samples and controls) |
| analysis | Sample names |
- iHeatmap
An interactive heatmap ranking all analyzed therapies according to the DSSasym metric descendingly. The dose response curves can be visualized upon hovering on a specific therapy.
- MRA DSSasym Waterfall Plots
Waterfall plot indicating the rank of the sensitivities of the therapies according to the DSSasym metric. This is followed by the goodness of fit (GOF) scatter plot indicating the relation between the DSSasym and the GOF, where each point indicates an analyzed treatment. Ideally top hit sensitivity treatments should have a high GOF. The second waterfall plot visualizes the treatment ranking based on the DSSasym,adj which takes the GOF into consideration within the final score.
- sDSSasym Waterfall Plots
Waterfall plot indicating the rank of the sensitivities of the therapies according to the sDSSasym metric. The positive sDSSasym indicates that the treatment has a higher effectivity in the sample than in the reference sample(s) (is selectively effective in the sample), while a negative sDSSasym indicates a higher effect of treatment in the control sample, indicating general toxicity of the treatment. The plot is followed by the goodness of fit (GOF) scatter plot indicating the relation between the sDSSasym and the GOF scatter plot. The second waterfall plot visualizes the treatment ranking based on the sDSSasym,adj which takes the GOF into consideration within the final score.
CRA-mod
Sample Screen: the sample screen tabset visualizes the CRA-mod output of one sample. In case a cohort analysis is uploaded, please select the sample of interest to be visualized.
- CRA Therapy Parameters
The CRA tabulated output is similar to the MRA therapy parameters output, however including the combination therapies analyzed in the screen rather than monotherapies. The output includes the following column details:
| Column | Detail |
|---|---|
| Drug.Name | Therapy names |
| dPI(n) | Differential Percentage Inhibition at nth concentration |
| dcDSS_asym | Asymmetric differential combination Drug Sensitivity Score (difference between DSS_asym of combination and monotherapy) |
- CRA DSSasym Waterfall Plot
The combination therapies are visualized in DSSasym waterfall plots and adjusted to the GOF similar to the functionality of the MRA DSSasym waterfall plot for monotherpaies
- CRA dcDSSasym & dPI Table
The CRA tabulated output includes the dPI and dcDSSasym as follows:
| Column | Detail |
|---|---|
| Drug.Name | Therapy names |
| dPI(n) | Differential Percentage Inhibition at nth concentration |
| dcDSS_asym | Asymmetric differential combination Drug Sensitivity Score (difference between DSS_asym of combination and monotherapy) |
- dcDSSasym Waterfall Plot & dPI Matrix
A waterfall plot revealing positive dcDSSasym (blue) and negative dcDSSasym metric (red). Positive values indicate a possible enhanced effect of the combotherapy over the monotherapy, while the negative values may explain a possible antagonism as the monotherapy DSSasym exceeds the combotherapy DSSasym. In rare cases the synergy and antagonism curve shift may be influenced by the curve fitting with a false interpretation. Thus the dPI values are essential to confirm the results of the dcDSSasym metric. A positive dcDSSasym and positive dPI values indicate a synergistic effect, while a negative dcDSSasym confirmed by negative dPI values indicate an antagonistic effect. dcDSSasym and dPI values near zero (0 +/- 2) explain a possible additive effect. The dPI matrix is visualized for positive dcDSSasym values (right) and is visualized for all combotherapies included in the analysis (left).
Cohort Screen
A cohort heatmap can be visualized for both MRA and CRA outputs using the MRA-mod and CRA-mod cohort screen tabsets respectively.
Heatmaps are generated for the whole uploaded cohort as demonstrated below:
The clustering distance can be adjusted to the method of interest. Moreover, checkboxes are available to visualize the sDSSasym heatmap if reference sample(s) have been uploaded, the therapy standard deviations (SDs), and the quality control z-prime (z’) values.
The plot width and height can also be adjusted using the slider bar.
3. Sample Specific Networks: HitNet- and Omics-mod
HitNet-mod
The HitNet module visualizes Drug-Drug interaction networks without mapping Omics features. If you have molecular features for your sample you can directly use the Omics module to visualize the network.
To visualize the HitNet output follow the steps indicated below:
1- Select the sample of interest.
If you have one sample only, the name of the sample will be present as the default selected sample.
2- Select your preferred form of drug target annotation.
You can upload your Drug-Target annotation table as a .xlsx spreadsheet or use annotations from DrugBank. Please note that you have to sign up for DrugBank to access the files - you can follow the link specified in the app in this case.
Below is an example sample annotation file prepared for demonstration post running the Monotherarpy demo dataset. Select Upload Table and upload the example sheet. The Drug names must match the layout drug names uploaded in the iTReX “Home” tab.
The column names of the uploaded spreadsheet must be identical to the demo spreadsheet column names as shown below.| Column | Details |
|---|---|
| Drug.Name | Drug names |
| Gene.Name | Drug target gene names (following HUGO nomenclature) |
3- Select the number of top hit drugs to be visualized.
Ideally you should select this value based on the results of the MRA module, aiming to include top hit drugs only.
For demonstration you can select a number of 10 drugs.
4- Set the screen type to: “Monotherapy” and click “Create Network”.
Omics-mod
The Omics module allows to visualize drug target interaction networks while highlighting molecular (Omics) features of the analyzed sample.
In order to visualize the network follow the steps indicated below:
1- Select the sample of interest.
If you have one sample only, the name of the sample will be present as the default selected sample.
2- Upload the Omics table including the molecular features of the specified sample.
Gene symbols must be specified according to HUGO gene nomenclature. An example .xlsx is available below to demonstrate the matching monotherapy demo sample. The uploaded table must include the molecular features of the sample with at least one of the following molecular feature types: mutations, expression, fusion.
The column names of the uploaded spreadsheet must be identical to the demo spreadsheet column names.
3- Select your preferred form of drug target annotation.
You can upload your Drug-Target annotation table as a .xlsx spreadsheet or use annotations from DrugBank. Please note that you have to sign up for DrugBank to access the files - you can follow the link specified in the app in this case.
Below is an example sample annotation file prepared for demonstration post running the Monotherarpy demo dataset. Select Upload Table and upload the example sheet. The Drug names must match the layout drug names uploaded in the iTReX “Home” tab.
The column names of the uploaded spreadsheet must be identical to the demo spreadsheet column names as shown below.| Column | Details |
|---|---|
| Drug.Name | Drug names |
| Gene.Name | Drug target gene names (following HUGO nomenclature) |
4- Select the number of top hit drugs to be visualized.
Ideally you should select this value based on the results of the MRA module, aiming to include top hit drugs only.
For demonstration you can select a threshold of 10
5- Set the screen type to: “Monotherapy” and click “Create Network”.
