BamUtil: revert

Overview of the revert function of bamUtil

The revert option on the bamUtil executable reverts the specified SAM/BAM by replacing the specified fields with their previous values (if known) and removes specified tags.

Currently there are options to revert the CIGAR and POS to the original values that are stored in the OC & OP fields and to revert the quality to its original value found in the OQ tag.

The keepTags parameter is used to indicate not to remove the tags used for reverting.

Additional parameters allow for the removal of any other tags in order to cleanup the SAM/BAM file.

NOTE: Does not reorder the BAM file after modifying the position, so the resulting file may not be sorted by coordinate.

Usage

./bam revert --in <inputFile> --out <outputFile.sam/bam/ubam (ubam is uncompressed bam)> [--cigar] [--qual] [--keepTags] [--rmBQ] [--rmTags <Tag:Type[;Tag:Type]*>] [--noeof] [--params]

Parameters

	Required Parameters:
		--in         : the SAM/BAM file to be read
		--out        : the SAM/BAM file to be written
	Optional Parameters:
		--cigar      : update the cigar and the position based on the OC & OP tags.
		--qual       : update the quality based on the OQ tag.
		--keepTags   : keep the tags that are used to update the record.  Default is to remove them.
		--rmBQ       : Remove the BQ Tag.
		--rmTags     : Remove the specified Tags formatted as Tag:Type;Tag:Type;Tag:Type...
		--noeof      : do not expect an EOF block on a bam file.
		--params     : print the parameter settings

	PhoneHome:
		--noPhoneHome       : disable PhoneHome (default enabled)
		--phoneHomeThinning : adjust the PhoneHome thinning parameter (default 50)

Required Parameters

Input File (--in)

Use --in followed by your file name to specify the SAM/BAM input file.

The program automatically determines if your input file is SAM/BAM/uncompressed BAM without any input other than a filename from the user, unless your input file is stdin.

A - is used to indicate to read from stdin and the extension is used to determine the file type (no extension indicates SAM).

SAM/BAM/Uncompressed BAM from file	--in yourFileName
SAM from stdin	--in -
BAM from stdin	--in -.bam
Uncompressed BAM from stdin	--in -.ubam

Note: Uncompressed BAM is compressed using compression level-0 (so it is not an entirely uncompressed file). This matches the samtools implementation so pipes between our tools and samtools are supported.

Output File (--out)

Use --out followed by your file name to specify the SAM/BAM output file.

The file extension is used to determine whether to write SAM/BAM/uncompressed BAM. A - is used to indicate stdout and the extension for file type (no extension is SAM).

SAM to file	--out yourFileName.sam
BAM to file	--out yourFileName.bam
Uncompressed BAM to file	--out yourFileName.ubam
SAM to stdout	--out -
BAM to stdout	--out -.bam
Uncompressed BAM to stdout	--out -.ubam

Note: Uncompressed BAM is compressed using compression level-0 (so it is not an entirely uncompressed file). This matches the samtools implementation so pipes between our tools and samtools are supported.

Optional Parameters

Revert the CIGAR & Position (--cigar)

Update the cigar and the base position of reads to the values in the OC (cigar) & OP (base position) tags.

By default, the OC & OP tags are removed. Use [[Keep Tags Used for Reverting (--keepTags)|--keepTags]] to keep the OC & OP tags.

Revert the Quality (--qual)

Update the quality of reads to the value in the OQ tag.

By default, the OQ tag is removed. Use [[Keep Tags Used for Reverting (--keepTags)|--keepTags]] to keep the OQ tag.

Keep Tags Used for Reverting (--keepTags)

Keep the tags that are used for reverting. The default (no option) is to remove the tags after they are used.

Remove BQ Tag (--rmBQ)

Use the --rmBQ option to remove the BQ Tag.

Remove Tags (--rmTags)

Use --rmTags followed by a list of tags separated by ';' to remove the specified tags. The tags should be formatted as: Tag:Type"

For multiple tags: Tag:Type;Tag:Type;Tag:Type...

Do not require BGZF EOF block (--noeof)

Use --noeof if you do not expect a trailing eof block in your bgzf file.

By default, the trailing empty block is expected and checked for.

Print the Program Parameters (--params)

Use --params to print the parameters for your program to stderr.

PhoneHome Parameters

See PhoneHome for more information on how PhoneHome works and what it does.

Turn off PhoneHome (--noPhoneHome)

Use the --noPhoneHome option to completely disable PhoneHome. PhoneHome is enabled by default based on the thinning parameter.

Adjust the Frequency of PhoneHome (--phoneHomeThinning)

Use --phoneHomeThinning to modify the percentage of the time that PhoneHome will run (0-100).

• By default, --phoneHomeThinning is set to 50, running 50% of the time.
• PhoneHome will only occur if the run's random number modulo 100 is less than the --phoneHomeThinning value.
• N/A if --noPhoneHome is set.

Return Value

Returns the SamStatus for the reads/writes (0 for success, non-0 for failure).

Example Output

Number of records read = 10
Number of records written = 10