Debian Codegraph @

lib/Genome/Model/Tools/Music/ClinicalCorrelation.pm

raw ◀ ▶
Source reconstructed at patch state 0 of 1 — not the installed (fully patched) source.
1 Debian patch touch this file
1 package Genome::Model::Tools::Music::ClinicalCorrelation;
2
3 use warnings;
4 use strict;
5 use Carp;
6 use Genome;
7 use IO::File;
8 use POSIX qw( WIFEXITED );
9
10 our $VERSION = $Genome::Model::Tools::Music::VERSION;
11
12 class Genome::Model::Tools::Music::ClinicalCorrelation {
13 is => 'Genome::Model::Tools::Music::Base',
14 has_input => [
15 bam_list => {
16 is => 'Text',
17 doc => "Tab delimited list of BAM files [sample_name, normal_bam, tumor_bam] (See Description)",
18 },
19 maf_file => {
20 is => 'Text', is_optional => 1,
21 doc => "List of mutations using TCGA MAF specification v2.3",
22 },
23 output_file => {
24 is_output => 1, is => 'Text',
25 doc => "Results of clinical-correlation tool. Will have suffix added for data type",
26 },
27 clinical_correlation_matrix_file => {
28 is => 'Text', is_optional => 1,
29 doc => "Specify a file to store the sample-vs-gene matrix created during calculations",
30 },
31 input_clinical_correlation_matrix_file => {
32 is => 'Text', is_optional => 1,
33 doc => "Instead of creating this from the MAF, input the sample-vs-gene matrix for calculations",
34 },
35 genetic_data_type => {
36 is => 'Text', is_optional => 1, default => "gene",
37 doc => "Correlate clinical data to \"gene\" or \"variant\" level data",
38 },
39 numeric_clinical_data_file => {
40 is => 'Text', is_optional => 1,
41 doc => "Table of samples (y) vs. numeric clinical data category (x)",
42 },
43 numerical_data_test_method => {
44 is => 'Text', is_optional => 1, default => 'cor',
45 doc => "Either 'cor' for Pearson Correlation or 'wilcox' for the Wilcoxon Rank-Sum Test for numerical clinical data",
46 },
47 categorical_clinical_data_file => {
48 is => 'Text', is_optional => 1,
49 doc => "Table of samples (y) vs. categorical clinical data category (x)",
50 },
51 glm_model_file => {
52 is => 'Text', is_optional => 1,
53 doc => "File outlining the type of model, response variable, covariants, etc. for the GLM analysis. (See DESCRIPTION)",
54 },
55 glm_clinical_data_file => {
56 is => 'Text', is_optional => 1,
57 doc => "Clinical traits, mutational profiles, other mixed clinical data (See DESCRIPTION)",
58 },
59 use_maf_in_glm => {
60 is => 'Boolean', is_optional => 1, default => 0,
61 doc => "Create a variant matrix from the MAF file as variant input to GLM analysis.",
62 },
63 skip_non_coding => {
64 is => 'Boolean', is_optional => 1, default => 1,
65 doc => "Skip non-coding mutations from the provided MAF file",
66 },
67 skip_silent => {
68 is => 'Boolean', is_optional => 1, default => 1,
69 doc => "Skip silent mutations from the provided MAF file",
70 },
71 ],
72 doc => "Correlate phenotypic traits against mutated genes, or against individual variants",
73 };
74
75 sub help_synopsis {
76 return <<HELP
77 ... music clinical-correlation \\
78 --bam-list /path/myBamList.tsv \\
79 --maf-file /path/myMAF.tsv \\
80 --numeric-clinical-data-file /path/myNumericData.tsv \\
81 --genetic-data-type 'gene' \\
82 --output-file /path/output_file
83
84 ... music clinical-correlation \\
85 --maf-file /path/myMAF.tsv \\
86 --bam-list /path/myBamList.tsv \\
87 --numeric-clinical-data-file /path/myNumericData.tsv \\
88 --categorical-clinical-data-file /path/myClassData.tsv \\
89 --genetic-data-type 'gene' \\
90 --output-file /path/output_file
91
92 ... music clinical-correlation \\
93 --maf-file /path/myMAF.tsv \\
94 --bam-list /path/myBamList.tsv \\
95 --output-file /path/output_file \\
96 --glm-model-file /path/model.tsv \\
97 --glm-clinical-data-file /path/glm_clinical_data.tsv \\
98 --use-maf-in-glm
99
100 HELP
101 }
102
103 sub help_detail {
104 return <<HELP
105
106 This command relates clinical traits and mutational data. Either one can perform correlation analysis between mutations recorded in a MAF and the particular phenotypic traits recorded in clinical data files for the same samples, or one can run a generalized linear model (GLM) analysis on the same types of data.
107
108 The clinical data files for correlation must be separated between numeric and categoric data and must follow these
109 conventions:
110
111 =over 4
112
113 =item * Headers are required
114
115 =item * Each file must include at least 1 sample_id column and 1 attribute column, with the format being [sample_id clinical_data_attribute_1 clinical_data_attribute_2 ...]
116
117 =item * The sample ID must match the sample ID listed in the MAF under "Tumor_Sample_Barcode" for relating the mutations of this sample.
118
119 =back
120
121 Note the importance of the headers: the header for each clinical_data_attribute will appear in the
122 output file to denote relationships with the mutation data from the MAF.
123
124 Internally, the input data is fed into an R script which calculates a P-value representing the
125 probability that the correlation seen between the mutations in each gene (or variant) and each
126 phenotype trait are random. Lower P-values indicate lower randomness, or likely true correlations.
127
128 The results are saved to the output filename given with a suffix appended; ".numeric.csv" will be
129 appended for results derived from numeric clinical data, and ".categorical.csv" will be appended for results
130 derived from categorical clinical data. Also, ".glm.csv" will be appended to the output filename for GLM results.
131
132 The GLM analysis accepts a mixed numeric and categoric clinical data file, input using the parameter --glm-clinical-data-file. GLM clinical data must adhere to the formats described above for the correlation clinical data files. GLM also requires the user to input a --glm-model-file. This file requires specific headers and defines the analysis to be performed rather exactly. Here are the conventions required for this file:
133
134 =over 4
135
136 =item * Columns must be ordered as such:
137
138 =item [ analysis_type clinical_data_trait_name variant/gene_name covariates memo ]
139
140 =item * The 'analysis_type' column must contain either "Q", indicating a quantative trait, or "B", indicating a binary trait will be examined.
141
142 =item * The 'clinical_data_trait_name' is the name of a clinical data trait defined by being a header in the --glm-clinical-data-file.
143
144 =item * The 'variant/gene_name' can either be the name of one or more columns from the --glm-clinical-data-file, or the name of one or more mutated gene names from the MAF, separated by "|". If this column is left blank, or instead contains "NA", then each column from either the variant mutation matrix (--use-maf-in-glm) or alternatively the --glm-clinical-data-file is used consecutively as the variant column in independent analyses.
145
146 =item * 'covariates' are the names of one or more columns from the --glm-clinical-data-file, separated by "+".
147
148 =item * 'memo' is any note deemed useful to the user. It will be printed in the output data file for reference.
149
150 =back
151
152 GLM analysis may be performed using solely the data input into --glm-clinical-data-file, as described above, or alternatively, mutational data from the MAF may be included as variants in the GLM analysis, as also described above. Use the --use-maf-in-glm flag to include the mutation matrix derived from the maf as variant data.
153
154 Note that all input files for both correlation and GLM analysis must be tab-separated.
155
156 HELP
157 }
158
159 sub _additional_help_sections {
160 return (
161 "ARGUMENTS",
162 <<EOS
163
164 =over 4
165
166 =item --bam-list
167
168 =over 8
169
170 =item Provide a file containing sample names and normal/tumor BAM locations for each. Use the tab-
171 delimited format [sample_name normal_bam tumor_bam] per line. This tool only needs sample_name,
172 so all other columns can be skipped. The sample_name must be the same as the tumor sample names
173 used in the MAF file (16th column, with the header Tumor_Sample_Barcode).
174
175 =back
176
177 =back
178
179 EOS
180 );
181 }
182
183 sub _doc_authors {
184 return <<EOS
185 Nathan D. Dees, Ph.D.
186 Qunyuan Zhang, Ph.D.
187 William Schierding, M.S.
188 EOS
189 }
190
191 sub execute {
192
193 # parse input arguments
194 my $self = shift;
195 my $bam_list = $self->bam_list;
196 my $output_file = $self->output_file;
197 my $genetic_data_type = $self->genetic_data_type;
198
199 # check genetic data type
200 unless( $genetic_data_type =~ /^gene|variant$/i ) {
201 $self->error_message("Please enter either \"gene\" or \"variant\" for the --genetic-data-type parameter.");
202 return;
203 }
204
205 # load clinical data and analysis types
206 my %clinical_data;
207 if( $self->numeric_clinical_data_file ) {
208 $clinical_data{'numeric'} = $self->numeric_clinical_data_file;
209 }
210 if( $self->categorical_clinical_data_file ) {
211 $clinical_data{'categ'} = $self->categorical_clinical_data_file;
212 }
213 if( $self->glm_clinical_data_file ) {
214 $clinical_data{'glm'} = $self->glm_clinical_data_file;
215 }
216 my $glm_model = $self->glm_model_file;
217
218 # declarations
219 my @all_sample_names; # names of all the samples, no matter if it's mutated or not
220
221 # parse out the sample names from the bam-list which should match the names in the MAF file
222 my $sampleFh = IO::File->new( $bam_list ) or die "Couldn't open $bam_list. $!\n";
223 while( my $line = $sampleFh->getline ) {
224 next if ( $line =~ m/^#/ );
225 chomp( $line );
226 my ( $sample ) = split( /\t/, $line );
227 push( @all_sample_names, $sample );
228 }
229 $sampleFh->close;
230
231 # loop through clinical data files
232 for my $datatype ( keys %clinical_data ) {
233
234 my $test_method;
235 my $full_output_filename;
236
237 if( $datatype =~ /numeric/i ) {
238 $full_output_filename = $output_file . ".numeric.csv";
239 $test_method = $self->numerical_data_test_method;
240 }
241
242 if( $datatype =~ /categ/i ) {
243 $full_output_filename = $output_file . ".categorical.csv";
244 $test_method = "fisher";
245 }
246
247 if( $datatype =~ /glm/i ) {
248 $full_output_filename = $output_file . ".glm.csv";
249 $test_method = "glm";
250 }
251
252 #read through clinical data file to see which samples are represented and create input matrix for R
253 my %samples;
254 my $matrix_file;
255 my $samples = \%samples;
256 my $clin_fh = new IO::File $clinical_data{$datatype},"r";
257 unless( $clin_fh ) {
258 die "failed to open $clinical_data{$datatype} for reading: $!";
259 }
260 my $header = $clin_fh->getline;
261 while( my $line = $clin_fh->getline ) {
262 chomp $line;
263 my ( $sample ) = split( /\t/, $line );
264 $samples{$sample}++;
265 }
266 #create correlation matrix unless it's glm analysis without using a maf file
267 unless(( $datatype =~ /glm/i && !$self->use_maf_in_glm ) || $self->input_clinical_correlation_matrix_file ) {
268
269 if( $genetic_data_type =~ /^gene$/i ) {
270 $matrix_file = $self->create_sample_gene_matrix_gene( $samples, $clinical_data{$datatype}, @all_sample_names );
271 }
272 elsif( $genetic_data_type =~ /^variant$/i ) {
273 $matrix_file = $self->create_sample_gene_matrix_variant( $samples, $clinical_data{$datatype}, @all_sample_names );
274 }
275 else {
276 $self->error_message( "Please enter either \"gene\" or \"variant\" for the --genetic-data-type parameter." );
277 return;
278 }
279 }
280
281 if( $self->input_clinical_correlation_matrix_file ) {
282 $matrix_file = $self->input_clinical_correlation_matrix_file;
283 }
284
285 unless( defined $matrix_file ) { $matrix_file = "'*'"; }
286
287 #set up R command
288 my $R_cmd = "R --slave --args < " . __FILE__ . ".R $test_method ";
289
290 if( $datatype =~ /glm/i ) {
291 $R_cmd .= "$glm_model $clinical_data{$datatype} $matrix_file $full_output_filename";
292 }
293 else {
294 $R_cmd .= "$clinical_data{$datatype} $matrix_file $full_output_filename";
295 }
296
297 #run R command
298 print "R_cmd:\n$R_cmd\n";
299 WIFEXITED( system $R_cmd ) or croak "Couldn't run: $R_cmd ($?)";
300 }
301
302 return( 1 );
303 }
304
305 sub create_sample_gene_matrix_gene {
306
307 my ( $self, $samples, $clinical_data_file, @all_sample_names ) = @_;
308 my $output_matrix = $self->clinical_correlation_matrix_file;
309
310 #create a hash of mutations from the MAF file
311 my ( %mutations, %all_genes, @all_genes );
312
313 #parse the MAF file and fill up the mutation status hashes
314 my $maf_fh = IO::File->new( $self->maf_file ) or die "Couldn't open MAF file!\n";
315 while( my $line = $maf_fh->getline ) {
316 next if( $line =~ m/^(#|Hugo_Symbol)/ );
317 chomp $line;
318 my @cols = split( /\t/, $line );
319 my ( $gene, $mutation_class, $sample ) = @cols[0,8,15];
320
321 #check that the mutation class is valid
322 if( $mutation_class !~ m/^(Missense_Mutation|Nonsense_Mutation|Nonstop_Mutation|Splice_Site|Translation_Start_Site|Frame_Shift_Del|Frame_Shift_Ins|In_Frame_Del|In_Frame_Ins|Silent|Intron|RNA|3'Flank|3'UTR|5'Flank|5'UTR|IGR|Targeted_Region|De_novo_Start_InFrame|De_novo_Start_OutOfFrame)$/ ) {
323 $self->error_message( "Unrecognized Variant_Classification \"$mutation_class\" in MAF file for gene $gene\nPlease use TCGA MAF v2.3.\n" );
324 return;
325 }
326
327 #check if sample exists in clinical data
328 unless( defined $samples->{$sample} ) {
329 warn "Sample Name: $sample from MAF file does not exist in Clinical Data File";
330 next;
331 }
332
333 # If user wants, skip Silent mutations, or those in Introns, RNA, UTRs, Flanks, IGRs, or the ubiquitous Targeted_Region
334 if(( $self->skip_non_coding && $mutation_class =~ m/^(Intron|RNA|3'Flank|3'UTR|5'Flank|5'UTR|IGR|Targeted_Region)$/ ) ||
335 ( $self->skip_silent && $mutation_class =~ m/^Silent$/ )) {
336 print "Skipping $mutation_class mutation in gene $gene.\n";
337 next;
338 }
339
340 $all_genes{$gene}++;
341 $mutations{$sample}{$gene}++;
342 }
343 $maf_fh->close;
344
345 #sort @all_genes for consistency
346 @all_genes = sort keys %all_genes;
347
348 #write the input matrix for R code to a file
349 my $matrix_fh;
350 unless (defined $output_matrix) {
351 $output_matrix = Genome::Sys->create_temp_file_path();
352 }
353 $matrix_fh = new IO::File $output_matrix,"w";
354 unless ($matrix_fh) {
355 die "Failed to create matrix file $output_matrix!: $!";
356 }
357 #print input matrix file header
358 my $header = join("\t","Sample",@all_genes);
359 $matrix_fh->print("$header\n");
360
361 #print mutation relation input matrix
362 for my $sample (sort @all_sample_names) {
363 $matrix_fh->print($sample);
364 for my $gene (@all_genes) {
365 if (exists $mutations{$sample}{$gene}) {
366 $matrix_fh->print("\t$mutations{$sample}{$gene}");
367 }
368 else {
369 $matrix_fh->print("\t0");
370 }
371 }
372 $matrix_fh->print("\n");
373 }
374
375 return $output_matrix;
376 }
377
378 sub create_sample_gene_matrix_variant {
379
380 my ( $self, $samples, $clinical_data_file, @all_sample_names ) = @_;
381 my $output_matrix = $self->clinical_correlation_matrix_file;
382
383 #create hash of mutations from the MAF file
384 my ( %variants_hash, %all_variants );
385
386 #parse the MAF file and fill up the mutation status hashes
387 my $maf_fh = IO::File->new( $self->maf_file ) or die "Couldn't open MAF file!\n";
388 while( my $line = $maf_fh->getline ) {
389 next if( $line =~ m/^(#|Hugo_Symbol)/ );
390 chomp $line;
391 my @cols = split( /\t/, $line );
392 my ( $gene, $chr, $start, $stop, $mutation_class, $mutation_type, $ref, $var1, $var2, $sample ) = @cols[0,4..6,8..12,15];
393
394 #check that the mutation class is valid
395 if( $mutation_class !~ m/^(Missense_Mutation|Nonsense_Mutation|Nonstop_Mutation|Splice_Site|Translation_Start_Site|Frame_Shift_Del|Frame_Shift_Ins|In_Frame_Del|In_Frame_Ins|Silent|Intron|RNA|3'Flank|3'UTR|5'Flank|5'UTR|IGR|Targeted_Region|De_novo_Start_InFrame|De_novo_Start_OutOfFrame)$/ ) {
396 $self->error_message( "Unrecognized Variant_Classification \"$mutation_class\" in MAF file for gene $gene\nPlease use TCGA MAF v2.3.\n" );
397 return;
398 }
399
400 unless( exists $samples->{$sample} ) {
401 warn "Sample Name: $sample from MAF file does not exist in Clinical Data File";
402 next;
403 }
404
405 # If user wants, skip Silent mutations, or those in Introns, RNA, UTRs, Flanks, IGRs, or the ubiquitous Targeted_Region
406 if(( $self->skip_non_coding && $mutation_class =~ m/^(Intron|RNA|3'Flank|3'UTR|5'Flank|5'UTR|IGR|Targeted_Region)$/ ) ||
407 ( $self->skip_silent && $mutation_class =~ m/^Silent$/ )) {
408 print "Skipping $mutation_class mutation in gene $gene.\n";
409 next;
410 }
411
412 my $var;
413 my $variant_name;
414 if( $ref eq $var1 ) {
415 $var = $var2;
416 $variant_name = $gene."_".$chr."_".$start."_".$stop."_".$ref."_".$var;
417 $variants_hash{$sample}{$variant_name}++;
418 $all_variants{$variant_name}++;
419 }
420 elsif( $ref eq $var2 ) {
421 $var = $var1;
422 $variant_name = $gene."_".$chr."_".$start."_".$stop."_".$ref."_".$var;
423 $variants_hash{$sample}{$variant_name}++;
424 $all_variants{$variant_name}++;
425 }
426 elsif( $ref ne $var1 && $ref ne $var2 ) {
427 $var = $var1;
428 $variant_name = $gene."_".$chr."_".$start."_".$stop."_".$ref."_".$var;
429 $variants_hash{$sample}{$variant_name}++;
430 $all_variants{$variant_name}++;
431 $var = $var2;
432 $variant_name = $gene."_".$chr."_".$start."_".$stop."_".$ref."_".$var;
433 $variants_hash{$sample}{$variant_name}++;
434 $all_variants{$variant_name}++;
435 }
436 }
437 $maf_fh->close;
438
439 #sort variants for consistency
440 my @variant_names = sort keys %all_variants;
441
442 #write the input matrix for R code to a file
443 my $matrix_fh;
444 unless( defined $output_matrix ) {
445 $output_matrix = Genome::Sys->create_temp_file_path();
446 }
447 $matrix_fh = new IO::File $output_matrix,"w";
448 unless( $matrix_fh ) {
449 die "Failed to create matrix file $output_matrix!: $!";
450 }
451
452 #print input matrix file header
453 my $header = join( "\t", "Sample", @variant_names );
454 $matrix_fh->print("$header\n");
455
456 #print mutation relation input matrix
457 for my $sample ( sort @all_sample_names ) {
458 $matrix_fh->print( $sample );
459 for my $variant ( @variant_names ) {
460 if( exists $variants_hash{$sample}{$variant} ) {
461 $matrix_fh->print("\t$variants_hash{$sample}{$variant}");
462 }
463 else {
464 $matrix_fh->print("\t0");
465 }
466 }
467 $matrix_fh->print("\n");
468 }
469
470 return $output_matrix;
471 }
472
473 1;