In compbiomed/TBSignatureProfiler: Profile RNA-Seq Data Using TB Pathway Signatures

Introduction

This tutorial serves as a step-by-step walkthrough to add signatures by performing the necessary data object updates, updating the publication information in the signature list documentation, and then pulling in the updated package into the official version in the wejlab repository.

There are basically four steps to adding a TB gene signature to the TBSignatureProfiler:

1) Collecting information from the publication source of the signature

2) Updating the data objects with the new signature

3) Adding the signature to the appropriate documentation

4) Submitting a pull request to the BUMC Division of Computational Biomedicine's (wejlab) GitHub repository where the package is located.

To illustrate the process of adding signatures, we will use a simple 3-transcript signature published in 2015 by Laux da Costa et al as an example.

Adding multiple signatures

If you need to add more than one signature, note that you will need to repeat the steps of this vignette for each signature. Be sure to use devtools::load_all() before updating the data objects for each subsequent signature.

Setup

Please be sure to download the latest version of the TBSignatureProfiler from GitHub onto your local machine. Navigate to that folder and set it as your working directory. We will use devtools to load the package.

library(knitr)

if (!requireNamespace("devtools", quietly = TRUE))
  install.packages("devtools")

devtools::load_all()

Gathering Information

The first step in this process is gathering the necessary information about the signature(s) that you would like to add. For each signature, you will need to access the signature's associated publication, and make a note (a table will be helpful) of these crucial pieces of information:

What to collect

The gene transcripts composing the signature

Currently, all signatures in the package are stored using gene symbols (not Entrez or Ensembl IDs, although these may be implemented in the future). The gene symbols composing a signature are usually either listed in the body of the article, printed in a figure, or available as a table in the supplementary materials. Sometimes the symbols aren't readily available - in which case, you can try to contact the author to obtain them.

The name of the first author listed

Take note of the last name of the first author listed - this will be used in naming the signature according to package naming standards.

Disease context

We need to know what the signature is intended to discriminate against. The signature type indicates whether the signature was developed to distinguish TB from LTBI ("Disease"), TB from some combination of other diseases and possibly LTBI ("Disease/Other Diseases"), TB from Human Immunodeficiency Virus ("Disease/HIV"), TB from pneumonia ("Disease/Pneumonia"), or identify risk of progression to TB ("risk"), risk of TB treatment failure ("failure"), or classify treatment responses (i.e., failures from cures, "response"). Whatever the designation, please record it as listed in parentheses above (i.e., "risk", "Disease/Other Diseases"). Note that these designations are case sensitive when we store them in the signature annotation object in the package. More details on this will be explained later in the tutorial.

Tissue type

The tissue type variable denotes whether the signature was developed using samples of either whole blood/paxgene or peripheral blood mononuclear cells (PBMCs). Due to the manipulation of cells inherently required to obtain PBMCs, many scientists prefer to use only whole blood samples for analysis. Also, note that "peripheral blood" without the peripheral blood mononuclear cell designation usually refers to whole blood, so be sure to record it correctly. If you are unsure what the tissue type is, get a second opinion to ensure correctness. Record this variable as "whole blood", "PBMC", or "mixed".

Reference information

Please copy down the citation and the DOI number of the article, to be used in the documentation. Provide the reference in AMA format, if possible.

Assigned publication signature name

Sometimes, but not typically, authors name their signatures in originating publication (or that of a peer). If this is the case, take note of this common name. We will use this name in the package alongside a name that we develop according to our own nomenclature system for convenience. Examples of alternative names include RISK6, PREDICT29, and ACS_COR.

If any details cannot be clearly determined

At this point, you should have recorded all of the necessary information. If you are missing any of the pieces of information listed above, then you will not be able to add the signature at this time. If you have any concerns about recording the correct information, you can reach out to the package maintainer, Aubrey Odom, at [e-mail].

Information table for Laux da Costa signature

As mentioned before, a table will be useful for keeping track, especially if you plan to use this vignette to update the profiler with multiple signatures. Below is a table of information collected for the Laux da Costa signature.

info <- matrix(c("Gene Transcripts", "GBP5, CD64, GZMA",
         "Author Name", "Laux da Costa",
         "Disease Context", "Disease/Other Diseases",
         "Tissue Type", "whole blood",
         "Alternate Name", "N/A",
         "Reference", "Laux da Costa L, Delcroix M, Dalla Costa ER, et al. A real-time PCR signature to discriminate between tuberculosis and other pulmonary diseases. Tuberculosis (Edinb). 2015;95(4):421-425.",
         "DOI Number", "10.1016/j.tube.2015.04.008"),
         ncol = 2, byrow = TRUE,
         dimnames = list(c(), c("Item Needed", "Signature Information")))
kable(info)

Updating the data objects

To streamline the process of adding signatures, we have introduced the addTBsignature() function to the package. To use the function, users must access the function by calling the unexported function, TBSignatureProfiler:::addTBsignature(). This function will take as input the various pieces of information listed previously, as well as a few other parameters. It will easily update the package's TBsignatures and TBcommon signature lists, as well as the sigAnnotData and commonAnnotData annotation data tables. After doing so, we will just need to update the documentation for the signature objects and pull in the updates to the repository, and the addition of the signature will be complete. But first, we need to ensure that the data objects can be updated correctly.

