####################################################################################################

Supplementary Material 2 - Electronic Appendix to the paper "Block Forests: random forests for blocks of
clinical and omics covariate data"

Roman Hornung 1,  Marvin N. Wright 2,3

1 Institute for Medical Information Processing, Biometry and Epidemiology, 
  University of Munich, Marchioninistr. 15, 81377 Munich, Germany;
  for questions please contact:  hornung@ibe.med.uni-muenchen.de

2 Leibniz Institute for Prevention Research and Epidemiology - BIPS, Achterstr. 30,
  28359 Bremen, Germany

3 Section of Biostatistics, Department of Public Health, University of Copenhagen, 
  ster Farimagsgade 5, 1014 Copenhagen, Denmark

####################################################################################################



Program and Platform:
#####################

- Program: R, version 3.5.0

- Used R packages:

     'blockForest', version: 0.1.5
     'DMwR', version: 0.4.1
     'ggplot2', version: 3.1.0
     'gridExtra', version: 2.3
     'nnet', version: 7.3-12
     'plyr', version: 1.8.4
     'ranger', version: 0.10.1
     'RColorBrewer', version: 1.1-2
     'Rmpi', version: 0.6-9
     'snow', version: 0.4-3
     'survival', version: 2.42-3

  Used Bioconductor packages:

     'edgeR', version: 3.24.1
     'survcomp', version: 1.32.0
     'limma', version: 3.38.3
     'SummarizedExperiment', version: 1.12.0
     'TCGAbiolinks', version: 2.10.0

- Platforms: Linux (x86-64)  (for the conduction of the analyses)
             Windows 7 64-bit (for the evaluation of the results)



General information and contents of the Electronic Appendix:
############################################################

- We provide all R codes used in the analysis. Neverthelesss,
  due to their sizes the pre-processed data sets (downloaded from The Cancer Genome
  Atlas (TCGA) database) cannot be provided in the Electronic Appendix.
  Therefore, the results cannot be reproduced without downloading
  and pre-processing the data sets. Alternatively, the pre-processed
  data sets are available from the corresponding author upon request.

- Paths of the form "./suppmat2_hornungwrighttr/..." are used in all
  R scripts, where "./" is the R working directory. Therefore, the
  folder "suppmat2_hornungwrighttr" this README file is contained in
  is to be put into the R working directory.
  Alternatively, the R working directory can be changed to an
  arbitrary directory that contains the folder "suppmat2_hornungwrighttr".

- The following subfolders are found in "suppmat2_hornungwrighttr":

  - "Data": This subfolder contains three subfolders "Download_FirstPreprocessing",
    "PreprocessingForAnalysis", and "ProcessedData" as well as the
    Rda file "numbercovariates.Rda".

    The subfolder "Download_FirstPreprocessing" contains the R code required
    for downloading the data sets from TCGA and first pre-processing. "Download.R"
    allows to download the data sets and "Build_CNV_Matrices.R", "Build_miRNA_Matrices.R",
    "Build_Mutation_Matrices.R", and "Build_RNA_Matrices.R" perform the
    first pre-processing. The downloaded and pre-processed data sets are
    stored in the corresponding subfolders of "Download_FirstPreprocessing".

    The subfolder "PreprocessingForAnalysis" contains an R script for
    each data set, where each of these R scripts performs the pre-processing of
    the data sets as used in the analysis.

    The subfolder "ProcessedData" is empty. This folder contains the
    pre-processed data sets after executing the R scripts contained in the
    subfolder "PreprocessingForAnalysis" (or after having obtained the
    pre-processed data sets from the corresponding author).

    The file "numbercovariates.Rda" is used in the evaluation of
    the results (subfolder "Evaluation") and contains the numbers of
    covariates per block and data set.

  - "Evaluation": This subfolder contains three R scripts "Evaluation_AnalysisCluster.R",
    "Evaluation_AnalysisCluster_TwoBlocks.R", and "DataTableInformation.R".
    "Evaluation_AnalysisCluster.R" was used to produce all results of the analysis
    of the multi-omics data. "Evaluation_AnalysisCluster_TwoBlocks.R"
    was used to produce all results of the analysis of the two-blocks case, that is, having
    clinical covariates plus RNA measurements available. These R scripts also
    contain the R code used to produce the figures. "DataTableInformation.R" was used
    to obtain the information on the data sets shown in Table 1 in the paper
    and in Table S1 in Supplementary Material 1.

  - "Figures": This subfolder contains all figures presented in the paper
    and in Supplementary Material 1 and were produced with the R scripts
    "Evaluation_AnalysisCluster.R" and "Evaluation_AnalysisCluster_TwoBlocks.R"
    (see subfolder "Evaluation").

  - "Functions": This folder contains a single R script "Functions_AnalysisCluster.R",
     which contains all functions used in the comparison study. This R script
     is called by the R scripts found in the folder "JobScripts" that perform
    the comparison study.

  - "JobScripts": The folder contains four R scripts "AnalysisCluster_1.R",
    "AnalysisCluster_2.R", "AnalysisCluster_3.R", and "AnalysisCluster_TwoBlocks.R",
    where the former three perform the the analysis of the multi-omics data and
    the latter the analysis of the two-blocks case. All R scripts use parallel computations,
    see Section "Reproducability of the results" below for details.

  - "Results": This folder contains raw results in the form of Rda files.

    The files "scenariogrid1.Rda", "scenariogrid2.Rda", "scenariogrid3.Rda",
    and "scenariogridtwoblocks.Rda" contain the information on the settings
    used in the comparison study, where the former three correspond to
    the multi-omics case and the latter corresponds to the two-blocks case.
    These files were generated by the R scripts contained in the folder
    "JobScripts"; for details, see these R scripts.

    The file "blocknamesavall.Rda" used by "Evaluation_AnalysisCluster.R"
    (see subfolder "Evaluation") contains a list that provides for each data set
    the information on which blocks are available for this data set.

    The files "resultstempsum_multiomics.Rda" and "resultstempsum_twoblocks.Rda"
    (used by "Evaluation_AnalysisCluster.R" and "Evaluation_AnalysisCluster_TwoBlocks.R"
    (see subfolder "Evaluation")) contain data frames that provide the information 
    required for the plots of the differences between the mean C index values 
    obtained using BlockForest and that obtained using RSF against the values of 
    the data set characteristics, where "resultstempsum_multiomics.Rda" provides 
    this information for the multi-omics case and "resultstempsum_twoblocks.Rda" 
    for the two-blocks case.

    The subfolders "Results1", "Results2", "Results3", and "ResultsTwoBlocks"
    contain the raw results of the comparison study, where the former three
    folders correspond to the multi-omics case and the latter corresponds
    to the two-blocks case. These files are used by the R scripts contained
    in the subfolder "Evaluation".



