IR-TEx: An Open Source Data Integration Tool for Big Data Transcriptomics Designed for the Malaria Vector Anopheles gambiae

1. Using the IR-TEx web application

1. Running the application in a web browser
   1. Open the IR-TEx web application by following the link at the bottom of the page found at http://www.lstmed.ac.uk/projects/IR-TEx.
   2. Once the web page has initialized, click the Application button at the top of the page, which will display the application and associated outputs.
   3. Read each output related to the default entry of AGAP008212-RA (CYP6M2) in the transcript ID box with the following conditions: An. coluzzii datasets that are (i) exposed to pyrethroid insecticides or (ii) not exposed to any insecticide class, and associated transcripts with a correlation of |r| >0.98.
2. Exploring expression of a transcript of interest
   1. To select a transcript of interest, input the transcript ID into the Transcript ID box, remembering that transcripts end in -RX dependent upon isoform of interest.
   2. Select the datasets to interrogate by ticking the relevant boxes for (i) Countries; (ii) Exposure status, (iii) Species of interest; and (iv) Insecticide class of interest, all while ensuring that these criteria result in >1 included dataset (see Supplementary Table 1 in Ingham et al.¹).
      NOTE: (iii) refers to the member of the An. gambiae species complex that the user interested in. Currently, data are available for An. coluzzii and An. arabiensis.
   3. Click Update View at the bottom of the selection menu or press Return, ignoring Absolute Correlation Value (for now).
   4. Give the application time to update.
   5. Read the first graph as: log₂ fold change between a resistant population and lab-susceptible mosquito population of the transcript of interest across each dataset that meets the criteria selected in step 1.2 (Figure 1). The details of all datasets can be found in Ingham et al.¹.
   6. Read the information below the graph as: the fold changes between the resistant and susceptible mosquitoes for each relevant dataset, in addition to the corrected p-values (Q). Each row represents individual probes on the microarray. The methodology for graphical display has been reported previously¹.
   7. Read the additional table below as the number of experiments in which the transcript of interest is significant as well as the total number of experiments matching the criteria selected in step 1.2.
   8. To download the data in tab separated format, click the Download button under the two tables. This allows the user to explore data in an easier manner using a program such as Excel.
   9. Interpret the map as follows: each point represents the approximate collection sites of resistant mosquitoes in each dataset in which the transcript of interest is differentially expressed. The colors follow a traffic light system that is explained in the app (Figure 2).
   10. For steps 1.2.5 and 1.2.8, save the graphical outputs by right-clicking, clicking Save image as…, and choosing an appropriate folder.
       NOTE: In the instance of an output error by the application, it is likely that no datasets match the inputted criteria. Check Supplementary Table 1 in Ingham et al.¹ if this occurs.
