How the code is organized
- This directory has the following directory structure at a top level. In the manuscript, we mainly used OLGA-generated data for the simulations, whereas semi-experimental data and immuneML-generated random amino acid data was used for one of the comparison. In the directory structure below, exp refers to semi-experimental, iml refers to immuneML-generated random aa, and olga refers to OLGA-generated.
## .
## ├── exp
## ├── iml
## └── olga
##
## 3 directories
- All the experiments explored in this study have been replicated three times on independent datasets. These are referred to as run_1, run_2, and run_3.
## .
## ├── exp
## │ ├── run_1
## │ ├── run_2
## │ └── run_3
## ├── iml
## │ ├── run_1
## │ ├── run_2
## │ └── run_3
## └── olga
## ├── run_1
## ├── run_2
## └── run_3
##
## 12 directories
- We explored a range of dataset-related or signal-related properties in this manuscript. The code related to each of the explored properties is organized under respective directories with self-explanatory naming of the directories that matches the descriptions in the manuscript.
## .
## ├── exp
## │ ├── run_1
## │ │ └── varying_rep_size
## │ ├── run_2
## │ │ └── varying_rep_size
## │ └── run_3
## │ └── varying_rep_size
## ├── iml
## │ ├── run_1
## │ │ └── varying_rep_size
## │ ├── run_2
## │ │ └── varying_rep_size
## │ └── run_3
## │ └── varying_rep_size
## └── olga
## ├── run_1
## │ ├── dataset_implanting_rate
## │ ├── trained_model_on_unseen_testdata
## │ ├── varying_complex_kmer_size
## │ ├── varying_feature_size
## │ ├── varying_kmer_size
## │ ├── varying_methods
## │ ├── varying_n_kmers
## │ ├── varying_noise
## │ ├── varying_regularization_rate
## │ ├── varying_rep_size
## │ └── varying_sample_size
## ├── run_2
## │ ├── dataset_implanting_rate
## │ ├── trained_model_on_unseen_testdata
## │ ├── varying_complex_kmer_size
## │ ├── varying_feature_size
## │ ├── varying_kmer_size
## │ ├── varying_methods
## │ ├── varying_n_kmers
## │ ├── varying_noise
## │ ├── varying_regularization_rate
## │ ├── varying_rep_size
## │ └── varying_sample_size
## └── run_3
## ├── dataset_implanting_rate
## ├── trained_model_on_unseen_testdata
## ├── varying_complex_kmer_size
## ├── varying_feature_size
## ├── varying_kmer_size
## ├── varying_methods
## ├── varying_n_kmers
## ├── varying_noise
## ├── varying_regularization_rate
## ├── varying_rep_size
## └── varying_sample_size
##
## 51 directories
- Under the directories of each of the explored properties, there are either further categorizations into sub-categories or a directory named
generated_yaml_files. The sub-category directories would also eventually contain a a directory named generated_yaml_files. The generated_yaml_files directory contain two directories simulation_instructions and ml_instructions. These directories contain the YAML specification files to be supplied to immuneML (https://immuneml.uio.no/) to reproduce the findings of this study. At the time of submission, a version of immuneML that can be used to reproduce the findings of this study has been wrapped in this directory to have a frozen version.
## .
## ├── exp
## │ ├── run_1
## │ │ └── varying_rep_size
## │ │ └── seqcount_100000
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── run_2
## │ │ └── varying_rep_size
## │ │ └── seqcount_100000
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ └── run_3
## │ └── varying_rep_size
## │ └── seqcount_100000
## │ └── generated_yaml_files
## │ ├── ml_instructions
## │ └── simulation_instructions
## ├── iml
## │ ├── run_1
## │ │ └── varying_rep_size
## │ │ └── seqcount_100000
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── run_2
## │ │ └── varying_rep_size
## │ │ └── seqcount_100000
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ └── run_3
## │ └── varying_rep_size
## │ └── seqcount_100000
## │ └── generated_yaml_files
## │ ├── ml_instructions
## │ └── simulation_instructions
## └── olga
## ├── run_1
## │ ├── dataset_implanting_rate
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── trained_model_on_unseen_testdata
## │ │ └── run_1_model_on_run_2_data
## │ │ └── dataset_path_filled_files
## │ ├── varying_complex_kmer_size
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── varying_feature_size
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── varying_kmer_size
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── varying_methods
## │ │ ├── rf
## │ │ │ └── generated_yaml_files
## │ │ │ ├── ml_instructions
## │ │ │ └── simulation_instructions
## │ │ ├── svm
## │ │ │ └── generated_yaml_files
## │ │ │ ├── ml_instructions
## │ │ │ └── simulation_instructions
## │ │ ├── testing_rf_params
## │ │ │ └── generated_yaml_files
## │ │ │ ├── ml_instructions
## │ │ │ └── simulation_instructions
## │ │ └── testing_svm_params
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── varying_n_kmers
## │ │ ├── seqcount_1066k
## │ │ │ └── generated_yaml_files
## │ │ │ ├── ml_instructions
## │ │ │ └── simulation_instructions
## │ │ ├── seqcount_133k
## │ │ │ └── generated_yaml_files
## │ │ │ ├── ml_instructions
## │ │ │ └── simulation_instructions
## │ │ ├── seqcount_2133k
## │ │ │ └── generated_yaml_files
## │ │ │ ├── ml_instructions
## │ │ │ └── simulation_instructions
## │ │ ├── seqcount_266k
## │ │ │ └── generated_yaml_files
## │ │ │ ├── ml_instructions
## │ │ │ └── simulation_instructions
## │ │ ├── seqcount_33k
## │ │ │ └── generated_yaml_files
## │ │ │ ├── ml_instructions
## │ │ │ └── simulation_instructions
## │ │ ├── seqcount_533k
## │ │ │ └── generated_yaml_files
## │ │ │ ├── ml_instructions
## │ │ │ └── simulation_instructions
## │ │ └── seqcount_66k
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── varying_noise
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── varying_regularization_rate
## │ │ └── n_kmers_1_64
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── varying_rep_size
## │ │ ├── seqcount_100000
## │ │ │ └── generated_yaml_files
## │ │ │ ├── ml_instructions
## │ │ │ └── simulation_instructions
## │ │ ├── seqcount_12000
## │ │ │ └── generated_yaml_files
## │ │ │ ├── ml_instructions
## │ │ │ └── simulation_instructions
## │ │ ├── seqcount_200000
## │ │ │ └── generated_yaml_files
## │ │ │ ├── ml_instructions
## │ │ │ └── simulation_instructions
## │ │ ├── seqcount_25000
## │ │ │ └── generated_yaml_files
## │ │ │ ├── ml_instructions
## │ │ │ └── simulation_instructions
## │ │ └── seqcount_50000
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ └── varying_sample_size
## │ ├── sample_size_100
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── sample_size_1600
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── sample_size_200
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── sample_size_400
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── sample_size_50
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ └── sample_size_800
## │ └── generated_yaml_files
## │ ├── ml_instructions
## │ └── simulation_instructions
## ├── run_2
## │ ├── dataset_implanting_rate
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── trained_model_on_unseen_testdata
## │ │ └── run_2_model_on_run_3_data
## │ │ └── dataset_path_filled_files
## │ ├── varying_complex_kmer_size
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── varying_feature_size
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── varying_kmer_size
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── varying_methods
## │ │ ├── rf
## │ │ │ └── generated_yaml_files
## │ │ │ ├── ml_instructions
## │ │ │ └── simulation_instructions
## │ │ └── svm
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── varying_n_kmers
## │ │ ├── seqcount_1066k
## │ │ │ └── generated_yaml_files
## │ │ │ ├── ml_instructions
## │ │ │ └── simulation_instructions
## │ │ ├── seqcount_133k
## │ │ │ └── generated_yaml_files
## │ │ │ ├── ml_instructions
## │ │ │ └── simulation_instructions
## │ │ ├── seqcount_2133k
## │ │ │ └── generated_yaml_files
## │ │ │ ├── ml_instructions
## │ │ │ └── simulation_instructions
## │ │ ├── seqcount_266k
## │ │ │ └── generated_yaml_files
## │ │ │ ├── ml_instructions
## │ │ │ └── simulation_instructions
## │ │ ├── seqcount_33k
## │ │ │ └── generated_yaml_files
## │ │ │ ├── ml_instructions
## │ │ │ └── simulation_instructions
## │ │ ├── seqcount_533k
## │ │ │ └── generated_yaml_files
## │ │ │ ├── ml_instructions
## │ │ │ └── simulation_instructions
## │ │ └── seqcount_66k
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── varying_noise
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── varying_regularization_rate
## │ │ └── n_kmers_1_64
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── varying_rep_size
## │ │ ├── seqcount_100000
## │ │ │ └── generated_yaml_files
## │ │ │ ├── ml_instructions
## │ │ │ └── simulation_instructions
## │ │ ├── seqcount_12000
## │ │ │ └── generated_yaml_files
## │ │ │ ├── ml_instructions
## │ │ │ └── simulation_instructions
## │ │ ├── seqcount_200000
## │ │ │ └── generated_yaml_files
## │ │ │ ├── ml_instructions
## │ │ │ └── simulation_instructions
## │ │ ├── seqcount_25000
## │ │ │ └── generated_yaml_files
## │ │ │ ├── ml_instructions
## │ │ │ └── simulation_instructions
## │ │ └── seqcount_50000
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ └── varying_sample_size
## │ ├── sample_size_100
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── sample_size_1600
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── sample_size_200
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── sample_size_400
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── sample_size_50
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ └── sample_size_800
## │ └── generated_yaml_files
## │ ├── ml_instructions
## │ └── simulation_instructions
## └── run_3
## ├── dataset_implanting_rate
## │ └── generated_yaml_files
## │ ├── ml_instructions
## │ └── simulation_instructions
## ├── trained_model_on_unseen_testdata
## │ └── run_3_model_on_run_1_data
## │ └── dataset_path_filled_files
## ├── varying_complex_kmer_size
## │ └── generated_yaml_files
## │ ├── ml_instructions
## │ └── simulation_instructions
## ├── varying_feature_size
## │ └── generated_yaml_files
## │ ├── ml_instructions
## │ └── simulation_instructions
## ├── varying_kmer_size
## │ └── generated_yaml_files
## │ ├── ml_instructions
## │ └── simulation_instructions
## ├── varying_methods
## │ ├── rf
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ └── svm
## │ └── generated_yaml_files
## │ ├── ml_instructions
## │ └── simulation_instructions
## ├── varying_n_kmers
## │ ├── seqcount_1066k
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── seqcount_133k
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── seqcount_2133k
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── seqcount_266k
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── seqcount_33k
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── seqcount_533k
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ └── seqcount_66k
## │ └── generated_yaml_files
## │ ├── ml_instructions
## │ └── simulation_instructions
## ├── varying_noise
## │ └── generated_yaml_files
## │ ├── ml_instructions
## │ └── simulation_instructions
## ├── varying_regularization_rate
## │ └── n_kmers_1_64
## │ └── generated_yaml_files
## │ ├── ml_instructions
## │ └── simulation_instructions
## ├── varying_rep_size
## │ ├── seqcount_100000
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── seqcount_12000
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── seqcount_200000
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ ├── seqcount_25000
## │ │ └── generated_yaml_files
## │ │ ├── ml_instructions
## │ │ └── simulation_instructions
## │ └── seqcount_50000
## │ └── generated_yaml_files
## │ ├── ml_instructions
## │ └── simulation_instructions
## └── varying_sample_size
## ├── sample_size_100
## │ └── generated_yaml_files
## │ ├── ml_instructions
## │ └── simulation_instructions
## ├── sample_size_1600
## │ └── generated_yaml_files
## │ ├── ml_instructions
## │ └── simulation_instructions
## ├── sample_size_200
## │ └── generated_yaml_files
## │ ├── ml_instructions
## │ └── simulation_instructions
## ├── sample_size_400
## │ └── generated_yaml_files
## │ ├── ml_instructions
## │ └── simulation_instructions
## ├── sample_size_50
## │ └── generated_yaml_files
## │ ├── ml_instructions
## │ └── simulation_instructions
## └── sample_size_800
## └── generated_yaml_files
## ├── ml_instructions
## └── simulation_instructions
##
## 386 directories
How to run the YAML specification files to reproduce the results
- See immuneML documentation on how to use the YAML files as input to immuneML (https://immuneml.uio.no/). In this study, in the large majority of the analyses, we simulated disease signal into an AIRR dataset and then trained a ML model on the simulated dataset. This will be achieved through two separate instructions in immuneML. Therefore, each simulation instruction YAML file will have a corresponding ML instruction YAML file and both are run in a sequence, but not in parallel.
- For instance, in the following example, a simulation YAML file is run using immuneML, where the output directory of that instruction is stored under
simulated_data with a sub-directory matching the filename of simulation YAML file. When the simulation instruction execution is successfully completed, the corresponding ML YAML file is run using immuneML, where that YAML file would contain paths to the relevant files from the output directory of simulation instruction. This pattern is followed for all the directories (properties explored in this manuscript).
- Some of the YAML instruction files contain path to a motif file under the argument
motif_filepath. The files to be supplied in such an argument are provided under run_1, run_2, and run_3 directories.
immune-ml olga/run_1/varying_rep_size/seqcount_100000/generated_yaml_files/simulation_instructions/repertoire_implanting_rate__0.002.yaml simulated_data/repertoire_implanting_rate__0.002
immune-ml olga/run_1/varying_rep_size/seqcount_100000/generated_yaml_files/ml_instructions/repertoire_implanting_rate__0.002_-_ml_instruction.yaml ML_Output/repertoire_implanting_rate__0.002
Generation of raw AIRR datasets
- The shell scripts provided under run_1, run_2, and run_3 contain code to generate raw AIRR datasets using OLGA. To freeze the version of OLGA used in this manuscript for the generation of raw datasets, we wrapped and included the
OLGA version that was used. These raw AIRR datasets are used as input for the simulation instructions.
- The generation of datasets or metadata files using the provided shell scripts use some utility functions through command-line. These command-line utilities can be obtained by installing the
utilities_immuneml python package through pip install.