Evaluation of the results:
##########################

- For the evaluation of the results it is not necessary to re-perform the analyses:

  The R scripts "Evaluation_AnalysisCluster.R" and "Evaluation_AnalysisCluster_TwoBlocks.R"
  contained in the subfolder "Evaluation" produce all results of the comparison study 
  without re-performing the analyses by reading in Rda files (stored in the subfolder "Results")
  that contain the raw results.



Reproducability of the results:
##############################

- In principle all R code needed to reproduce the results is available in 
  this electronic appendix. However, reproducing the results is not possible without
  the pre-processed data that is available on request from the corresponding author
  (see above). Nevertheless, by making available all code, the reader can 
  understand all details of the analyses.

- If the pre-processed data sets have been obtained before reproducing
  the results, the folder "suppmat2_hornungwrighttr" this README is contained
  in has to be put into the home directory ("~/") of a Linux machine.

- An MPI environment is required.

- The R scripts "AnalysisCluster_1.R", "AnalysisCluster_2.R", "AnalysisCluster_3.R", 
  and "AnalysisCluster_TwoBlocks.R" (subfolder "JobScripts") perform the
  comparison study in parallel. Before executing these scripts you need to install 
  the RMPISNOW shell script from the installed 'snow' R package or 'inst' directory of 
  the package sources of the 'snow' R package in an appropriate location, preferably
  on your path. 
  See http://homepage.divms.uiowa.edu/~luke/R/cluster/cluster.html (last accessed: 
  18 December 2018) for more details.
  Subsequently, you need to create sh files, each for a different of the
  above R scripts. The following is the content of an example sh file "AnalysisCluster_1.sh":


  #!/bin/bash
  #SBATCH -o /myoutfiledirectory/myjob.%j.%N.out
  #SBATCH -D /myhomedirectory
  #SBATCH -J AnalysisCluster_1 
  #SBATCH --get-user-env 
  #SBATCH --clusters=myclustername
  #SBATCH --nodes=??
  #SBATCH --tasks-per-node=??
  #SBATCH --mail-type=end
  #SBATCH --mail-user=my@mail.de
  #SBATCH --time=??:??:??

  mpirun RMPISNOW < ./suppmat2_hornungwrighttr/JobScripts/AnalysisCluster_1.R


  The above sh-file of course has to be adjusted to be useable (e.g., the "?"s have
  to replaced by actual numbers, the directories have to be adjusted and
  you need to specify your e-mail address; an e-mail will be sent to this address
  once the job is finished).