3. Identifying putative functions/pathways of transcript of interest
   1. Correlations (minimum r² value inputted) of the expression patterns of transcripts across multiple datasets can be used to predict transcript function and potentially elucidate coregulated transcripts from the same pathway. Using the example from Ingham et al.¹ (AGAP001076-RA; CYP4G16), follow steps 1.2.1–1.2.2 in the section above, selecting all datasets for maximal power.
   2. Before clicking Update View, move the Absolute Correlation Value slider to 0.85, and click Update View or press Return.
   3. Examine the correlation table (bottommost table) to find the multiple transcripts that are now displayed and are correlated (|r| = 0.85) with the inputted transcript.
   4. Manipulate the Absolute Correlation Value slider and observe any changes in the bottommost graph and table; the outputs from step 1.3.2 will remain unchanged. As shown in Figure 3 (|r| > 0.9, |r| > 0.8), lowering the stringency of the correlation value will show more transcripts but will introduce more noise.
   5. Read the table below the graphical output, which (in addition to the parameters described in step 1.2.6) contains the correlation value for each transcript.
   6. To download the data in a tab-separated format, click the Download button.
   7. Functional enrichment analysis can be performed on the downloaded transcript ID list using DAVID analysis⁸. Once on the DAVID website (found at https://david.ncifcrf.gov/), select Functional Analysis. Paste the full gene list, using gene IDs [identifier without the -RX, which can be done in excel by inserting a column to the right of the Systematic ID and typing =LEFT(X1,10), where X1 is the Systematic ID cell]. Select the identifier as VectorBase_ID and gene list and click Submit List.
   8. Click the Functional Annotation Clustering button to yield an overview of the enrichments found in this correlation network, allowing a potential function to be assigned to the transcript. Explore in-depth enrichments by looking through the different categories and clicking the + buttons for each and subsequently clicking Chart.

2. Downloading and implementing IR-TEx locally

1. Downloading and running IR-TEx
   1. Go to the link found at http://github.com/LSTMScientificComputing/IR-TEx; and click Clone or download | Download Zip. Direct to a folder of choice and unzip the file in that folder.
   2. Download the latest version of R software for the appropriate operating system from the link found at http://cran.r-project.org/mirrors.html. Install the program.
   3. Download and install the latest R Studio software, again for the appropriate operating system from the link found at http://www.rstudio.com/products/rstudio/download/.
   4. Once installed, open R Studio | Supplemental coding File 1 and run each line to set up the system for IR-TEx.
   5. Once all packages are successfully installed and updated as required, go to File | Open, locate IR-TEx.R, highlight, and open. This should now be visible in the top window of R Studio.
   6. To run the app, press the Run App button in the top-right of the window, and a second window will pop up in which the app will load. Once the loading is complete, for full functionality click Open in Browser located in the top-right of the loaded window.
2. Adding resistance datasets to IR-TEx (generated using Anopheles gambiae 15k Agilent array)
   1. To add a new analyzed dataset generated on the same microarray platform (A-MEXP-2196) to the available dataset, download the app and locate the unzipped folder downloaded in section 2.1.
   2. Open Additional File 1, which represents an output from a limma analysis on A-MEXP-2196 ¹. Using Excel, in column H1, write Fold_Change, and in H2, write =2^B2, in which B2 is the log fold change. Apply this throughout column H to produce raw fold changes.
   3. Arrange Additional File 1 such that column A is the ID, column B is the fold change from column H (copy column H, highlight column B, then right-click and paste values) and column C is the adjusted p-value. Delete all other columns and save as a tab-delimited file.
   4. Open Supplemental coding File 2 and run using the tab-delimited sheet produced in step 2.2.3.
      NEWFILE_FC = c('COUNTRY','EXPOSURE STATUS','SPECIES','INSECTICIDE')
      NEWFILE_Q = c('COUNTRY','EXPOSURE STATUS','SPECIES','INSECTICIDE')
      NOTE: Fields within single quotation marks should be changed to reflect information from the new dataset. Exposure status refers to whether samples were collected following insecticide exposure (exposed/unexposed). Insecticide: if 'unexposed', use 'none'. See Fold_Changes.txt. for metadata from other samples. Ensure that spelling is consistent.
   5. Open geography.txt, scroll to the final occupied row, and select below. Type in the name of the dataset, followed by Q and NEWFILE_Q in column 1, the latitude of the sample collection site in column 2, and the longitude in column 3. Save the changes.
   6. If any novel entries are used (i.e., Gambia), which are not available for selection in the dataset (see Ingham et al. Supplementary Table 1¹), these will need to be added into the code. To do this, open IR-TEx.R in RStudio and locate line 26 as indicated by RStudio, at which point the following should begin:
      'sidebarPanel(….'.
      NOTE: Each of the proceeding rows relates to an item of metadata inputted into the rows below the dataset name in Fold_Changes.txt in step 2.2.5.
   7. To add the novel metadata, scroll to the end of the line of the metadata of choice, and locate the term 'selected='. Immediately following this should be a comma and closed bracket; at this point, click the cursor within the closed bracket. After the final apostrophe, type a comma, followed by an apostrophe, followed by the new metadata (e.g., 'Gambia'), and save the changes. See below for an example.
      checkboxGroupInput('CountryInput','Select Relevant Countries',c('Burkina Faso','Cote D`Ivoire','Cameroon','Equatorial Guinea','Zambia','Tanzania','Sudan','Uganda','Togo', 'Gambia'),selected=c('Burkina Faso','Cote D`Ivoire','Cameroon','Equatorial Guinea','Zambia','Tanzania','Sudan','Uganda','Togo'))
   8. Run the app. The new metadata entry should appear as an unselected tick box under the relevant heading. If the user wants it to be selected, it should be added after the selected=c(…, as shown below:
      checkboxGroupInput('CountryInput','Select Relevant Countries',c('Burkina Faso','Cote D`Ivoire','Cameroon','Equatorial Guinea','Zambia','Tanzania','Sudan','Uganda','Togo', 'Gambia'),selected=c('Burkina Faso','Cote D`Ivoire','Cameroon','Equatorial Guinea','Zambia','Tanzania','Sudan','Uganda','Togo', 'Gambia'))
   9. To add resistance datasets not performed on A-MEXP-2196, see section 3.

3. Modifying IR-TEx for use with different datasets

1. Use across multiple -omics platforms and proceeding with missing data
   1. To proceed with "0" in datasets: consult the dataset source for the specific meaning of "0". It is recommended that "0" is (conservatively) replaced with "NA". As with raw fold changes (B/A), "0" indicates an undetected signal in experimental condition B. In the case that experimental condition A exhibits substantial expression, the user can apply a small fold change value.
   2. Open Additional File 2.txt, an RNAseq file adapted from Uyhelji et al.⁹. This file represents the template in which new data should be based: column A = identifier, column B = raw fold change, and column C = adjusted p-value. Use this file to run through the below steps.
   3. Run the R code to match identifiers into a single tab-delimited file across platforms, then organize and normalize the data (Supplemental Coding File 2). Instructions are contained within the file. Any FILEPATH will be separated by "/" for MacOS or "//" for Windows (change these from "", as they will appear).
   4. Output the file produced at the end of Supplemental Coding File 2 to a location of choice for use in step 3.1.5. Supplemental Coding File 2 will output a new Fold_Changes.txt file. Back up the original file.
   5. Execute the code contained in Supplementary coding File 3. Find the output file named FC_distribPlot.png in the folder specified as FILEPATH. Check the distributions of log₂ fold change to verify that the log₂ fold change distributions are nearly identical across datasets.
   6. Follow instructions from step 2.2.6 to edit additional files and ensure compatibility of the new Fold_Changes.txt.
2. Modifying IR-TEx for use with completely new datasets
   1. Open IR-TEx.R in RStudio and locate the lines (23–34) beginning with:
      'tabPanel('
      and ending in:
      submitButton("Update View", icon("refresh"))
      ),
   2. Change the AGAP008212-RA found in the below lines to a transcript of interest in the new data.
      textInput('textInput','Transcript ID',value='AGAP008212-RA'),
   3. Locate the four options beginning with:
      checkboxGroupInput(
      These options can be modified to represent important metadata that the user wishes to filter the new data by. In each instance, the user should change the Select Relevant Countries; Select Exposure Status; Select Relevant Species; and Select Insecticide Class to be representative of the data (i.e., Select Tissue Type; Select Sex; Select Age Bracket; Select Disease Status).
   4. Identify the metadata associated with the dataset and input to replace the existing options immediately after the first c('. In each instance, the options will be contained within speech marks and separated from the next selection by a comma. After the final selection, the bracket should be closed. An example for Select Disease Status is:
      c('Infected', 'Uninfected', 'Unknown')
   5. Choose which of these metadata will be selected upon opening the app. These can be changed by modifying the options after selected=c('. An example for Select Disease Status is:
      selected=c('Infected', 'Uninfected')
      This will instruct the app to select only datasets matching these criteria on initial loading.
   6. To create a new data table, follow the layout found in Fold_Changes.txt and instructions in section 2. Change the metadata to each respective change outlined in step 3.2.4, exactly as written into the code (R is case-sensitive). Into the detoxification column, input gene names, and in the transcript type column, input gene descriptions for each transcript. Follow section 3.2 when adding new datasets.
   7. If mapping is not relevant to the experimental requirements, locate the following lines of code and place '#' in front:
      Lines 49–51:
      br(),br(),
      withSpinner(plotOutput("Geography")),
      textOutput('Geography_legend'),
      Lines 493 starting:
      output$Geography <- renderPlot({
      To line 602 ending:
      output$Geography_legend <- renderText({
      paste("Significant Transcripts Only (p", as.expression("<="),"0.05): FC > 5 = Red, FC > 1 = Amber, FC < 1 = Green",sep="")
      })