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

Electronic appendix to the Technical Report 194, Department of Statistics, LMU:

Improving cross-study prediction through addon batch effect adjustment 
and addon normalization

Roman Hornung*, David Causeur, Christoph Bernau, Anne-Laure Boulesteix

* Department of Medical Informatics, Biometry and Epidemiology,
  University of Munich, Marchioninistr. 15, D-81377, Munich, Germany;
  for questions please contact:  hornung@ibe.med.uni-muenchen.de

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


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

- Program: R, version 3.1.0

- Used R packages:

     'bapred', version: 1.0
     'ggplot2', version: 2.1.0
     'gridExtra', version: 2.2.1
     'plyr', version: 1.8.3
     'snow', version: 0.4-1
     'snowfall', version: 1.84-6.1

  Used Bioconductor packages:  

     'affy', version: 1.32.0
     'ArrayExpress', version: 1.24.0
     'CMA', version: 1.30.0
  
  NOTE: Packages listed above depend on others, which might have to be installed
        manually in case this is not performed automatically.

- Platform: Linux (x86-64)




General information:
####################

- The folder "ICSVCodeData" this README is contained in has to be put into the 
  home directory ("~/") of a Linux machine.
  We use paths of the form "./ICSVCodeData/...".
  Note: Evaluating the results (see below) can also be performed under Windows.
  The retrieval of the datasets and the reproduction of the analysis - which is
  performed in parallel - requires Linux.

- The following subfolders are found in "ICSVCodeData":

  - "Results": the results of the large data study in the form of Rda-files
    and the plots produced in the evaluation and included in the Supplementary 
    Materials

  - "Functions": R-script "FunctionsForClusters.R" with functions used in the 
    large data study

  - "InterimResults": empty; used in the analyses to store intermediate
    files not part of the final results.

  - "JobScripts": R-scripts which perform the large data study

  - "Datasets": empty; this folder will contain the raw data and
    the data after normalization and, for each training/test set pair,
    the addon normalized test datasets.

  - "DataRetrieval": R-script "DataRetrieval.R" performs the retrieval
    of the datasets used in the analysis, most importantly the removal of repeated
    measurements. The sub-folder "sdrffiles" contains Rda-files which
    contain data.frames giving the meta-information on the datasets
    after removal of repeated measurements. Additionally the sdrf-file
    of each dataset is contained here. R-script "DownloadData.R"
    can be used to download the raw data after removal of repeated
    measurements.

  - "EvaluationOfResults": enables the evaluation of the results
    without the need to re-perform the analysis, see below.


  

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

- For the evaluation of the results it is not necessary to re-perform the analyses:
  In the folder "EvaluationOfResults" we provide the R-files "MetainformationOnDatasets.R" 
  and "LargeDataStudy.R". "MetainformationOnDatasets.R" produces Table S1 presented
  in the Supplementary Materials. "LargeDataStudy.R" produces all other empirical results 
  presented or discussed in the paper and in the Supplementary Materials.




Reproducing the results:
########################

Prerequisites:
##############

- An MPI-environment is required.

- With the exception of "DownloadData.R" (folder "DataRetrieval") all parallel 
  computations require that the content of "RprofileSNOWFALL", found in the folder
  this README-file is contained in, is used as the  .Rprofile-file loaded at the 
  start of every R session. To facilitate this, the content of "RprofileSNOWFALL" is
  copied into a file designated as ".Rprofile" which is to be put into the
  home directory of R (in Linux, put "RprofileSNOWFALL" into the home directory and
  use "cp ~/RprofileSNOWFALL ~/.Rprofile").


Datasets:
#########

- Because of the sizes of the raw datasets, we could not include them into
  the Electronic Appendix. However, as already noted above, they can be
  obtained by "DownloadData.R" in the folder "DataRetrieval".


Large Data Study:
#################

- All R-scripts to perform the large data study are contained in the 
  folder "JobScripts".

- At first, normalization is performed by "NormalizationTrainingScript.R".

- Consecutively, addon normalization is performed by "NormalizationAddonScript.R".

- Finally, addon batch effect adjustment and cross-study prediction is performed
  by "LargeDataStudy_1.R", "LargeDataStudy_2.R", "LargeDataStudy_3.R" and 
  "LargeDataStudy_4.R".
