{"id":1643,"date":"2024-05-29T22:32:15","date_gmt":"2024-05-29T20:32:15","guid":{"rendered":"https:\/\/paul-regnier.fr\/?page_id=1643"},"modified":"2026-02-27T15:42:10","modified_gmt":"2026-02-27T14:42:10","slug":"tutoriel-amocati","status":"publish","type":"page","link":"https:\/\/paul-regnier.fr\/en_gb\/tutoriel-amocati\/","title":{"rendered":"Tutoriel AMOCATI"},"content":{"rendered":"

AMOCATI: Algorithmic Meta-analysis Of Clinical And Transcriptomic Information<\/strong><\/p>\n\n\n\n

Warning: this tutorial is only available in English, even if you choose the French language at the bottom of the screen. Thank you for your understanding<\/strong>.<\/strong><\/p>\n\n\n\n

AMOCATI<\/code> is a R-written package which aims to analyze transcriptome-based datasets, and more specifically quantify how a given gene and\/or gene signature impacts the overall survival of patients. For the sake of convenience, AMOCATI<\/code> allows to flawlessly download data from the Genomic Data Commons (GDC) repository, and more precisely cancer datasets from TCGA, TARGET and CGCI projects.<\/p>\n\n\n\n

Table of contents<\/strong><\/h2>\n\n\n\n
    \n
  1. Prerequisites<\/a>\n
      \n
    1. Publication<\/a><\/li>\n\n\n\n
    2. R environment introduction and installation<\/a><\/li>\n\n\n\n
    3. AMOCATI R package installation and update<\/a><\/li>\n\n\n\n
    4. Load AMOCATI<\/a><\/li>\n<\/ol>\n<\/li>\n\n\n\n
    5. Workspace directory setup<\/a><\/li>\n\n\n\n
    6. Download and process a dataset of interest<\/a><\/li>\n\n\n\n
    7. Launch the metaResults analysis<\/a><\/li>\n\n\n\n
    8. Extract the Classification Signature<\/a><\/li>\n\n\n\n
    9. Compute patient-wise the Quantitative Scores and Clinical Scores of the Classification Signature<\/a><\/li>\n\n\n\n
    10. Separate the patients of the cohort according to the Quantitative Score or the Clinical Score of the Classification Signature<\/a><\/li>\n\n\n\n
    11. Use of custom gene signatures instead of the Classification Signature<\/a><\/li>\n\n\n\n
    12. Adding distinguishing genes as a new layer of complexity for custom signatures<\/a><\/li>\n\n\n\n
    13. Further analyses<\/a><\/li>\n\n\n\n
    14. Miscellaneous<\/a><\/li>\n\n\n\n
    15. Citation<\/a><\/li>\n<\/ol>\n\n\n\n

      1) Prerequisites<\/strong><\/h2>\n\n\n\n

      1.1) Publication<\/strong><\/h3>\n\n\n\n

      Before using AMOCATI<\/code>, we greatly encourage users to carefully read our associated publication. The methodology behind AMOCATI<\/code> can be rather complex to understand at first sight, but we tried our best to make it as clear as possible. The manuscript and its associated supplemental resources will help users to understand how AMOCATI<\/code> works, what are the main steps of its workflow and how to apply it in real-life datasets to treat a biological question.<\/p>\n\n\n\n

      1.2) R environment introduction and installation<\/strong><\/h3>\n\n\n\n

      To make the installation of R programming language and RStudio development software easier for new or beginner users, we highly recommend the following ressource, entitled \u00ab\u00a0YaRrr! The Pirate’s Guide to R\u00a0\u00bb<\/a>. New users should at least read the first (\u00ab\u00a0Preface\u00a0\u00bb) and second (\u00ab\u00a0Getting Started\u00a0\u00bb) sections, as they provide clear and straightforward instructions on how to setup R and RStudio on Windows and MacOS operating systems. These sections will allow users to correctly install AMOCATI<\/code> and launch it flawlessly.<\/p>\n\n\n\n

      1.3) AMOCATI R package installation and update<\/strong><\/h3>\n\n\n\n

      AMOCATI<\/code> package can be installed with the following command:<\/p>\n\n\n\n

      # The following line can be skipped if the devtools package is already installed\n<\/em>\ninstall.packages(<\/strong>\"devtools\")<\/strong>\n\n# Load the devtools package\n<\/em>\nlibrary(<\/strong>\"devtools\")<\/strong>\n\n# Install AMOCATI from GitHub repository\n<\/em>\ndevtools::install_github(<\/strong>\"PaulRegnier\/AMOCATI\", build_vignettes = TRUE)<\/strong>\n\n# Update AMOCATI from GitHub repository\n<\/em>\ndevtools::install_github(<\/strong>\"PaulRegnier\/AMOCATI\", build_vignettes = TRUE, force = TRUE)<\/strong><\/code><\/pre>\n\n\n\n
      1.4) Load AMOCATI<\/strong><\/h3>\n\n\n\n
      To load AMOCATI<\/code>, simply enter the following command in the R console:<\/p>\n\n\n\n
      library(<\/strong>\"AMOCATI\")<\/strong><\/code><\/pre>\n\n\n\n
      2) Workspace directory setup<\/strong><\/h2>\n\n\n\n
      Before launching the actual analysis, users need to select and setup their working directory, which AMOCATI<\/code> will use throughout its workflow:<\/p>\n\n\n\n
      # Select the right working directory\n<\/em>\nworkingDirectory = file.path(<\/strong>\"YOUR\", \"PATH\", \"HERE\")<\/strong>\nsetwd(<\/strong>workingDirectory)<\/strong>\n\n# Construct the actual workspace\n<\/em>\nresetWorkspace(<\/strong>\n    eraseEntireRMemory<\/strong> = FALSE,\n    verbose<\/strong> = TRUE\n)<\/strong><\/code><\/pre>\n\n\n\n
      This function will create a set of folders and subfolders in which different files will be written throughout the AMOCATI<\/code> workflow.<\/p>\n\n\n\n
      3) Download and process a dataset of interest<\/strong><\/h2>\n\n\n\n
      First, users should determine which dataset should be analyzed. For the sake of convenience, AMOCATI<\/code> allows users to directly download cancer datasets coming from the GDC repository (and notably TCGA, TARGET and CGCI projects).<\/p>\n\n\n\n
      If you want to use such dataset, please run the following command to access the available datasets to download:<\/p>\n\n\n\n
      # List projects and associated parameters\n<\/em>\nlistProjectsAttributes()<\/strong><\/code><\/pre>\n\n\n\n
      This will output something similar to:<\/p>\n\n\n\n
                ProjectID                                                                   ProjectName\n1     CGCI-HTMCP-CC               HIV+ Tumor Molecular Characterization Project - Cervical Cancer\n2  CGCI-HTMCP-DLBCL HIV+ Tumor Molecular Characterization Project - Diffuse Large B-Cell Lymphoma\n3     CGCI-HTMCP-LC                   HIV+ Tumor Molecular Characterization Project - Lung Cancer\n4     TARGET-ALL-P1                                        Acute Lymphoblastic Leukemia - Phase I\n5     TARGET-ALL-P2                                       Acute Lymphoblastic Leukemia - Phase II\n6     TARGET-ALL-P3                                      Acute Lymphoblastic Leukemia - Phase III\n7        TARGET-AML                                                        Acute Myeloid Leukemia\n8       TARGET-CCSK                                              Clear Cell Sarcoma of the Kidney\n9        TARGET-NBL                                                                 Neuroblastoma\n10        TARGET-OS                                                                  Osteosarcoma\n11        TARGET-RT                                                                Rhabdoid Tumor\n12        TARGET-WT                                                         High-Risk Wilms Tumor\n13         TCGA-ACC                                                      Adrenocortical Carcinoma\n14        TCGA-BLCA                                                  Bladder Urothelial Carcinoma\n15        TCGA-BRCA                                                     Breast Invasive Carcinoma\n16        TCGA-CESC              Cervical Squamous Cell Carcinoma and Endocervical Adenocarcinoma\n17        TCGA-CHOL                                                            Cholangiocarcinoma\n18        TCGA-COAD                                                          Colon Adenocarcinoma\n19        TCGA-DLBC                               Lymphoid Neoplasm Diffuse Large B-cell Lymphoma\n20        TCGA-ESCA                                                          Esophageal Carcinoma\n21         TCGA-GBM                                                       Glioblastoma Multiforme\n22        TCGA-HNSC                                         Head and Neck Squamous Cell Carcinoma\n23        TCGA-KICH                                                            Kidney Chromophobe\n24        TCGA-KIRC                                             Kidney Renal Clear Cell Carcinoma\n25        TCGA-KIRP                                         Kidney Renal Papillary Cell Carcinoma\n26        TCGA-LAML                                                        Acute Myeloid Leukemia\n27         TCGA-LGG                                                      Brain Lower Grade Glioma\n28        TCGA-LIHC                                                Liver Hepatocellular Carcinoma\n29        TCGA-LUAD                                                           Lung Adenocarcinoma\n30        TCGA-LUSC                                                  Lung Squamous Cell Carcinoma\n31        TCGA-MESO                                                                  Mesothelioma\n32          TCGA-OV                                             Ovarian Serous Cystadenocarcinoma\n33        TCGA-PAAD                                                     Pancreatic Adenocarcinoma\n34        TCGA-PCPG                                            Pheochromocytoma and Paraganglioma\n35        TCGA-PRAD                                                       Prostate Adenocarcinoma\n36        TCGA-READ                                                         Rectum Adenocarcinoma\n37        TCGA-SARC                                                                       Sarcoma\n38        TCGA-SKCM                                                       Skin Cutaneous Melanoma\n39        TCGA-STAD                                                        Stomach Adenocarcinoma\n40        TCGA-TGCT                                                   Testicular Germ Cell Tumors\n41        TCGA-THCA                                                             Thyroid Carcinoma\n42        TCGA-THYM                                                                       Thymoma\n43        TCGA-UCEC                                          Uterine Corpus Endometrial Carcinoma\n44         TCGA-UCS                                                        Uterine Carcinosarcoma\n45         TCGA-UVM                                                                Uveal Melanoma<\/pre>\n\n\n\n
      Of note, if users want to download a TCGA or a CGCI dataset, then they must use the dedicated TCGA_CGCI.download()<\/code>, TCGA_CGCI.createMetaMapping()<\/code> and TCGA_CGCI.pool()<\/code> functions as described below. On the contrary, if users rather want to use a TARGET dataset, they must use the TARGET.download()<\/code>, TARGET.createMetaMapping()<\/code> and TARGET.pool()<\/code> functions.<\/strong><\/p>\n\n\n\n
      For the rest of this tutorial, we will use the cholangiocarcinoma dataset from the TCGA project (ProjectID = TCGA-CHOL<\/code>).<\/p>\n\n\n\n
      # Download the associated RNA-Seq and clinical data\n<\/em>\nTCGA_CGCI.download(projectID<\/strong> = \"TCGA-CHOL\")<\/strong>\n\n# Create a metamapping file which links RNA-Seq and clinical data to the right patients\n<\/em>\nTCGA_CGCI.createMetaMapping(verbose<\/strong> = TRUE)<\/strong>\n\n# Finally pool, process and export data in an all-in-one file\n<\/em>\nTCGA_CGCI.pool(verbose<\/strong> = TRUE)<\/strong><\/code><\/pre>\n\n\n\n
      Because of their dependence to the GDC API, the TCGA_CGCI.download()<\/strong><\/code> and TARGET.download()<\/code><\/strong> functions could potentially stop during the downloading and thus throw errors. In this case, do not hesitate to run the command again, as we implemented a mechanism inside to prevent the redownloading of already downloaded files (both for RNA-Seq and clinical data).<\/p>\n\n\n\n
      Indeed, users always have the possibility to use their own dataset, as long as it follows the correct format (see the Figure 1<\/code> below): the fullData.data<\/code> file (located in the output > data<\/code> folder) should be a tabulation-delimited plain text file, where the 1st<\/sup> column is entitled CaseUUID<\/code> and lists all the unique identifiers for each patient, the 2nd<\/sup> column is entitled vitalStatus<\/code> and lists the vital status of each patient (either Alive<\/code> or Dead<\/code>), the 3rd<\/sup> column is entitled survivedDays<\/code> and lists the number of days survived after the diagnosis, and the subsequent columns list the expression values for each gene (HGNC format) of the transcriptome.<\/strong><\/p>\n\n\n
      \n
      \"\"\n\t\t\t\n\t\t\t\t\n\t\t\t<\/svg>\n\t\t<\/button><\/figure>\n<\/div>\n\n\n
      Figure 1 – File format to respect for AMOCATI<\/code> data (click on the image to open in fullscreen).<\/strong><\/p>\n\n\n\n
      Importantly, users can also use datasets unrelated to cancer if they wish to. The only important criteria is that the data should represent measurable features (one per column) for patients (one per line) with survival\/relapse\/event information (2nd<\/sup> and 3rd<\/sup> column). Alive<\/code> and Dead<\/code> values for the vitalStatus<\/code> column could easily be translated to code any other event type (although the column name nor the words Alive<\/code> or Dead<\/code> should be changed for the sake of compatibility with AMOCATI<\/code>).<\/p>\n\n\n\n
      4) Launch the metaResults analysis<\/strong><\/h2>\n\n\n\n
      Then, the next step is to compute the metaResults<\/code> associated with this dataset. In a few words, this function randomly samples the dataset a given number of times (bootstrapping approach) and then computes, summarizes and outputs different metrics for each gene allowing to estimate and classify its impact on the overall survival of patients (see publication for more details about the algorithm as well as for a graphical representation of what it actually does):<\/p>\n\n\n\n
      createMetaResults(<\/strong>\n    selectedGenesOnly<\/strong> = FALSE,\n    verbose<\/strong> = TRUE,\n    signaturesMode<\/strong> = FALSE,\n    minNumberOfPatientsPerGroup<\/strong> = 3,\n    unsollicitedCores<\/strong> = 2,\n    iterationsPerCluster<\/strong> = 16,\n    genesCutoff<\/strong> = 20\n)<\/strong><\/code><\/pre>\n\n\n\n
      Of note, this step can be long to complete and can be rather computing intensive. So please set the number of unsollicitedCores<\/code> to a reasonable value (RAM requirements can be important).<\/strong><\/p>\n\n\n\n
      This function outputs a tabulation-delimited text file named metaResults.meta<\/code> and located in the output > metaResults<\/code> folder.<\/p>\n\n\n\n
      If desired, this analysis can be performed only on a given selection of genes, in order to drastically reduce the computation time. To this, users can provide a list of genes to use through the selectedGenesOnly = TRUE<\/code> argument. In this case, the output metaResults analysis will be named metaResults_selectedGenes.meta<\/code> and will be located in the output > metaResults<\/code> folder, as previously described. Additionally, this mode of analysis will also generate other results, and notably a selectedGenes.zip<\/code> file contaning the associated survival tables and curves in the output > metaResults > selectedGenes<\/code> folder. Please note that the tabulation-delimited text file containing the selected gene(s) to use should follow a precise format, although its name can be whatever the users want (*.txt<\/code>): this file should contain a single column table, with the first line named HGNC_GeneSymbol<\/code> and the subsequent ones indicating the actual genes to use. These genes must be in the HGNC format. This file should mandatorily be located in the output > data > input<\/code> folder.<\/p>\n\n\n\n
      5) Extract the Classification Signature<\/strong><\/h2>\n\n\n\n
      Afterwards, users should plot two metrics that are output by the previous createMetaResults()<\/strong> function in order to select the genes that have a great impact on survival coupled with a low variability upon the performed boostrapping iterations.<\/p>\n\n\n\n
      First, users should see the two metrics that will help to delineate the genes that will compose the Classification Signature:<\/p>\n\n\n\n
      getClassificationSignature(<\/strong>\n    GeneScoreThreshold<\/strong> = NULL,\n    Gene_SNR_ExpressionThreshold<\/strong> = NULL,\n    exportSignature<\/strong> = FALSE,\n    verbose<\/strong> = TRUE\n)<\/strong><\/code><\/pre>\n\n\n\n
      After that, users can choose associated thresholds and see how it affects the resulting signature (see the Figure 2<\/strong> below):<\/p>\n\n\n\n
      GS_threshold = 0.5\nSNR_threshold = 2\n\ngetClassificationSignature(<\/strong>\n    GeneScoreThreshold<\/strong> = GS_threshold,\n    Gene_SNR_ExpressionThreshold<\/strong> = SNR_threshold,\n    exportSignature<\/strong> = FALSE,\n    verbose<\/strong> = TRUE\n)<\/strong><\/code><\/pre>\n\n\n
      \n
      \"\"\n\t\t\t\n\t\t\t\t\n\t\t\t<\/svg>\n\t\t<\/button><\/figure>\n<\/div>\n\n\n
      Figure 2 – GeneScoreThreshold<\/code> and Gene_SNR_ExpressionThreshold<\/code> are visually set (click on the image to open in fullscreen).<\/strong><\/p>\n\n\n\n
      When the thresholds are correctly set, users should export the final gene signature:<\/p>\n\n\n\n
      getClassificationSignature(<\/strong>\n    GeneScoreThreshold<\/strong> = GS_threshold,\n    Gene_SNR_ExpressionThreshold<\/strong> = SNR_threshold,\n    exportSignature<\/strong> = TRUE,\n    verbose<\/strong> = TRUE\n)<\/strong><\/code><\/pre>\n\n\n\n
      The subsequent Classification Signature is saved in the output > signatures > classificationSignature.sign<\/code> file, as well as the associated plot in PDF format. *.sign<\/code> files are simply plain text file (tabulation-delimited), where each column represents a gene signature (each gene being in the HGNC format), with a short description in the 1st<\/sup> line. Therefore, several signatures can be aggregated within a single *.sign<\/code> file (see later in this tutorial).<\/p>\n\n\n\n
      6) Compute patient-wise the Quantitative Scores and Clinical Scores of the Classification Signature<\/strong><\/h2>\n\n\n\n
      Then, AMOCATI<\/code> can compute both the Quantitative Score as well as the Clinical Score for the Classification Signature and for each patient, which basically uses the previously-determined Classification Signature and the metaResults.meta<\/code> file:<\/p>\n\n\n\n
      applySignature(<\/strong>\n    signatureUsed<\/strong> = \"classification\",\n    verbose<\/strong> = TRUE\n)<\/strong><\/code><\/pre>\n\n\n\n
      In this setting, the applySignature()<\/strong><\/code> function outputs a *.apply<\/code> file in the output > apply<\/code> folder. This tabulation-delimited text file contains the Quantitative Scores and the Clinical Scores for the Classification Signature for each patient.<\/p>\n\n\n\n
      7) Separate the patients of the cohort according to the Quantitative Score or the Clinical Score of the Classification Signature<\/strong><\/h2>\n\n\n\n
      Next, we can separate the patients of the cohort according to their previously computed Clinical Score for the Classification Signature:<\/p>\n\n\n\n
      separatePatients(<\/strong>\n    applyFileUsed<\/strong> = \"classification\",\n    metricToUse<\/strong> = \"CS\",\n    verbose<\/strong> = TRUE\n)<\/strong><\/code><\/pre>\n\n\n\n
      Basically, this function takes as input the previously generated *.apply file as well as the metaResults.meta<\/code> file.<\/p>\n\n\n\n
      If desired, users can also use the Quantitative Score to attempt to separate the patients of the cohort, although this generally leads to a poor separation of patients:<\/p>\n\n\n\n
      separatePatients(<\/strong>\n    applyFileUsed<\/strong> = \"classification\",\n    metricToUse<\/strong> = \"QS\",\n    verbose<\/strong> = TRUE\n)<\/strong><\/code><\/pre>\n\n\n\n
      The aim of this function is to separate patients into 2 groups: the ones with the highest values (called Long-Term Survivors if the Clinical Score is used) and the ones with the lowest values (called Short-Term Survivors if the Clinical Score is used). Please read the publication for the full details.<\/p>\n\n\n\n
      This function outputs several files in the output > class > classificationSignature<\/code> folder: PDF files containing the ROC curve as well as the survival curves, a tabulation-delimited *.class<\/code> file which is basically a *.apply<\/code> file with a supplemental column indicated in which group (LTS or STS) each patient is, and several tabulation-delimited text files with different information and statistics about the two generated groups, the ROC curves, etc.<\/p>\n\n\n\n
      8) Use of custom gene signatures instead of the Classification Signature<\/strong><\/h2>\n\n\n\n
      If desired, users have the possiblity to use their own custom gene signatures instead of the determined Classification Signature. The process to follow is exactly the same as for the steps 6) and 7), except that all the signatures of interest should be written in the output > signatures > customSignatures.sign<\/code> file, which should follow the same file format as previously described for the classificationSignature.sign<\/code> file:<\/p>\n\n\n\n
      # Compute the Clinical Scores and the Quantitative Scores for each custom gene signatures and for each patient\n<\/em>\napplySignature(<\/strong>\n    signatureUsed<\/strong> = \"custom\",\n    verbose<\/strong> = TRUE\n)<\/strong><\/code><\/pre>\n\n\n\n
      Technically, in this context, this function performs exactly the same tasks as in the step 6), but organizes the results in different output folders: output > customSignatures > fullTables<\/code> for the *.apply<\/code> files as previously described and output > customSignatures > synthesis<\/code> for a tabulation-delimited text file which contains the Pearson’s and Spearman’s coefficient of correlation as well as their associated p-values and the coefficient determined for a linear regression between the Quantitative Scores and Clinical Scores for each custom signature. This will help users to determine if their own gene signatures (which one(s) and with which magnitude) is positively or negatively associated with survival.<\/p>\n\n\n\n
      # Use the Clinical Scores obtained for each of the custom signatures to separate the patients of the cohort\n<\/em>\nseparatePatients(\n<\/strong>    applyFileUsed<\/strong> = \"custom\",\n    metricToUse<\/strong> = \"CS\",\n    verbose<\/strong> = TRUE\n)<\/strong><\/code><\/pre>\n\n\n\n
      This function also performs exactly as the one mentioned in the step 7), but instead creates in the output > class<\/code> folder one subdirectory per custom signature.<\/p>\n\n\n\n
      9) Adding distinguishing genes as a new layer of complexity for custom signatures<\/strong> <\/strong><\/h2>\n\n\n\n
      If desired, users have the possiblity to use one or several distinguishing gene(s) during the computation of the Clinical Score and Quantitative Score as well as during the patients separation. Briefly, a distinguishing gene is a given gene for which users want to deeper stratify the impact of the gene signatures on the overall survival (only for the custom signatures). This will simply add a new column in the resulting tables which will allow users to better see if a low, intermediate or high expression actually impacts the survival. The process is exactly the same as for the steps 6), 7) and 8):<\/p>\n\n\n\n
      # Compute the Clinical Score and the Quantitative Score on the custom gene signatures using one or more gene(s) as distinguishing gene(s)\n<\/em>\napplySignature(<\/strong>\n    signatureUsed<\/strong> = \"custom\",\n    distinguishingGenes<\/strong> = TRUE,\n    verbose<\/strong> = TRUE\n)<\/strong><\/code><\/pre>\n\n\n\n
      Please note that the tabulation-delimited text file containing the distinguishing gene(s) to use should follow a precise format, although its name can be whatever the users want (*.txt<\/code>): this file should contain a single column table, with the first line named HGNC_GeneSymbol<\/code> and the subsequent ones indicating the actual genes to use. These genes must be in the HGNC format. This file should mandatorily be located in the output > apply > input<\/code> folder. <\/strong><\/p>\n\n\n\n
      This functions also performs similar computations as compared to the ones presented in the step 8), but outputs more results that are ordered in supplementary folders:<\/p>\n\n\n\n