Genome...Helper(3pm)

💖 Genome...Helper 💖

okay so bestie, this is the page for Genome...Helper(3pm) ✨ it lives in the User Contributed Perl Documentation corner of the manual, and it is giving major "the module documents itself from the inside" energy, because a big chunk of it is literally the Perl subs that hand back the doc strings. very meta, very iconic, we love that for it 💅

🎀 OPTIONS 🎀

• --roi-file — so the regions of interest (ROIs) of each gene are typically the regions targeted for sequencing, or they're merged exon loci (from multiple transcripts) of genes with 2-bp flanks — those flanks are the splice junctions, iykyk 🧬 and listen: ROIs from the same chromosome must be listed adjacent to each other in this file, no cap. why? because it lets the underlying C-based code run so much more efficiently and avoid re-counting bases it already saw in overlapping ROIs (that's for overall covered base counts). but heads up for per-gene base counts 😭 an overlapping base will be counted each time it appears in an ROI of the same gene. so to avoid that, be sure to merge together overlapping ROIs of the same gene. BEDtools' mergeBed can help if you use it per gene 🫶
• --reference-sequence — the reference sequence, in FASTA format 🌸 and if a reference sequence index isn't found next to this file (that's a .fai file), it will be created. handled, don't stress ✨
• --normal-tumor-bam-pair — the value looks exactly like this: "sample-name path/to/normal_bam path/to/tumor_bam" 👑
• --output-file — specify an output file where the per-ROI covered base counts will be written 📝

🧚 UNDER THE HOOD 🧚

and now, the actual Perl, verbatim, every string and regex and $self-> accessor exactly as it appears 💜

       EOS
         ); }

       sub _doc_authors {
         return " Cyriac Kandoth, Ph.D."; }

       sub _doc_see_also {
         return <<EOS genome-music-bmr(1), genome-music(1), genome(1) EOS }

       sub execute {
         my $self = shift;
         my $roi_file = $self->roi_file;
         my $ref_seq = $self->reference_sequence;
         my $tumor_bam = $self->tumor_bam;
         my $normal_bam = $self->normal_bam;
         my $output_file = $self->final_output_file;
         my $normal_min_depth = $self->normal_min_depth;
         my $tumor_min_depth = $self->tumor_min_depth;
         my $min_mapq = $self->min_mapq;

         # Check on all the input data before starting work
         print STDERR "ROI file not found or is empty: $roi_file\n" unless( -s $roi_file );
         print STDERR "Reference sequence file not found: $ref_seq\n" unless( -e $ref_seq );
         print STDERR "Normal BAM file not found or is empty: $normal_bam\n" unless( -s $normal_bam );
         print STDERR "Tumor BAM file not found or is empty: $tumor_bam\n" unless( -s $tumor_bam );
         return undef unless( -s $roi_file && -e $ref_seq && -s $normal_bam && -s $tumor_bam );

         # Check whether the annotated regions of interest are clumped together by chromosome
         my $roiFh = IO::File->new( $roi_file ) or die "ROI file could not be opened. $!\n";
         my @chroms = ( "" );
         while( my $line = $roiFh->getline ) # Emulate Unix's uniq command on the chromosome column
         {
           my ( $chrom ) = ( $line =~ m/^(\S+)/ );
           push( @chroms, $chrom ) if( $chrom ne $chroms[-1] );
         }
         $roiFh->close;
         my %chroms = map { $_ => 1 } @chroms; # Get the actual number of unique chromosomes
         if( scalar( @chroms ) != scalar( keys %chroms ))
         {
           print STDERR "ROIs from the same chromosome must be listed adjacent to each other in file. ";
           print STDERR "If in UNIX, try:\nsort -k 1,1 $roi_file\n";
           return undef;
         }

         # If the reference sequence FASTA file hasn't been indexed, do it
         my $ref_seq_idx = "$ref_seq.fai";
         system( "samtools faidx $ref_seq" ) unless( -e $ref_seq_idx );

         $normal_bam = '' unless( defined $normal_bam );
         $tumor_bam = '' unless( defined $tumor_bam );
         print STDERR "Normal BAM not found: \"$normal_bam\"\n" unless( -e $normal_bam );
         print STDERR "Tumor BAM not found: \"$tumor_bam\"\n" unless( -e $tumor_bam );
         next unless( -e $normal_bam && -e $tumor_bam );

         # Construct the command that calculates coverage per ROI
         my $calcRoiCovg_cmd = "calcRoiCovg $normal_bam $tumor_bam $roi_file $ref_seq $output_file $normal_min_depth $tumor_min_depth $min_mapq";

         # If the calcRoiCovg output was already generated, then don't rerun it
         if( -s $output_file )
         {
           print "Output file $output_file found. Skipping re-calculation.\n";
         }
         # Run the calcRoiCovg command on this tumor-normal pair. This could take a while
         elsif( system( "$calcRoiCovg_cmd" ) != 0 )
         {
           print STDERR "Failed to execute: $calcRoiCovg_cmd\n";
           return;
         }
         else
         {
           print "$output_file generated and stored.\n";
           return 1;
         }

       }

       1;

so what's actually happening in there, bestie? 🕵️

• first it pulls a whole pile of stuff off $self: roi_file, reference_sequence, tumor_bam, normal_bam, final_output_file, normal_min_depth, tumor_min_depth, and min_mapq
• then it checks on all the input data before starting work, printing to STDERR if the ROI file is not found or is empty, the reference sequence file is not found, or the normal/tumor BAM files are not found or are empty — and it returns undef if any of that goes wrong
• then it checks whether the annotated regions of interest are clumped together by chromosome, emulating Unix's uniq command on the chromosome column, and if they're not it tells you the ROIs from the same chromosome must be listed adjacent to each other in the file and suggests trying sort -k 1,1 $roi_file 🙈
• if the reference sequence FASTA file hasn't been indexed, it does that step
• then it constructs the command that calculates coverage per ROI, and if the output file was already generated it just says so and skips re-calculation instead of rerunning 💅

👑 SEE ALSO 👑

• genome-music-bmr(1)
• genome-music(1)
• genome(1)

and that's the whole vibe 🎀 shoutout to Cyriac Kandoth, Ph.D. for writing this, fr fr 💜 this page is perl v5.30.3, dated 2020-11-06, and it's Genome...Helper(3pm) — periodt 💅