PCAP::Bam(3)

NAME
PCAP::Bam - Methods that process BAM files

  Object Methods

new
      my $bam = PCAP::Bam->new($bam_file);

    Generate a BAM object to allow access to object based functions. Primarily added to allow efficient access to header information without re-parsing once populated.

read_group_info
      my $rg_data = $bam->read_group_info($required_tags);

    Returns an arrayref (one entry per readgroup) of hashes where the keys are the RG tags found in the @RG header line. Providing an arrayref of required_tags causes an error to be raised if any are not found:

      my $rg_data = $bam->read_group_info([qw(CN LB SN)]);

    Resulting data structure:

      [ { CN => 'SI',
          LB => 'LIBRARY_ID',
          SM => 'Sample_name},
        { CN => ...
        },
        ...];

single_rg_value
      my $sample_name = $bam->single_rg_value('SM');

    Gets the value of a single RG tag. Errors if multiple readgroups detected.

check_for_tags
      $bam->check_for_tags([list of required tags]);

    Check that all readgroups in this BAM have the specified tags. Errors if any are not detected.

check_paired
      $bam->check_paired;

    Will error if BAM file doesn't contain paired reads.

comments
      my @comments = @{$bam->comments};

    Returns an array ref of the value of each comment line. '@CO\t' is pre-stripped.

sam_header
      my @header_lines = @{$bam->sam_header};

    Returns array ref of all header lines. One entry perl line.

  Non Object Methods

bam_to_grouped_bam
      PCAP::Bam::bam_to_grouped_bam($index, $options);

    Convert a BAM for a single readgroup to a readname grouped BAM.

      index   - Which element of the 'bams' array reference found in options should be processed
                  NOTE: index is origin 1

      options - Hashref, requires the following entries:

              -tmp  : working/output directory depending on application
              -bams : array reference to a B<sorted> list of BAM files (to allow resume function)

    On successful completion of a run a file is created in tmp/progress/bamcollate.$index. If the program is re-run without clearing of this progress folder the execution of the command is skipped.

merge_and_mark_dup
      PCAP::Bam::merge_and_mark_dup($options);

    Takes a list of sorted BAM files, marks duplicates and produces single output BAM in one pass.

      options - Hashref, requires the following entries:

              -tmp      : working/output directory depending on application
              -bams     : array reference to a B<sorted> list of BAM files (for consistent results)
              -outdir   : output files written to this folder
              -sample   : prefix of output file
              -threads  : Total threads available to process

      returns - path_to_marked_bam

    Resulting data is of the form:

      $outdir/$sample.bam
      $outdir/$sample.bam.bai
      $outdir/$sample.bam.md5
      $outdir/$sample.met

sample_name
    Takes BAM or Bio::DB::HTS object as input and returns the sample name found in the header.

    The SAM object is also returned should it be useful for other calls

rg_line_for_output
    Takes BAM or Bio::DB::HTS object as input and returns the string representation for the RG line. Intended for use when adding RG to BWA MEM output and is only useful in single RG BAMs

    Optional second boolean arg causes ID to be replaced with a UUID.

    The SAM object is also returned should it be useful for other calls

sam_ob
      my $sam_ob = sam_ob('file.bam');

    Generate a Bio::DB::HTS object from the provided BAM|CRAM file.