From the code below, you should be able to pretty clearly see what needs to be inputted based on the table created above, but if this is unclear, please run ?TBSignatureProfiler:::addTBsignature for more details on the parameters.

The one parameter that we will point out, however, is very important - savobjs. This takes a logical and denotes essentially whether this is a 'test run' or the real thing (i.e., saving all the objects with the new signature). Here, we will first run the function with saveobjs = FALSE. Doing so will not save or overwrite any new object files to the data directory - it will only produce error messages and other progress messages, and (if views = TRUE) invoke a data viewer with View() on each of the objects so we can see what the final objects will look like. Note that the function will never return anything in its output to be saved to the working environment, regardless of what saveobjs is set to, and this is why we produce the data views if nothing is actually being saved to the RDS files in the data directory.

Test run

We will run the function using the information gathered from the Laux da Costa publication (note that spaces should be omitted from the author name):

# Append a 2 since the signature is already in the package
# This is merely for testing
addTBsignature(sigsymbols = c("GBP5", "CD64", "GZMA"),
             authname = "LauxdaCosta2", 
             sigtype = "Disease/Other Diseases",
             tissuetype = "whole blood",
             signame_common = NULL,
             saveobjs = FALSE,
             views = FALSE)

Since this is a vignette, we set views = FALSE, but it will generally be a good thing to keep it set to TRUE to ensure that all goes as planned. This will allow you to peruse the tables/lists and make sure that the signature name looks right, the signatures are all ordered according to alphabetization of package assigned names (TBsignatures ordering is carried over to alternative name objects), and that correct information was entered. Note that the sigAnnotData uses some abbreviations and won't contain exactly the same information that you put in.

Overwriting the RDS files

Assuming there are no glaring errors and everything looks correct, we can run the function again to save and overwrite the currently existing data objects by setting saveobjs = TRUE. Here, we will refrain from running the code as this is merely a vignette, but the same messages will be output, along with a message confirming that the objects were written to the data folder.

addTBsignature(sigsymbols = c("GBP5", "CD64", "GZMA"),
             authname = "LauxdaCosta2",
             signame_common = NULL,
             sigtype = "Disease/Other Diseases",
             tissuetype = "whole blood",
             saveobjs = TRUE,
             views = FALSE)

With that, the data objects themselves should be successfully updated. You can take a look at them by running devtools::load_all() to update your local repository and then loading the data objects as data("TBsignatures) or data(common_sigAnnotObject).

In the case that you wrote to the RDS files by accident and need to fix them, redownload the appropriate files from the GitHub repository and try again. Be sure to rerun the devtools::load_all() command.

Documentation

The documentation is the only place where the source of the signature will be mentioned in the package; therefore, it is crucial that it be updated accordingly every time a signature is added to the package. Upon adding a signature, the only documentation that needs to be added is that of the list objects, TBsignatures and TBcommon. The table looks a bit messy when viewed raw, but the finished product looks much nicer (you can pull it up with ?TBsignatures or ?Tbcommon).

There is a specific format that needs to be followed for adding an entry, but you can easily create the table entry by using the function provided below. The function only requires that you supply the name of the signature given by addTBsignature(), the reference (minus the DOI, that is a separate parameter), and the DOI number (not the link!).

An example is illustrated below using the LauxdaCosta_OD_3 signature. The file containing documentation should be located in the file R/data.R inside the package file structure.

mkTBreference <- function(TBsigname, ref, DOInum) {
  cat("\\item{\\strong{", TBsigname, "}}{: ", ref,
      " \\href{http://dx.doi.org/", DOInum, "}{", DOInum, "}}", sep = "")
}

mkTBreference(TBsigname = "LauxdaCosta2_OD_3", # The name output in a message from addTBsignature()
              ref = "Laux da Costa L, Delcroix M, Dalla Costa ER, et al. A real-time PCR signature to discriminate between tuberculosis and other pulmonary diseases. Tuberculosis (Edinb). 2015;95(4):421-425.",
              DOInum = "10.1016/j.tube.2015.04.008")

In the case that an alternative publication signature name exists, mkTBreference will need to be rerun with the alternative name as the TBsigname argument, for use with the TBcommon documentation table. Otherwise, the package assigned signature name can be used for both TBcommon and TBsignatures entries.

Once you have you have the requisite entries, open up data/data.R. First, find the table for TBsignatures, and insert the entry (with the #' at the beginning like all other entries) at the appropriate position. All signatures should have the same position in the table as they do when you look at ordering of the names of the TBsignatures object (names(TBsignatures)). Once this is complete, do the same to the TBcommon table, which should be a little further down on the page.

Please make sure to compile the documentation by running devtools::document() upon completion of your documentation edits.

Pull in your changes to the repository

The very last step of this process will be to submit a pull request to the GitHub repository. If you have never submitted a pull request to another repo before, instructions can be found here. When you are submitting your request, please note which signature(s) you added by name and what publications they can be found in, so that we can check that the update was completed successfully. We will try to approve pull requests as soon as possible. After the request is approved, your signature will be part of the package. Thank you for your contribution!

Session Information

sessionInfo()

compbiomed/TBSignatureProfiler documentation built on April 9, 2024, 10:46 p.m.