Create a SAM record from data. This function verifies the format and indexes fields for accessors. Note that the ownership of data is transferred to a new record object.
Note that in the BAM specification, the field called cigar typically stores the cigar string of the record. However, this is not always true, sometimes the true cigar is very long, and due to some constraints of the BAM format, the actual cigar string is stored in an extra tag: CG:B,I, and the cigar field stores a pseudo-cigar string.
Calling this method with checkCG set to true (default) this method will always yield the true cigar string, because this is probably what you want the vast majority of the time.
If you have a record that stores the true cigar in a CG:B,I tag, but you still want to access the pseudo-cigar that is stored in the cigar field of the BAM record, then you can set checkCG to false.
Get a run-length encoded tuple (ops, lens) of the CIGAR string in record.
Note that in the BAM specification, the field called cigar typically stores the cigar string of the record. However, this is not always true, sometimes the true cigar is very long, and due to some constraints of the BAM format, the actual cigar string is stored in an extra tag: CG:B,I, and the cigar field stores a pseudo-cigar string.
Calling this method with checkCG set to true (default) this method will always yield the true cigar string, because this is probably what you want the vast majority of the time.
If you have a record that stores the true cigar in a CG:B,I tag, but you still want to access the pseudo-cigar that is stored in the cigar field of the BAM record, then you can set checkCG to false.
Return the number of operations in the CIGAR string of record.
Note that in the BAM specification, the field called cigar typically stores the cigar string of the record. However, this is not always true, sometimes the true cigar is very long, and due to some constraints of the BAM format, the actual cigar string is stored in an extra tag: CG:B,I, and the cigar field stores a pseudo-cigar string.
Calling this method with checkCG set to true (default) this method will always yield the number of operations in the true cigar string, because this is probably what you want, the vast majority of the time.
If you have a record that stores the true cigar in a CG:B,I tag, but you still want to get the number of operations in the cigar field of the BAM record, then set checkCG to false.
Create a SAM record from data. This function verifies the format and indexes fields for accessors. Note that the ownership of data is transferred to a new record object.
Note that in the BAM specification, the field called cigar typically stores the cigar string of the record. However, this is not always true, sometimes the true cigar is very long, and due to some constraints of the BAM format, the actual cigar string is stored in an extra tag: CG:B,I, and the cigar field stores a pseudo-cigar string.
Calling this method with checkCG set to true (default) this method will always yield the true cigar string, because this is probably what you want the vast majority of the time.
If you have a record that stores the true cigar in a CG:B,I tag, but you still want to access the pseudo-cigar that is stored in the cigar field of the BAM record, then you can set checkCG to false.
Get a run-length encoded tuple (ops, lens) of the CIGAR string in record.
Note that in the BAM specification, the field called cigar typically stores the cigar string of the record. However, this is not always true, sometimes the true cigar is very long, and due to some constraints of the BAM format, the actual cigar string is stored in an extra tag: CG:B,I, and the cigar field stores a pseudo-cigar string.
Calling this method with checkCG set to true (default) this method will always yield the true cigar string, because this is probably what you want the vast majority of the time.
If you have a record that stores the true cigar in a CG:B,I tag, but you still want to access the pseudo-cigar that is stored in the cigar field of the BAM record, then you can set checkCG to false.
Return the number of operations in the CIGAR string of record.
Note that in the BAM specification, the field called cigar typically stores the cigar string of the record. However, this is not always true, sometimes the true cigar is very long, and due to some constraints of the BAM format, the actual cigar string is stored in an extra tag: CG:B,I, and the cigar field stores a pseudo-cigar string.
Calling this method with checkCG set to true (default) this method will always yield the number of operations in the true cigar string, because this is probably what you want, the vast majority of the time.
If you have a record that stores the true cigar in a CG:B,I tag, but you still want to get the number of operations in the cigar field of the BAM record, then set checkCG to false.
Note that in the BAM specification, the field called cigar typically stores the cigar string of the record. However, this is not always true, sometimes the true cigar is very long, and due to some constraints of the BAM format, the actual cigar string is stored in an extra tag: CG:B,I, and the cigar field stores a pseudo-cigar string.
Calling this method with checkCG set to true (default) this method will always yield the true cigar string, because this is probably what you want the vast majority of the time.
If you have a record that stores the true cigar in a CG:B,I tag, but you still want to access the pseudo-cigar that is stored in the cigar field of the BAM record, then you can set checkCG to false.
SAM and BAM records support the storing of optional data fields associated with tags.
Tagged auxiliary data follows a format of TAG:TYPE:VALUE. TAG is a two-letter string, and each tag can only appear once per record. TYPE is a single case-sensetive letter which defined the format of VALUE.
Type
Description
'A'
Printable character
'i'
Signed integer
'f'
Single-precision floating number
'Z'
Printable string, including space
'H'
Byte array in Hex format
'B'
Integer of numeric array
For more information about these tags and their types we refer you to the [SAM/BAM specification][samtools-spec] and the additional [optional fields specification][samtags] document.
There are some tags that are reserved, predefined standard tags, for specific uses.
To access optional fields stored in tags, you use getindex indexing syntax on the record object. Note that accessing optional tag fields will result in type instability in Julia. This is because the type of the optional data is not known until run-time, as the tag is being read. This can have a significant impact on performance. To limit this, if the user knows the type of a value in advance, specifying it as a type annotation will alleviate the problem:
Below is an example of looping over records in a bam file and using indexing syntax to get the data stored in the "NM" tag. Note the UInt8 type assertion to alleviate type instability.
for record in open(BAM.Reader, "data.bam")
+
In the above we can see there were 7 sequences in the reference: 5 chromosomes, one chloroplast sequence, and one mitochondrial sequence.
Note that in the BAM specification, the field called cigar typically stores the cigar string of the record. However, this is not always true, sometimes the true cigar is very long, and due to some constraints of the BAM format, the actual cigar string is stored in an extra tag: CG:B,I, and the cigar field stores a pseudo-cigar string.
Calling this method with checkCG set to true (default) this method will always yield the true cigar string, because this is probably what you want the vast majority of the time.
If you have a record that stores the true cigar in a CG:B,I tag, but you still want to access the pseudo-cigar that is stored in the cigar field of the BAM record, then you can set checkCG to false.
SAM and BAM records support the storing of optional data fields associated with tags.
Tagged auxiliary data follows a format of TAG:TYPE:VALUE. TAG is a two-letter string, and each tag can only appear once per record. TYPE is a single case-sensetive letter which defined the format of VALUE.
Type
Description
'A'
Printable character
'i'
Signed integer
'f'
Single-precision floating number
'Z'
Printable string, including space
'H'
Byte array in Hex format
'B'
Integer of numeric array
For more information about these tags and their types we refer you to the [SAM/BAM specification][samtools-spec] and the additional [optional fields specification][samtags] document.
There are some tags that are reserved, predefined standard tags, for specific uses.
To access optional fields stored in tags, you use getindex indexing syntax on the record object. Note that accessing optional tag fields will result in type instability in Julia. This is because the type of the optional data is not known until run-time, as the tag is being read. This can have a significant impact on performance. To limit this, if the user knows the type of a value in advance, specifying it as a type annotation will alleviate the problem:
Below is an example of looping over records in a bam file and using indexing syntax to get the data stored in the "NM" tag. Note the UInt8 type assertion to alleviate type instability.
for record in open(BAM.Reader, "data.bam")
nm = record["NM"]::UInt8
# do something
end
BioAlignments supports the BAI index to fetch records in a specific range from a BAM file. [Samtools][samtools] provides index subcommand to create an index file (.bai) from a sorted BAM file.
We also welcome financial contributions in full transparency on our open collective. Anyone can file an expense. If the expense makes sense for the development of the community, it will be "merged" in the ledger of our open collective by the core contributors and the person who filed the expense will be reimbursed.
Does your company use BioJulia? Help keep BioJulia feature rich and healthy by sponsoring the project Your logo will show up here with a link to your website.
We also welcome financial contributions in full transparency on our open collective. Anyone can file an expense. If the expense makes sense for the development of the community, it will be "merged" in the ledger of our open collective by the core contributors and the person who filed the expense will be reimbursed.
Does your company use BioJulia? Help keep BioJulia feature rich and healthy by sponsoring the project Your logo will show up here with a link to your website.
diff --git a/dev/search_index.js b/dev/search_index.js
index e2bd775..4171e2a 100644
--- a/dev/search_index.js
+++ b/dev/search_index.js
@@ -1,3 +1,3 @@
var documenterSearchIndex = {"docs":
-[{"location":"#XAM-1","page":"Home","title":"XAM","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"(Image: Latest Release) (Image: MIT license) (Image: Stable documentation) (Image: Latest documentation) (Image: Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.)","category":"page"},{"location":"#","page":"Home","title":"Home","text":"(Image: Chat)","category":"page"},{"location":"#Description-1","page":"Home","title":"Description","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"XAM provides I/O and utilities for manipulating SAM and BAM, formatted alignment map files.","category":"page"},{"location":"#Installation-1","page":"Home","title":"Installation","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"XAM is made available to install through BioJulia's package registry.","category":"page"},{"location":"#","page":"Home","title":"Home","text":"Julia by default only watches the \"General\" package registry, so before you start, you should add the BioJulia package registry.","category":"page"},{"location":"#","page":"Home","title":"Home","text":"Start a julia terminal, hit the ] key to enter pkg mode (you should see the prompt change from julia> to pkg> ), then enter the following command:","category":"page"},{"location":"#","page":"Home","title":"Home","text":"registry add https://github.com/BioJulia/BioJuliaRegistry.git","category":"page"},{"location":"#","page":"Home","title":"Home","text":"After you've added the registry, you can install XAM from the julia REPL. Press ] to enter pkg mode again, and enter the following:","category":"page"},{"location":"#","page":"Home","title":"Home","text":"add XAM","category":"page"},{"location":"#","page":"Home","title":"Home","text":"If you are interested in the cutting edge of the development, please check out the develop branch to try new features before release.","category":"page"},{"location":"#Testing-1","page":"Home","title":"Testing","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"XAM is tested against Julia 1.X on Linux, OS X, and Windows.","category":"page"},{"location":"#","page":"Home","title":"Home","text":"Latest build status:","category":"page"},{"location":"#","page":"Home","title":"Home","text":"(Image: ) (Image: Build status) (Image: )","category":"page"},{"location":"#Contributing-1","page":"Home","title":"Contributing","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"We appreciate contributions from users including reporting bugs, fixing issues, improving performance and adding new features.","category":"page"},{"location":"#","page":"Home","title":"Home","text":"Take a look at the contributing files detailed contributor and maintainer guidelines, and code of conduct.","category":"page"},{"location":"#Financial-contributions-1","page":"Home","title":"Financial contributions","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"We also welcome financial contributions in full transparency on our open collective. Anyone can file an expense. If the expense makes sense for the development of the community, it will be \"merged\" in the ledger of our open collective by the core contributors and the person who filed the expense will be reimbursed.","category":"page"},{"location":"#Backers-and-Sponsors-1","page":"Home","title":"Backers & Sponsors","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"Thank you to all our backers and sponsors!","category":"page"},{"location":"#","page":"Home","title":"Home","text":"Love our work and community? Become a backer.","category":"page"},{"location":"#","page":"Home","title":"Home","text":"(Image: backers)","category":"page"},{"location":"#","page":"Home","title":"Home","text":"Does your company use BioJulia? Help keep BioJulia feature rich and healthy by sponsoring the project Your logo will show up here with a link to your website.","category":"page"},{"location":"#","page":"Home","title":"Home","text":"(Image: ) (Image: ) (Image: ) (Image: ) (Image: ) (Image: ) (Image: ) (Image: ) (Image: ) (Image: )","category":"page"},{"location":"#Questions?-1","page":"Home","title":"Questions?","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"If you have a question about contributing or using BioJulia software, come on over and chat to us on Gitter, or you can try the Bio category of the Julia discourse site.","category":"page"},{"location":"hts-files/#SAM-and-BAM-1","page":"SAM and BAM","title":"SAM and BAM","text":"","category":"section"},{"location":"hts-files/#Introduction-1","page":"SAM and BAM","title":"Introduction","text":"","category":"section"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"High-throughput sequencing (HTS) technologies generate a large amount of data in the form of a large number of nucleotide sequencing reads. One of the most common tasks in bioinformatics is to align these reads against known reference genomes, chromosomes, or contigs. BioAlignments provides several data formats commonly used for this kind of task.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"BioAlignments offers high-performance tools for SAM and BAM file formats, which are the most popular file formats.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"If you have questions about the SAM and BAM formats or any of the terminology used when discussing these formats, see the published [specification][samtools-spec], which is maintained by the [samtools group][samtools].","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"A very very simple SAM file looks like the following:","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"@HD VN:1.6 SO:coordinate\n@SQ SN:ref LN:45\nr001 99 ref 7 30 8M2I4M1D3M = 37 39 TTAGATAAAGGATACTG *\nr002 0 ref 9 30 3S6M1P1I4M * 0 0 AAAAGATAAGGATA *\nr003 0 ref 9 30 5S6M * 0 0 GCCTAAGCTAA * SA:Z:ref,29,-,6H5M,17,0;\nr004 0 ref 16 30 6M14N5M * 0 0 ATAGCTTCAGC *\nr003 2064 ref 29 17 6H5M * 0 0 TAGGC * SA:Z:ref,9,+,5S6M,30,1;\nr001 147 ref 37 30 9M = 7 -39 CAGCGGCAT * NM:i:1","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"Where the first two lines are part of the \"header\", and the following lines are \"records\". Each record describes how a read aligns to some reference sequence. Sometimes one record describes one read, but there are other cases like chimeric reads and split alignments, where multiple records apply to one read. In the example above, r003 is a chimeric read, and r004 is a split alignment, and r001 are mate pair reads. Again, we refer you to the official [specification][samtools-spec] for more details.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"A BAM file stores this same information but in a binary and compressible format that does not make for pretty printing here!","category":"page"},{"location":"hts-files/#Reading-SAM-and-BAM-files-1","page":"SAM and BAM","title":"Reading SAM and BAM files","text":"","category":"section"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"A typical script iterating over all records in a file looks like below:","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"using BioAlignments\n\n# Open a BAM file.\nreader = open(BAM.Reader, \"data.bam\")\n\n# Iterate over BAM records.\nfor record in reader\n # `record` is a BAM.Record object.\n if BAM.ismapped(record)\n # Print the mapped position.\n println(BAM.refname(record), ':', BAM.position(record))\n end\nend\n\n# Close the BAM file.\nclose(reader)","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"The size of a BAM file is often extremely large. The iterator interface demonstrated above allocates an object for each record and that may be a bottleneck of reading data from a BAM file. In-place reading reuses a pre-allocated object for every record and less memory allocation happens in reading:","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"reader = open(BAM.Reader, \"data.bam\")\nrecord = BAM.Record()\nwhile !eof(reader)\n read!(reader, record)\n # do something\nend","category":"page"},{"location":"hts-files/#SAM-and-BAM-Headers-1","page":"SAM and BAM","title":"SAM and BAM Headers","text":"","category":"section"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"Both SAM.Reader and BAM.Reader implement the header function, which returns a SAM.Header object. To extract certain information out of the headers, you can use the find method on the header to extract information according to SAM/BAM tag. Again we refer you to the [specification][samtools-spec] for full details of all the different tags that can occur in headers, and what they mean.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"Below is an example of extracting all the info about the reference sequences from the BAM header. In SAM/BAM, any description of a reference sequence is stored in the header, under a tag denoted SQ (think reference SeQuence!).","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"julia> reader = open(SAM.Reader, \"data.sam\");\n\njulia> find(header(reader), \"SQ\")\n7-element Array{Bio.Align.SAM.MetaInfo,1}:\n Bio.Align.SAM.MetaInfo:\n tag: SQ\n value: SN=Chr1 LN=30427671\n Bio.Align.SAM.MetaInfo:\n tag: SQ\n value: SN=Chr2 LN=19698289\n Bio.Align.SAM.MetaInfo:\n tag: SQ\n value: SN=Chr3 LN=23459830\n Bio.Align.SAM.MetaInfo:\n tag: SQ\n value: SN=Chr4 LN=18585056\n Bio.Align.SAM.MetaInfo:\n tag: SQ\n value: SN=Chr5 LN=26975502\n Bio.Align.SAM.MetaInfo:\n tag: SQ\n value: SN=chloroplast LN=154478\n Bio.Align.SAM.MetaInfo:\n tag: SQ\n value: SN=mitochondria LN=366924\n","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"In the above we can see there were 7 sequences in the reference: 5 chromosomes, one chloroplast sequence, and one mitochondrial sequence.","category":"page"},{"location":"hts-files/#SAM-and-BAM-Records-1","page":"SAM and BAM","title":"SAM and BAM Records","text":"","category":"section"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"BioAlignments supports the following accessors for SAM.Record types.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"XAM.SAM.flag\nXAM.SAM.ismapped\nXAM.SAM.isprimary\nXAM.SAM.refname\nXAM.SAM.position\nXAM.SAM.rightposition\nXAM.SAM.isnextmapped\nXAM.SAM.nextrefname\nXAM.SAM.nextposition\nXAM.SAM.mappingquality\nXAM.SAM.cigar\nXAM.SAM.alignment\nXAM.SAM.alignlength\nXAM.SAM.tempname\nXAM.SAM.templength\nXAM.SAM.sequence\nXAM.SAM.seqlength\nXAM.SAM.quality\nXAM.SAM.auxdata","category":"page"},{"location":"hts-files/#XAM.SAM.flag","page":"SAM and BAM","title":"XAM.SAM.flag","text":"flag(record::Record)::UInt16\n\nGet the bitwise flag of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.ismapped","page":"SAM and BAM","title":"XAM.SAM.ismapped","text":"ismapped(record::Record)::Bool\n\nTest if record is mapped.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.isprimary","page":"SAM and BAM","title":"XAM.SAM.isprimary","text":"isprimary(record::Record)::Bool\n\nTest if record is a primary line of the read.\n\nThis is equivalent to flag(record) & 0x900 == 0.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.refname","page":"SAM and BAM","title":"XAM.SAM.refname","text":"refname(record::Record)::String\n\nGet the reference sequence name of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.position","page":"SAM and BAM","title":"XAM.SAM.position","text":"position(record::Record)::Int\n\nGet the 1-based leftmost mapping position of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.rightposition","page":"SAM and BAM","title":"XAM.SAM.rightposition","text":"rightposition(record::Record)::Int\n\nGet the 1-based rightmost mapping position of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.isnextmapped","page":"SAM and BAM","title":"XAM.SAM.isnextmapped","text":"isnextmapped(record::Record)::Bool\n\nTest if the mate/next read of record is mapped.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.nextrefname","page":"SAM and BAM","title":"XAM.SAM.nextrefname","text":"nextrefname(record::Record)::String\n\nGet the reference name of the mate/next read of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.nextposition","page":"SAM and BAM","title":"XAM.SAM.nextposition","text":"nextposition(record::Record)::Int\n\nGet the position of the mate/next read of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.mappingquality","page":"SAM and BAM","title":"XAM.SAM.mappingquality","text":"mappingquality(record::Record)::UInt8\n\nGet the mapping quality of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.cigar","page":"SAM and BAM","title":"XAM.SAM.cigar","text":"cigar(record::Record)::String\n\nGet the CIGAR string of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.alignment","page":"SAM and BAM","title":"XAM.SAM.alignment","text":"alignment(record::Record)::BioAlignments.Alignment\n\nGet the alignment of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.alignlength","page":"SAM and BAM","title":"XAM.SAM.alignlength","text":"alignlength(record::Record)::Int\n\nGet the alignment length of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.tempname","page":"SAM and BAM","title":"XAM.SAM.tempname","text":"tempname(record::Record)::String\n\nGet the query template name of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.templength","page":"SAM and BAM","title":"XAM.SAM.templength","text":"templength(record::Record)::Int\n\nGet the template length of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.sequence","page":"SAM and BAM","title":"XAM.SAM.sequence","text":"sequence(record::Record)::BioSequences.DNASequence\n\nGet the segment sequence of record.\n\n\n\n\n\nsequence(::Type{String}, record::Record)::String\n\nGet the segment sequence of record as String.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.seqlength","page":"SAM and BAM","title":"XAM.SAM.seqlength","text":"seqlength(record::Record)::Int\n\nGet the sequence length of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.quality","page":"SAM and BAM","title":"XAM.SAM.quality","text":"quality(record::Record)::Vector{UInt8}\n\nGet the Phred-scaled base quality of record.\n\n\n\n\n\nquality(::Type{String}, record::Record)::String\n\nGet the ASCII-encoded base quality of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.auxdata","page":"SAM and BAM","title":"XAM.SAM.auxdata","text":"auxdata(record::Record)::Dict{String,Any}\n\nGet the auxiliary data (optional fields) of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"BioAlignments supports the following accessors for BAM.Record types.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"XAM.BAM.flag\nXAM.BAM.ismapped\nXAM.BAM.isprimary\nXAM.BAM.refid\nXAM.BAM.refname\nXAM.BAM.reflen\nXAM.BAM.position\nXAM.BAM.rightposition\nXAM.BAM.isnextmapped\nXAM.BAM.nextrefid\nXAM.BAM.nextrefname\nXAM.BAM.nextposition\nXAM.BAM.mappingquality\nXAM.BAM.cigar\nXAM.BAM.alignment\nXAM.BAM.alignlength\nXAM.BAM.tempname\nXAM.BAM.templength\nXAM.BAM.sequence\nXAM.BAM.seqlength\nXAM.BAM.quality\nXAM.BAM.auxdata","category":"page"},{"location":"hts-files/#XAM.BAM.flag","page":"SAM and BAM","title":"XAM.BAM.flag","text":"flag(record::Record)::UInt16\n\nGet the bitwise flag of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.ismapped","page":"SAM and BAM","title":"XAM.BAM.ismapped","text":"ismapped(record::Record)::Bool\n\nTest if record is mapped.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.isprimary","page":"SAM and BAM","title":"XAM.BAM.isprimary","text":"isprimary(record::Record)::Bool\n\nTest if record is a primary line of the read.\n\nThis is equivalent to flag(record) & 0x900 == 0.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.refid","page":"SAM and BAM","title":"XAM.BAM.refid","text":"refid(record::Record)::Int\n\nGet the reference sequence ID of record.\n\nThe ID is 1-based (i.e. the first sequence is 1) and is 0 for a record without a mapping position.\n\nSee also: BAM.rname\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.refname","page":"SAM and BAM","title":"XAM.BAM.refname","text":"refname(record::Record)::String\n\nGet the reference sequence name of record.\n\nSee also: BAM.refid\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.reflen","page":"SAM and BAM","title":"XAM.BAM.reflen","text":"reflen(record::Record)::Int\n\nGet the length of the reference sequence this record applies to.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.position","page":"SAM and BAM","title":"XAM.BAM.position","text":"position(record::Record)::Int\n\nGet the 1-based leftmost mapping position of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.rightposition","page":"SAM and BAM","title":"XAM.BAM.rightposition","text":"rightposition(record::Record)::Int\n\nGet the 1-based rightmost mapping position of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.isnextmapped","page":"SAM and BAM","title":"XAM.BAM.isnextmapped","text":"isnextmapped(record::Record)::Bool\n\nTest if the mate/next read of record is mapped.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.nextrefid","page":"SAM and BAM","title":"XAM.BAM.nextrefid","text":"nextrefid(record::Record)::Int\n\nGet the next/mate reference sequence ID of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.nextrefname","page":"SAM and BAM","title":"XAM.BAM.nextrefname","text":"nextrefname(record::Record)::String\n\nGet the reference name of the mate/next read of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.nextposition","page":"SAM and BAM","title":"XAM.BAM.nextposition","text":"nextposition(record::Record)::Int\n\nGet the 1-based leftmost mapping position of the next/mate read of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.mappingquality","page":"SAM and BAM","title":"XAM.BAM.mappingquality","text":"mappingquality(record::Record)::UInt8\n\nGet the mapping quality of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.cigar","page":"SAM and BAM","title":"XAM.BAM.cigar","text":"cigar(record::Record)::String\n\nGet the CIGAR string of record.\n\nNote that in the BAM specification, the field called cigar typically stores the cigar string of the record. However, this is not always true, sometimes the true cigar is very long, and due to some constraints of the BAM format, the actual cigar string is stored in an extra tag: CG:B,I, and the cigar field stores a pseudo-cigar string.\n\nCalling this method with checkCG set to true (default) this method will always yield the true cigar string, because this is probably what you want the vast majority of the time.\n\nIf you have a record that stores the true cigar in a CG:B,I tag, but you still want to access the pseudo-cigar that is stored in the cigar field of the BAM record, then you can set checkCG to false.\n\nSee also BAM.cigar_rle.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.alignment","page":"SAM and BAM","title":"XAM.BAM.alignment","text":"alignment(record::Record)::BioAlignments.Alignment\n\nGet the alignment of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.alignlength","page":"SAM and BAM","title":"XAM.BAM.alignlength","text":"alignlength(record::Record)::Int\n\nGet the alignment length of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.tempname","page":"SAM and BAM","title":"XAM.BAM.tempname","text":"tempname(record::Record)::String\n\nGet the query template name of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.templength","page":"SAM and BAM","title":"XAM.BAM.templength","text":"templength(record::Record)::Int\n\nGet the template length of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.sequence","page":"SAM and BAM","title":"XAM.BAM.sequence","text":"sequence(record::Record)::BioSequences.DNASequence\n\nGet the segment sequence of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.seqlength","page":"SAM and BAM","title":"XAM.BAM.seqlength","text":"seqlength(record::Record)::Int\n\nGet the sequence length of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.quality","page":"SAM and BAM","title":"XAM.BAM.quality","text":"quality(record::Record)::Vector{UInt8}\n\nGet the base quality of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.auxdata","page":"SAM and BAM","title":"XAM.BAM.auxdata","text":"auxdata(record::Record)::BAM.AuxData\n\nGet the auxiliary data of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#Accessing-auxiliary-data-1","page":"SAM and BAM","title":"Accessing auxiliary data","text":"","category":"section"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"SAM and BAM records support the storing of optional data fields associated with tags.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"Tagged auxiliary data follows a format of TAG:TYPE:VALUE. TAG is a two-letter string, and each tag can only appear once per record. TYPE is a single case-sensetive letter which defined the format of VALUE.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"Type Description\n'A' Printable character\n'i' Signed integer\n'f' Single-precision floating number\n'Z' Printable string, including space\n'H' Byte array in Hex format\n'B' Integer of numeric array","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"For more information about these tags and their types we refer you to the [SAM/BAM specification][samtools-spec] and the additional [optional fields specification][samtags] document.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"There are some tags that are reserved, predefined standard tags, for specific uses.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"To access optional fields stored in tags, you use getindex indexing syntax on the record object. Note that accessing optional tag fields will result in type instability in Julia. This is because the type of the optional data is not known until run-time, as the tag is being read. This can have a significant impact on performance. To limit this, if the user knows the type of a value in advance, specifying it as a type annotation will alleviate the problem:","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"Below is an example of looping over records in a bam file and using indexing syntax to get the data stored in the \"NM\" tag. Note the UInt8 type assertion to alleviate type instability.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"for record in open(BAM.Reader, \"data.bam\")\n nm = record[\"NM\"]::UInt8\n # do something\nend","category":"page"},{"location":"hts-files/#Getting-records-in-a-range-1","page":"SAM and BAM","title":"Getting records in a range","text":"","category":"section"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"BioAlignments supports the BAI index to fetch records in a specific range from a BAM file. [Samtools][samtools] provides index subcommand to create an index file (.bai) from a sorted BAM file.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"$ samtools index -b SRR1238088.sort.bam\n$ ls SRR1238088.sort.bam*\nSRR1238088.sort.bam SRR1238088.sort.bam.bai","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"eachoverlap(reader, chrom, range) returns an iterator of BAM records overlapping the query interval:","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"reader = open(BAM.Reader, \"SRR1238088.sort.bam\", index=\"SRR1238088.sort.bam.bai\")\nfor record in eachoverlap(reader, \"Chr2\", 10000:11000)\n # `record` is a BAM.Record object\n # ...\nend\nclose(reader)","category":"page"},{"location":"hts-files/#Getting-records-overlapping-genomic-features-1","page":"SAM and BAM","title":"Getting records overlapping genomic features","text":"","category":"section"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"eachoverlap also accepts the Interval type defined in GenomicFeatures.jl.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"This allows you to do things like first read in the genomic features from a GFF3 file, and then for each feature, iterate over all the BAM records that overlap with that feature.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"# Load GFF3 module.\nusing GenomicFeatures\nusing BioAlignments\n\n# Load genomic features from a GFF3 file.\nfeatures = open(collect, GFF3.Reader, \"TAIR10_GFF3_genes.gff\")\n\n# Keep mRNA features.\nfilter!(x -> GFF3.featuretype(x) == \"mRNA\", features)\n\n# Open a BAM file and iterate over records overlapping mRNA transcripts.\nreader = open(BAM.Reader, \"SRR1238088.sort.bam\", index = \"SRR1238088.sort.bam.bai\")\nfor feature in features\n for record in eachoverlap(reader, feature)\n # `record` overlaps `feature`.\n # ...\n end\nend\nclose(reader)","category":"page"},{"location":"hts-files/#Writing-files-1","page":"SAM and BAM","title":"Writing files","text":"","category":"section"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"In order to write a BAM or SAM file, you must first create a SAM.Header.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"A SAM.Header is constructed from a vector of SAM.MetaInfo objects.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"For example, to create the following simple header:","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"@HD VN:1.6 SO:coordinate\n@SQ SN:ref LN:45","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"julia> a = SAM.MetaInfo(\"HD\", [\"VN\" => 1.6, \"SO\" => \"coordinate\"])\nSAM.MetaInfo:\n tag: HD\n value: VN=1.6 SO=coordinate\n\njulia> b = SAM.MetaInfo(\"SQ\", [\"SN\" => \"ref\", \"LN\" => 45])\nSAM.MetaInfo:\n tag: SQ\n value: SN=ref LN=45\n\njulia> h = SAM.Header([a, b])\nSAM.Header(SAM.MetaInfo[SAM.MetaInfo:\n tag: HD\n value: VN=1.6 SO=coordinate, SAM.MetaInfo:\n tag: SQ\n value: SN=ref LN=45])\n","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"Then to create the writer for a SAM file, construct a SAM.Writer using the header and an IO type:","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"julia> samw = SAM.Writer(open(\"my-data.sam\", \"w\"), h)\nSAM.Writer(IOStream())\n","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"To make a BAM Writer is slightly different, as you need to use a specific stream type from the [BGZFStreams][bgzfstreams] package:","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"julia> using BGZFStreams\n\njulia> bamw = BAM.Writer(BGZFStream(open(\"my-data.bam\", \"w\"), \"w\"))\nBAM.Writer(BGZFStreams.BGZFStream{IOStream}())\n","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"Once you have a BAM or SAM writer, you can use the write method to write BAM.Records or SAM.Records to file:","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"julia> write(bamw, rec) # Here rec is a `BAM.Record`\n330780","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"[samtools]: https://samtools.github.io/ [samtools-spec]: https://samtools.github.io/hts-specs/SAMv1.pdf [samtags]: https://samtools.github.io/hts-specs/SAMtags.pdf [bgzfstreams]: https://github.com/BioJulia/BGZFStreams.jl","category":"page"},{"location":"api/public/#","page":"Public","title":"Public","text":"CurrentModule = XAM\nDocTestSetup = quote\n using XAM\nend","category":"page"},{"location":"api/public/#Public-API-Reference-1","page":"Public","title":"Public API Reference","text":"","category":"section"},{"location":"api/public/#Contents-1","page":"Public","title":"Contents","text":"","category":"section"},{"location":"api/public/#","page":"Public","title":"Public","text":"Pages = [\"public.md\"]","category":"page"},{"location":"api/public/#","page":"Public","title":"Public","text":"Pages = [\"public.md\"]","category":"page"},{"location":"api/public/#SAM-API-1","page":"Public","title":"SAM API","text":"","category":"section"},{"location":"api/public/#","page":"Public","title":"Public","text":"The following methods and types are provided by the SAM submodule for public use.","category":"page"},{"location":"api/public/#","page":"Public","title":"Public","text":"Modules = [XAM.SAM]\nprivate = false","category":"page"},{"location":"api/public/#XAM.SAM.FLAG_DUP","page":"Public","title":"XAM.SAM.FLAG_DUP","text":"0x0400: optical or PCR duplicate\n\n\n\n\n\n","category":"constant"},{"location":"api/public/#XAM.SAM.FLAG_MREVERSE","page":"Public","title":"XAM.SAM.FLAG_MREVERSE","text":"0x0020: the mate is mapped to the reverse strand\n\n\n\n\n\n","category":"constant"},{"location":"api/public/#XAM.SAM.FLAG_MUNMAP","page":"Public","title":"XAM.SAM.FLAG_MUNMAP","text":"0x0008: the mate is unmapped\n\n\n\n\n\n","category":"constant"},{"location":"api/public/#XAM.SAM.FLAG_PAIRED","page":"Public","title":"XAM.SAM.FLAG_PAIRED","text":"0x0001: the read is paired in sequencing, no matter whether it is mapped in a pair\n\n\n\n\n\n","category":"constant"},{"location":"api/public/#XAM.SAM.FLAG_PROPER_PAIR","page":"Public","title":"XAM.SAM.FLAG_PROPER_PAIR","text":"0x0002: the read is mapped in a proper pair\n\n\n\n\n\n","category":"constant"},{"location":"api/public/#XAM.SAM.FLAG_QCFAIL","page":"Public","title":"XAM.SAM.FLAG_QCFAIL","text":"0x0200: QC failure\n\n\n\n\n\n","category":"constant"},{"location":"api/public/#XAM.SAM.FLAG_READ1","page":"Public","title":"XAM.SAM.FLAG_READ1","text":"0x0040: this is read1\n\n\n\n\n\n","category":"constant"},{"location":"api/public/#XAM.SAM.FLAG_READ2","page":"Public","title":"XAM.SAM.FLAG_READ2","text":"0x0080: this is read2\n\n\n\n\n\n","category":"constant"},{"location":"api/public/#XAM.SAM.FLAG_REVERSE","page":"Public","title":"XAM.SAM.FLAG_REVERSE","text":"0x0010: the read is mapped to the reverse strand\n\n\n\n\n\n","category":"constant"},{"location":"api/public/#XAM.SAM.FLAG_SECONDARY","page":"Public","title":"XAM.SAM.FLAG_SECONDARY","text":"0x0100: not primary alignment\n\n\n\n\n\n","category":"constant"},{"location":"api/public/#XAM.SAM.FLAG_SUPPLEMENTARY","page":"Public","title":"XAM.SAM.FLAG_SUPPLEMENTARY","text":"0x0800: supplementary alignment\n\n\n\n\n\n","category":"constant"},{"location":"api/public/#XAM.SAM.FLAG_UNMAP","page":"Public","title":"XAM.SAM.FLAG_UNMAP","text":"0x0004: the read itself is unmapped; conflictive with SAM.FLAGPROPERPAIR\n\n\n\n\n\n","category":"constant"},{"location":"api/public/#XAM.SAM.Header-Tuple{}","page":"Public","title":"XAM.SAM.Header","text":"SAM.Header()\n\nCreate an empty header.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.MetaInfo-Tuple{AbstractString,Any}","page":"Public","title":"XAM.SAM.MetaInfo","text":"MetaInfo(tag::AbstractString, value)\n\nCreate a SAM metainfo with tag and value.\n\ntag is a two-byte ASCII string. If tag is \"CO\", value must be a string; otherwise, value is an iterable object with key and value pairs.\n\nExamples\n\njulia> SAM.MetaInfo(\"CO\", \"some comment\")\nBioAlignments.SAM.MetaInfo:\n tag: CO\n value: some comment\n\njulia> string(ans)\n\"@CO\tsome comment\"\n\njulia> SAM.MetaInfo(\"SQ\", [\"SN\" => \"chr1\", \"LN\" => 12345])\nBioAlignments.SAM.MetaInfo:\n tag: SQ\n value: SN=chr1 LN=12345\n\njulia> string(ans)\n\"@SQ\tSN:chr1\tLN:12345\"\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.MetaInfo-Tuple{AbstractString}","page":"Public","title":"XAM.SAM.MetaInfo","text":"MetaInfo(str::AbstractString)\n\nCreate a SAM metainfo from str.\n\nExamples\n\njulia> SAM.MetaInfo(\"@CO\tsome comment\")\nBioAlignments.SAM.MetaInfo:\n tag: CO\n value: some comment\n\njulia> SAM.MetaInfo(\"@SQ\tSN:chr1\tLN:12345\")\nBioAlignments.SAM.MetaInfo:\n tag: SQ\n value: SN=chr1 LN=12345\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.Reader-Tuple{IO}","page":"Public","title":"XAM.SAM.Reader","text":"SAM.Reader(input::IO)\n\nCreate a data reader of the SAM file format.\n\nArguments\n\ninput: data source\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.Record-Tuple{AbstractString}","page":"Public","title":"XAM.SAM.Record","text":"SAM.Record(str::AbstractString)\n\nCreate a SAM record from str. This function verifies the format and indexes fields for accessors.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.Record-Tuple{Array{UInt8,1}}","page":"Public","title":"XAM.SAM.Record","text":"SAM.Record(data::Vector{UInt8})\n\nCreate a SAM record from data. This function verifies the format and indexes fields for accessors. Note that the ownership of data is transferred to a new record object.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.Record-Tuple{}","page":"Public","title":"XAM.SAM.Record","text":"SAM.Record()\n\nCreate an unfilled SAM record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.Writer","page":"Public","title":"XAM.SAM.Writer","text":"Writer(output::IO, header::Header=Header())\n\nCreate a data writer of the SAM file format.\n\nArguments\n\noutput: data sink\nheader=Header(): SAM header object\n\n\n\n\n\n","category":"type"},{"location":"api/public/#Base.findall-Tuple{XAM.SAM.Header,AbstractString}","page":"Public","title":"Base.findall","text":"find(header::Header, key::AbstractString)::Vector{MetaInfo}\n\nFind metainfo objects satisfying SAM.tag(metainfo) == key.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#BioCore.header-Tuple{XAM.SAM.Reader}","page":"Public","title":"BioCore.header","text":"header(reader::Reader)::Header\n\nGet the header of reader.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.alignlength-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.alignlength","text":"alignlength(record::Record)::Int\n\nGet the alignment length of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.alignment-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.alignment","text":"alignment(record::Record)::BioAlignments.Alignment\n\nGet the alignment of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.auxdata-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.auxdata","text":"auxdata(record::Record)::Dict{String,Any}\n\nGet the auxiliary data (optional fields) of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.cigar-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.cigar","text":"cigar(record::Record)::String\n\nGet the CIGAR string of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.flag-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.flag","text":"flag(record::Record)::UInt16\n\nGet the bitwise flag of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.iscomment-Tuple{XAM.SAM.MetaInfo}","page":"Public","title":"XAM.SAM.iscomment","text":"iscomment(metainfo::MetaInfo)::Bool\n\nTest if metainfo is a comment (i.e. its tag is \"CO\").\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.ismapped-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.ismapped","text":"ismapped(record::Record)::Bool\n\nTest if record is mapped.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.isnextmapped-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.isnextmapped","text":"isnextmapped(record::Record)::Bool\n\nTest if the mate/next read of record is mapped.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.isprimary-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.isprimary","text":"isprimary(record::Record)::Bool\n\nTest if record is a primary line of the read.\n\nThis is equivalent to flag(record) & 0x900 == 0.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.keyvalues-Tuple{XAM.SAM.MetaInfo}","page":"Public","title":"XAM.SAM.keyvalues","text":"keyvalues(metainfo::MetaInfo)::Vector{Pair{String,String}}\n\nGet the values of metainfo as string pairs.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.mappingquality-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.mappingquality","text":"mappingquality(record::Record)::UInt8\n\nGet the mapping quality of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.nextposition-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.nextposition","text":"nextposition(record::Record)::Int\n\nGet the position of the mate/next read of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.nextrefname-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.nextrefname","text":"nextrefname(record::Record)::String\n\nGet the reference name of the mate/next read of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.position-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.position","text":"position(record::Record)::Int\n\nGet the 1-based leftmost mapping position of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.quality-Tuple{Type{String},XAM.SAM.Record}","page":"Public","title":"XAM.SAM.quality","text":"quality(::Type{String}, record::Record)::String\n\nGet the ASCII-encoded base quality of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.quality-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.quality","text":"quality(record::Record)::Vector{UInt8}\n\nGet the Phred-scaled base quality of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.refname-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.refname","text":"refname(record::Record)::String\n\nGet the reference sequence name of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.rightposition-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.rightposition","text":"rightposition(record::Record)::Int\n\nGet the 1-based rightmost mapping position of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.seqlength-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.seqlength","text":"seqlength(record::Record)::Int\n\nGet the sequence length of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.sequence-Tuple{Type{String},XAM.SAM.Record}","page":"Public","title":"XAM.SAM.sequence","text":"sequence(::Type{String}, record::Record)::String\n\nGet the segment sequence of record as String.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.sequence-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.sequence","text":"sequence(record::Record)::BioSequences.DNASequence\n\nGet the segment sequence of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.tag-Tuple{XAM.SAM.MetaInfo}","page":"Public","title":"XAM.SAM.tag","text":"tag(metainfo::MetaInfo)::String\n\nGet the tag of metainfo.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.templength-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.templength","text":"templength(record::Record)::Int\n\nGet the template length of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.tempname-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.tempname","text":"tempname(record::Record)::String\n\nGet the query template name of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.value-Tuple{XAM.SAM.MetaInfo}","page":"Public","title":"XAM.SAM.value","text":"value(metainfo::MetaInfo)::String\n\nGet the value of metainfo as a string.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#BAM-API-1","page":"Public","title":"BAM API","text":"","category":"section"},{"location":"api/public/#","page":"Public","title":"Public","text":"The following methods and types are provided by the BAM submodule for public use.","category":"page"},{"location":"api/public/#","page":"Public","title":"Public","text":"Modules = [XAM.BAM]\nprivate = false","category":"page"},{"location":"api/public/#XAM.BAM.BAI-Tuple{AbstractString}","page":"Public","title":"XAM.BAM.BAI","text":"BAI(filename::AbstractString)\n\nLoad a BAI index from filename.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.BAI-Tuple{IO}","page":"Public","title":"XAM.BAM.BAI","text":"BAI(input::IO)\n\nLoad a BAI index from input.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.Reader","page":"Public","title":"XAM.BAM.Reader","text":"BAM.Reader(input::IO; index=nothing)\n\nCreate a data reader of the BAM file format.\n\nArguments\n\ninput: data source\nindex=nothing: filepath to a random access index (currently bai is supported)\n\n\n\n\n\n","category":"type"},{"location":"api/public/#XAM.BAM.Record","page":"Public","title":"XAM.BAM.Record","text":"BAM.Record()\n\nCreate an unfilled BAM record.\n\n\n\n\n\n","category":"type"},{"location":"api/public/#XAM.BAM.Writer","page":"Public","title":"XAM.BAM.Writer","text":"BAM.Writer(output::BGZFStream, header::SAM.Header)\n\nCreate a data writer of the BAM file format.\n\nArguments\n\noutput: data sink\nheader: SAM header object\n\n\n\n\n\n","category":"type"},{"location":"api/public/#BioCore.header-Tuple{XAM.BAM.Reader}","page":"Public","title":"BioCore.header","text":"header(reader::Reader; fillSQ::Bool=false)::SAM.Header\n\nGet the header of reader.\n\nIf fillSQ is true, this function fills missing \"SQ\" metainfo in the header.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.alignlength-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.alignlength","text":"alignlength(record::Record)::Int\n\nGet the alignment length of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.alignment-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.alignment","text":"alignment(record::Record)::BioAlignments.Alignment\n\nGet the alignment of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.auxdata-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.auxdata","text":"auxdata(record::Record)::BAM.AuxData\n\nGet the auxiliary data of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.cigar","page":"Public","title":"XAM.BAM.cigar","text":"cigar(record::Record)::String\n\nGet the CIGAR string of record.\n\nNote that in the BAM specification, the field called cigar typically stores the cigar string of the record. However, this is not always true, sometimes the true cigar is very long, and due to some constraints of the BAM format, the actual cigar string is stored in an extra tag: CG:B,I, and the cigar field stores a pseudo-cigar string.\n\nCalling this method with checkCG set to true (default) this method will always yield the true cigar string, because this is probably what you want the vast majority of the time.\n\nIf you have a record that stores the true cigar in a CG:B,I tag, but you still want to access the pseudo-cigar that is stored in the cigar field of the BAM record, then you can set checkCG to false.\n\nSee also BAM.cigar_rle.\n\n\n\n\n\n","category":"function"},{"location":"api/public/#XAM.BAM.cigar_rle","page":"Public","title":"XAM.BAM.cigar_rle","text":"cigar_rle(record::Record, checkCG::Bool = true)::Tuple{Vector{BioAlignments.Operation},Vector{Int}}\n\nGet a run-length encoded tuple (ops, lens) of the CIGAR string in record.\n\nNote that in the BAM specification, the field called cigar typically stores the cigar string of the record. However, this is not always true, sometimes the true cigar is very long, and due to some constraints of the BAM format, the actual cigar string is stored in an extra tag: CG:B,I, and the cigar field stores a pseudo-cigar string.\n\nCalling this method with checkCG set to true (default) this method will always yield the true cigar string, because this is probably what you want the vast majority of the time.\n\nIf you have a record that stores the true cigar in a CG:B,I tag, but you still want to access the pseudo-cigar that is stored in the cigar field of the BAM record, then you can set checkCG to false.\n\nSee also BAM.cigar.\n\n\n\n\n\n","category":"function"},{"location":"api/public/#XAM.BAM.flag-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.flag","text":"flag(record::Record)::UInt16\n\nGet the bitwise flag of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.ismapped-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.ismapped","text":"ismapped(record::Record)::Bool\n\nTest if record is mapped.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.isnextmapped-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.isnextmapped","text":"isnextmapped(record::Record)::Bool\n\nTest if the mate/next read of record is mapped.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.ispositivestrand-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.ispositivestrand","text":"ispositivestrand(record::Record)::Bool\n\nTest if record is aligned to the positive strand.\n\nThis is equivalent to flag(record) & 0x10 == 0.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.isprimary-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.isprimary","text":"isprimary(record::Record)::Bool\n\nTest if record is a primary line of the read.\n\nThis is equivalent to flag(record) & 0x900 == 0.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.mappingquality-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.mappingquality","text":"mappingquality(record::Record)::UInt8\n\nGet the mapping quality of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.n_cigar_op","page":"Public","title":"XAM.BAM.n_cigar_op","text":"n_cigar_op(record::Record, checkCG::Bool = true)\n\nReturn the number of operations in the CIGAR string of record.\n\nNote that in the BAM specification, the field called cigar typically stores the cigar string of the record. However, this is not always true, sometimes the true cigar is very long, and due to some constraints of the BAM format, the actual cigar string is stored in an extra tag: CG:B,I, and the cigar field stores a pseudo-cigar string.\n\nCalling this method with checkCG set to true (default) this method will always yield the number of operations in the true cigar string, because this is probably what you want, the vast majority of the time.\n\nIf you have a record that stores the true cigar in a CG:B,I tag, but you still want to get the number of operations in the cigar field of the BAM record, then set checkCG to false.\n\n\n\n\n\n","category":"function"},{"location":"api/public/#XAM.BAM.nextposition-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.nextposition","text":"nextposition(record::Record)::Int\n\nGet the 1-based leftmost mapping position of the next/mate read of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.nextrefid-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.nextrefid","text":"nextrefid(record::Record)::Int\n\nGet the next/mate reference sequence ID of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.nextrefname-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.nextrefname","text":"nextrefname(record::Record)::String\n\nGet the reference name of the mate/next read of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.position-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.position","text":"position(record::Record)::Int\n\nGet the 1-based leftmost mapping position of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.quality-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.quality","text":"quality(record::Record)::Vector{UInt8}\n\nGet the base quality of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.refid-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.refid","text":"refid(record::Record)::Int\n\nGet the reference sequence ID of record.\n\nThe ID is 1-based (i.e. the first sequence is 1) and is 0 for a record without a mapping position.\n\nSee also: BAM.rname\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.reflen-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.reflen","text":"reflen(record::Record)::Int\n\nGet the length of the reference sequence this record applies to.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.refname-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.refname","text":"refname(record::Record)::String\n\nGet the reference sequence name of record.\n\nSee also: BAM.refid\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.rightposition-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.rightposition","text":"rightposition(record::Record)::Int\n\nGet the 1-based rightmost mapping position of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.seqlength-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.seqlength","text":"seqlength(record::Record)::Int\n\nGet the sequence length of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.sequence-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.sequence","text":"sequence(record::Record)::BioSequences.DNASequence\n\nGet the segment sequence of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.templength-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.templength","text":"templength(record::Record)::Int\n\nGet the template length of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.tempname-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.tempname","text":"tempname(record::Record)::String\n\nGet the query template name of record.\n\n\n\n\n\n","category":"method"}]
+[{"location":"#XAM-1","page":"Home","title":"XAM","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"(Image: Latest Release) (Image: MIT license) (Image: Stable documentation) (Image: Latest documentation) (Image: Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.)","category":"page"},{"location":"#","page":"Home","title":"Home","text":"(Image: Chat)","category":"page"},{"location":"#Description-1","page":"Home","title":"Description","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"XAM provides I/O and utilities for manipulating SAM and BAM formatted alignment map files.","category":"page"},{"location":"#Installation-1","page":"Home","title":"Installation","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"XAM is made available to install through BioJulia's package registry.","category":"page"},{"location":"#","page":"Home","title":"Home","text":"Julia by default only watches the \"General\" package registry, so before you start, you should add the BioJulia package registry.","category":"page"},{"location":"#","page":"Home","title":"Home","text":"Start a julia terminal, hit the ] key to enter pkg mode (you should see the prompt change from julia> to pkg> ), then enter the following command:","category":"page"},{"location":"#","page":"Home","title":"Home","text":"registry add https://github.com/BioJulia/BioJuliaRegistry.git","category":"page"},{"location":"#","page":"Home","title":"Home","text":"After you've added the registry, you can install XAM from the julia REPL. Press ] to enter pkg mode again, and enter the following:","category":"page"},{"location":"#","page":"Home","title":"Home","text":"add XAM","category":"page"},{"location":"#","page":"Home","title":"Home","text":"If you are interested in the cutting edge of the development, please check out the develop branch to try new features before release.","category":"page"},{"location":"#Testing-1","page":"Home","title":"Testing","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"XAM is tested against Julia 1.X on Linux, OS X, and Windows.","category":"page"},{"location":"#","page":"Home","title":"Home","text":"Latest build status:","category":"page"},{"location":"#","page":"Home","title":"Home","text":"(Image: ) (Image: Build status) (Image: codecov)","category":"page"},{"location":"#Contributing-1","page":"Home","title":"Contributing","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"We appreciate contributions from users including reporting bugs, fixing issues, improving performance and adding new features.","category":"page"},{"location":"#","page":"Home","title":"Home","text":"Take a look at the contributing files detailed contributor and maintainer guidelines, and code of conduct.","category":"page"},{"location":"#Financial-contributions-1","page":"Home","title":"Financial contributions","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"We also welcome financial contributions in full transparency on our open collective. Anyone can file an expense. If the expense makes sense for the development of the community, it will be \"merged\" in the ledger of our open collective by the core contributors and the person who filed the expense will be reimbursed.","category":"page"},{"location":"#Backers-and-Sponsors-1","page":"Home","title":"Backers & Sponsors","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"Thank you to all our backers and sponsors!","category":"page"},{"location":"#","page":"Home","title":"Home","text":"Love our work and community? Become a backer.","category":"page"},{"location":"#","page":"Home","title":"Home","text":"(Image: backers)","category":"page"},{"location":"#","page":"Home","title":"Home","text":"Does your company use BioJulia? Help keep BioJulia feature rich and healthy by sponsoring the project Your logo will show up here with a link to your website.","category":"page"},{"location":"#","page":"Home","title":"Home","text":"(Image: ) (Image: ) (Image: ) (Image: ) (Image: ) (Image: ) (Image: ) (Image: ) (Image: ) (Image: )","category":"page"},{"location":"#Questions?-1","page":"Home","title":"Questions?","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"If you have a question about contributing or using BioJulia software, come on over and chat to us on Gitter, or you can try the Bio category of the Julia discourse site.","category":"page"},{"location":"hts-files/#SAM-and-BAM-1","page":"SAM and BAM","title":"SAM and BAM","text":"","category":"section"},{"location":"hts-files/#Introduction-1","page":"SAM and BAM","title":"Introduction","text":"","category":"section"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"High-throughput sequencing (HTS) technologies generate a large amount of data in the form of a large number of nucleotide sequencing reads. One of the most common tasks in bioinformatics is to align these reads against known reference genomes, chromosomes, or contigs. BioAlignments provides several data formats commonly used for this kind of task.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"BioAlignments offers high-performance tools for SAM and BAM file formats, which are the most popular file formats.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"If you have questions about the SAM and BAM formats or any of the terminology used when discussing these formats, see the published [specification][samtools-spec], which is maintained by the [samtools group][samtools].","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"A very very simple SAM file looks like the following:","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"@HD VN:1.6 SO:coordinate\n@SQ SN:ref LN:45\nr001 99 ref 7 30 8M2I4M1D3M = 37 39 TTAGATAAAGGATACTG *\nr002 0 ref 9 30 3S6M1P1I4M * 0 0 AAAAGATAAGGATA *\nr003 0 ref 9 30 5S6M * 0 0 GCCTAAGCTAA * SA:Z:ref,29,-,6H5M,17,0;\nr004 0 ref 16 30 6M14N5M * 0 0 ATAGCTTCAGC *\nr003 2064 ref 29 17 6H5M * 0 0 TAGGC * SA:Z:ref,9,+,5S6M,30,1;\nr001 147 ref 37 30 9M = 7 -39 CAGCGGCAT * NM:i:1","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"Where the first two lines are part of the \"header\", and the following lines are \"records\". Each record describes how a read aligns to some reference sequence. Sometimes one record describes one read, but there are other cases like chimeric reads and split alignments, where multiple records apply to one read. In the example above, r003 is a chimeric read, and r004 is a split alignment, and r001 are mate pair reads. Again, we refer you to the official [specification][samtools-spec] for more details.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"A BAM file stores this same information but in a binary and compressible format that does not make for pretty printing here!","category":"page"},{"location":"hts-files/#Reading-SAM-and-BAM-files-1","page":"SAM and BAM","title":"Reading SAM and BAM files","text":"","category":"section"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"A typical script iterating over all records in a file looks like below:","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"using BioAlignments\n\n# Open a BAM file.\nreader = open(BAM.Reader, \"data.bam\")\n\n# Iterate over BAM records.\nfor record in reader\n # `record` is a BAM.Record object.\n if BAM.ismapped(record)\n # Print the mapped position.\n println(BAM.refname(record), ':', BAM.position(record))\n end\nend\n\n# Close the BAM file.\nclose(reader)","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"The size of a BAM file is often extremely large. The iterator interface demonstrated above allocates an object for each record and that may be a bottleneck of reading data from a BAM file. In-place reading reuses a pre-allocated object for every record and less memory allocation happens in reading:","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"reader = open(BAM.Reader, \"data.bam\")\nrecord = BAM.Record()\nwhile !eof(reader)\n read!(reader, record)\n # do something\nend","category":"page"},{"location":"hts-files/#SAM-and-BAM-Headers-1","page":"SAM and BAM","title":"SAM and BAM Headers","text":"","category":"section"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"Both SAM.Reader and BAM.Reader implement the header function, which returns a SAM.Header object. To extract certain information out of the headers, you can use the find method on the header to extract information according to SAM/BAM tag. Again we refer you to the [specification][samtools-spec] for full details of all the different tags that can occur in headers, and what they mean.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"Below is an example of extracting all the info about the reference sequences from the BAM header. In SAM/BAM, any description of a reference sequence is stored in the header, under a tag denoted SQ (think reference SeQuence!).","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"julia> reader = open(SAM.Reader, \"data.sam\");\n\njulia> find(header(reader), \"SQ\")\n7-element Array{Bio.Align.SAM.MetaInfo,1}:\n Bio.Align.SAM.MetaInfo:\n tag: SQ\n value: SN=Chr1 LN=30427671\n Bio.Align.SAM.MetaInfo:\n tag: SQ\n value: SN=Chr2 LN=19698289\n Bio.Align.SAM.MetaInfo:\n tag: SQ\n value: SN=Chr3 LN=23459830\n Bio.Align.SAM.MetaInfo:\n tag: SQ\n value: SN=Chr4 LN=18585056\n Bio.Align.SAM.MetaInfo:\n tag: SQ\n value: SN=Chr5 LN=26975502\n Bio.Align.SAM.MetaInfo:\n tag: SQ\n value: SN=chloroplast LN=154478\n Bio.Align.SAM.MetaInfo:\n tag: SQ\n value: SN=mitochondria LN=366924\n","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"In the above we can see there were 7 sequences in the reference: 5 chromosomes, one chloroplast sequence, and one mitochondrial sequence.","category":"page"},{"location":"hts-files/#SAM-and-BAM-Records-1","page":"SAM and BAM","title":"SAM and BAM Records","text":"","category":"section"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"BioAlignments supports the following accessors for SAM.Record types.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"XAM.SAM.flag\nXAM.SAM.ismapped\nXAM.SAM.isprimary\nXAM.SAM.refname\nXAM.SAM.position\nXAM.SAM.rightposition\nXAM.SAM.isnextmapped\nXAM.SAM.nextrefname\nXAM.SAM.nextposition\nXAM.SAM.mappingquality\nXAM.SAM.cigar\nXAM.SAM.alignment\nXAM.SAM.alignlength\nXAM.SAM.tempname\nXAM.SAM.templength\nXAM.SAM.sequence\nXAM.SAM.seqlength\nXAM.SAM.quality\nXAM.SAM.auxdata","category":"page"},{"location":"hts-files/#XAM.SAM.flag","page":"SAM and BAM","title":"XAM.SAM.flag","text":"flag(record::Record)::UInt16\n\nGet the bitwise flag of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.ismapped","page":"SAM and BAM","title":"XAM.SAM.ismapped","text":"ismapped(record::Record)::Bool\n\nTest if record is mapped.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.isprimary","page":"SAM and BAM","title":"XAM.SAM.isprimary","text":"isprimary(record::Record)::Bool\n\nTest if record is a primary line of the read.\n\nThis is equivalent to flag(record) & 0x900 == 0.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.refname","page":"SAM and BAM","title":"XAM.SAM.refname","text":"refname(record::Record)::String\n\nGet the reference sequence name of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.position","page":"SAM and BAM","title":"XAM.SAM.position","text":"position(record::Record)::Int\n\nGet the 1-based leftmost mapping position of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.rightposition","page":"SAM and BAM","title":"XAM.SAM.rightposition","text":"rightposition(record::Record)::Int\n\nGet the 1-based rightmost mapping position of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.isnextmapped","page":"SAM and BAM","title":"XAM.SAM.isnextmapped","text":"isnextmapped(record::Record)::Bool\n\nTest if the mate/next read of record is mapped.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.nextrefname","page":"SAM and BAM","title":"XAM.SAM.nextrefname","text":"nextrefname(record::Record)::String\n\nGet the reference name of the mate/next read of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.nextposition","page":"SAM and BAM","title":"XAM.SAM.nextposition","text":"nextposition(record::Record)::Int\n\nGet the position of the mate/next read of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.mappingquality","page":"SAM and BAM","title":"XAM.SAM.mappingquality","text":"mappingquality(record::Record)::UInt8\n\nGet the mapping quality of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.cigar","page":"SAM and BAM","title":"XAM.SAM.cigar","text":"cigar(record::Record)::String\n\nGet the CIGAR string of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.alignment","page":"SAM and BAM","title":"XAM.SAM.alignment","text":"alignment(record::Record)::BioAlignments.Alignment\n\nGet the alignment of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.alignlength","page":"SAM and BAM","title":"XAM.SAM.alignlength","text":"alignlength(record::Record)::Int\n\nGet the alignment length of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.tempname","page":"SAM and BAM","title":"XAM.SAM.tempname","text":"tempname(record::Record)::String\n\nGet the query template name of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.templength","page":"SAM and BAM","title":"XAM.SAM.templength","text":"templength(record::Record)::Int\n\nGet the template length of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.sequence","page":"SAM and BAM","title":"XAM.SAM.sequence","text":"sequence(record::Record)::BioSequences.DNASequence\n\nGet the segment sequence of record.\n\n\n\n\n\nsequence(::Type{String}, record::Record)::String\n\nGet the segment sequence of record as String.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.seqlength","page":"SAM and BAM","title":"XAM.SAM.seqlength","text":"seqlength(record::Record)::Int\n\nGet the sequence length of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.quality","page":"SAM and BAM","title":"XAM.SAM.quality","text":"quality(record::Record)::Vector{UInt8}\n\nGet the Phred-scaled base quality of record.\n\n\n\n\n\nquality(::Type{String}, record::Record)::String\n\nGet the ASCII-encoded base quality of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.SAM.auxdata","page":"SAM and BAM","title":"XAM.SAM.auxdata","text":"auxdata(record::Record)::Dict{String,Any}\n\nGet the auxiliary data (optional fields) of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"BioAlignments supports the following accessors for BAM.Record types.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"XAM.BAM.flag\nXAM.BAM.ismapped\nXAM.BAM.isprimary\nXAM.BAM.refid\nXAM.BAM.refname\nXAM.BAM.reflen\nXAM.BAM.position\nXAM.BAM.rightposition\nXAM.BAM.isnextmapped\nXAM.BAM.nextrefid\nXAM.BAM.nextrefname\nXAM.BAM.nextposition\nXAM.BAM.mappingquality\nXAM.BAM.cigar\nXAM.BAM.alignment\nXAM.BAM.alignlength\nXAM.BAM.tempname\nXAM.BAM.templength\nXAM.BAM.sequence\nXAM.BAM.seqlength\nXAM.BAM.quality\nXAM.BAM.auxdata","category":"page"},{"location":"hts-files/#XAM.BAM.flag","page":"SAM and BAM","title":"XAM.BAM.flag","text":"flag(record::Record)::UInt16\n\nGet the bitwise flag of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.ismapped","page":"SAM and BAM","title":"XAM.BAM.ismapped","text":"ismapped(record::Record)::Bool\n\nTest if record is mapped.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.isprimary","page":"SAM and BAM","title":"XAM.BAM.isprimary","text":"isprimary(record::Record)::Bool\n\nTest if record is a primary line of the read.\n\nThis is equivalent to flag(record) & 0x900 == 0.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.refid","page":"SAM and BAM","title":"XAM.BAM.refid","text":"refid(record::Record)::Int\n\nGet the reference sequence ID of record.\n\nThe ID is 1-based (i.e. the first sequence is 1) and is 0 for a record without a mapping position.\n\nSee also: BAM.rname\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.refname","page":"SAM and BAM","title":"XAM.BAM.refname","text":"refname(record::Record)::String\n\nGet the reference sequence name of record.\n\nSee also: BAM.refid\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.reflen","page":"SAM and BAM","title":"XAM.BAM.reflen","text":"reflen(record::Record)::Int\n\nGet the length of the reference sequence this record applies to.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.position","page":"SAM and BAM","title":"XAM.BAM.position","text":"position(record::Record)::Int\n\nGet the 1-based leftmost mapping position of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.rightposition","page":"SAM and BAM","title":"XAM.BAM.rightposition","text":"rightposition(record::Record)::Int\n\nGet the 1-based rightmost mapping position of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.isnextmapped","page":"SAM and BAM","title":"XAM.BAM.isnextmapped","text":"isnextmapped(record::Record)::Bool\n\nTest if the mate/next read of record is mapped.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.nextrefid","page":"SAM and BAM","title":"XAM.BAM.nextrefid","text":"nextrefid(record::Record)::Int\n\nGet the next/mate reference sequence ID of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.nextrefname","page":"SAM and BAM","title":"XAM.BAM.nextrefname","text":"nextrefname(record::Record)::String\n\nGet the reference name of the mate/next read of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.nextposition","page":"SAM and BAM","title":"XAM.BAM.nextposition","text":"nextposition(record::Record)::Int\n\nGet the 1-based leftmost mapping position of the next/mate read of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.mappingquality","page":"SAM and BAM","title":"XAM.BAM.mappingquality","text":"mappingquality(record::Record)::UInt8\n\nGet the mapping quality of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.cigar","page":"SAM and BAM","title":"XAM.BAM.cigar","text":"cigar(record::Record)::String\n\nGet the CIGAR string of record.\n\nNote that in the BAM specification, the field called cigar typically stores the cigar string of the record. However, this is not always true, sometimes the true cigar is very long, and due to some constraints of the BAM format, the actual cigar string is stored in an extra tag: CG:B,I, and the cigar field stores a pseudo-cigar string.\n\nCalling this method with checkCG set to true (default) this method will always yield the true cigar string, because this is probably what you want the vast majority of the time.\n\nIf you have a record that stores the true cigar in a CG:B,I tag, but you still want to access the pseudo-cigar that is stored in the cigar field of the BAM record, then you can set checkCG to false.\n\nSee also BAM.cigar_rle.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.alignment","page":"SAM and BAM","title":"XAM.BAM.alignment","text":"alignment(record::Record)::BioAlignments.Alignment\n\nGet the alignment of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.alignlength","page":"SAM and BAM","title":"XAM.BAM.alignlength","text":"alignlength(record::Record)::Int\n\nGet the alignment length of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.tempname","page":"SAM and BAM","title":"XAM.BAM.tempname","text":"tempname(record::Record)::String\n\nGet the query template name of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.templength","page":"SAM and BAM","title":"XAM.BAM.templength","text":"templength(record::Record)::Int\n\nGet the template length of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.sequence","page":"SAM and BAM","title":"XAM.BAM.sequence","text":"sequence(record::Record)::BioSequences.DNASequence\n\nGet the segment sequence of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.seqlength","page":"SAM and BAM","title":"XAM.BAM.seqlength","text":"seqlength(record::Record)::Int\n\nGet the sequence length of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.quality","page":"SAM and BAM","title":"XAM.BAM.quality","text":"quality(record::Record)::Vector{UInt8}\n\nGet the base quality of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#XAM.BAM.auxdata","page":"SAM and BAM","title":"XAM.BAM.auxdata","text":"auxdata(record::Record)::BAM.AuxData\n\nGet the auxiliary data of record.\n\n\n\n\n\n","category":"function"},{"location":"hts-files/#Accessing-auxiliary-data-1","page":"SAM and BAM","title":"Accessing auxiliary data","text":"","category":"section"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"SAM and BAM records support the storing of optional data fields associated with tags.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"Tagged auxiliary data follows a format of TAG:TYPE:VALUE. TAG is a two-letter string, and each tag can only appear once per record. TYPE is a single case-sensetive letter which defined the format of VALUE.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"Type Description\n'A' Printable character\n'i' Signed integer\n'f' Single-precision floating number\n'Z' Printable string, including space\n'H' Byte array in Hex format\n'B' Integer of numeric array","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"For more information about these tags and their types we refer you to the [SAM/BAM specification][samtools-spec] and the additional [optional fields specification][samtags] document.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"There are some tags that are reserved, predefined standard tags, for specific uses.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"To access optional fields stored in tags, you use getindex indexing syntax on the record object. Note that accessing optional tag fields will result in type instability in Julia. This is because the type of the optional data is not known until run-time, as the tag is being read. This can have a significant impact on performance. To limit this, if the user knows the type of a value in advance, specifying it as a type annotation will alleviate the problem:","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"Below is an example of looping over records in a bam file and using indexing syntax to get the data stored in the \"NM\" tag. Note the UInt8 type assertion to alleviate type instability.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"for record in open(BAM.Reader, \"data.bam\")\n nm = record[\"NM\"]::UInt8\n # do something\nend","category":"page"},{"location":"hts-files/#Getting-records-in-a-range-1","page":"SAM and BAM","title":"Getting records in a range","text":"","category":"section"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"BioAlignments supports the BAI index to fetch records in a specific range from a BAM file. [Samtools][samtools] provides index subcommand to create an index file (.bai) from a sorted BAM file.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"$ samtools index -b SRR1238088.sort.bam\n$ ls SRR1238088.sort.bam*\nSRR1238088.sort.bam SRR1238088.sort.bam.bai","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"eachoverlap(reader, chrom, range) returns an iterator of BAM records overlapping the query interval:","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"reader = open(BAM.Reader, \"SRR1238088.sort.bam\", index=\"SRR1238088.sort.bam.bai\")\nfor record in eachoverlap(reader, \"Chr2\", 10000:11000)\n # `record` is a BAM.Record object\n # ...\nend\nclose(reader)","category":"page"},{"location":"hts-files/#Getting-records-overlapping-genomic-features-1","page":"SAM and BAM","title":"Getting records overlapping genomic features","text":"","category":"section"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"eachoverlap also accepts the Interval type defined in GenomicFeatures.jl.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"This allows you to do things like first read in the genomic features from a GFF3 file, and then for each feature, iterate over all the BAM records that overlap with that feature.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"# Load GFF3 module.\nusing GenomicFeatures\nusing BioAlignments\n\n# Load genomic features from a GFF3 file.\nfeatures = open(collect, GFF3.Reader, \"TAIR10_GFF3_genes.gff\")\n\n# Keep mRNA features.\nfilter!(x -> GFF3.featuretype(x) == \"mRNA\", features)\n\n# Open a BAM file and iterate over records overlapping mRNA transcripts.\nreader = open(BAM.Reader, \"SRR1238088.sort.bam\", index = \"SRR1238088.sort.bam.bai\")\nfor feature in features\n for record in eachoverlap(reader, feature)\n # `record` overlaps `feature`.\n # ...\n end\nend\nclose(reader)","category":"page"},{"location":"hts-files/#Writing-files-1","page":"SAM and BAM","title":"Writing files","text":"","category":"section"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"In order to write a BAM or SAM file, you must first create a SAM.Header.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"A SAM.Header is constructed from a vector of SAM.MetaInfo objects.","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"For example, to create the following simple header:","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"@HD VN:1.6 SO:coordinate\n@SQ SN:ref LN:45","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"julia> a = SAM.MetaInfo(\"HD\", [\"VN\" => 1.6, \"SO\" => \"coordinate\"])\nSAM.MetaInfo:\n tag: HD\n value: VN=1.6 SO=coordinate\n\njulia> b = SAM.MetaInfo(\"SQ\", [\"SN\" => \"ref\", \"LN\" => 45])\nSAM.MetaInfo:\n tag: SQ\n value: SN=ref LN=45\n\njulia> h = SAM.Header([a, b])\nSAM.Header(SAM.MetaInfo[SAM.MetaInfo:\n tag: HD\n value: VN=1.6 SO=coordinate, SAM.MetaInfo:\n tag: SQ\n value: SN=ref LN=45])\n","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"Then to create the writer for a SAM file, construct a SAM.Writer using the header and an IO type:","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"julia> samw = SAM.Writer(open(\"my-data.sam\", \"w\"), h)\nSAM.Writer(IOStream())\n","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"To make a BAM Writer is slightly different, as you need to use a specific stream type from the [BGZFStreams][bgzfstreams] package:","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"julia> using BGZFStreams\n\njulia> bamw = BAM.Writer(BGZFStream(open(\"my-data.bam\", \"w\"), \"w\"))\nBAM.Writer(BGZFStreams.BGZFStream{IOStream}())\n","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"Once you have a BAM or SAM writer, you can use the write method to write BAM.Records or SAM.Records to file:","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"julia> write(bamw, rec) # Here rec is a `BAM.Record`\n330780","category":"page"},{"location":"hts-files/#","page":"SAM and BAM","title":"SAM and BAM","text":"[samtools]: https://samtools.github.io/ [samtools-spec]: https://samtools.github.io/hts-specs/SAMv1.pdf [samtags]: https://samtools.github.io/hts-specs/SAMtags.pdf [bgzfstreams]: https://github.com/BioJulia/BGZFStreams.jl","category":"page"},{"location":"api/public/#","page":"Public","title":"Public","text":"CurrentModule = XAM\nDocTestSetup = quote\n using XAM\nend","category":"page"},{"location":"api/public/#Public-API-Reference-1","page":"Public","title":"Public API Reference","text":"","category":"section"},{"location":"api/public/#Contents-1","page":"Public","title":"Contents","text":"","category":"section"},{"location":"api/public/#","page":"Public","title":"Public","text":"Pages = [\"public.md\"]","category":"page"},{"location":"api/public/#","page":"Public","title":"Public","text":"Pages = [\"public.md\"]","category":"page"},{"location":"api/public/#SAM-API-1","page":"Public","title":"SAM API","text":"","category":"section"},{"location":"api/public/#","page":"Public","title":"Public","text":"The following methods and types are provided by the SAM submodule for public use.","category":"page"},{"location":"api/public/#","page":"Public","title":"Public","text":"Modules = [XAM.SAM]\nprivate = false","category":"page"},{"location":"api/public/#XAM.SAM.FLAG_DUP","page":"Public","title":"XAM.SAM.FLAG_DUP","text":"0x0400: optical or PCR duplicate\n\n\n\n\n\n","category":"constant"},{"location":"api/public/#XAM.SAM.FLAG_MREVERSE","page":"Public","title":"XAM.SAM.FLAG_MREVERSE","text":"0x0020: the mate is mapped to the reverse strand\n\n\n\n\n\n","category":"constant"},{"location":"api/public/#XAM.SAM.FLAG_MUNMAP","page":"Public","title":"XAM.SAM.FLAG_MUNMAP","text":"0x0008: the mate is unmapped\n\n\n\n\n\n","category":"constant"},{"location":"api/public/#XAM.SAM.FLAG_PAIRED","page":"Public","title":"XAM.SAM.FLAG_PAIRED","text":"0x0001: the read is paired in sequencing, no matter whether it is mapped in a pair\n\n\n\n\n\n","category":"constant"},{"location":"api/public/#XAM.SAM.FLAG_PROPER_PAIR","page":"Public","title":"XAM.SAM.FLAG_PROPER_PAIR","text":"0x0002: the read is mapped in a proper pair\n\n\n\n\n\n","category":"constant"},{"location":"api/public/#XAM.SAM.FLAG_QCFAIL","page":"Public","title":"XAM.SAM.FLAG_QCFAIL","text":"0x0200: QC failure\n\n\n\n\n\n","category":"constant"},{"location":"api/public/#XAM.SAM.FLAG_READ1","page":"Public","title":"XAM.SAM.FLAG_READ1","text":"0x0040: this is read1\n\n\n\n\n\n","category":"constant"},{"location":"api/public/#XAM.SAM.FLAG_READ2","page":"Public","title":"XAM.SAM.FLAG_READ2","text":"0x0080: this is read2\n\n\n\n\n\n","category":"constant"},{"location":"api/public/#XAM.SAM.FLAG_REVERSE","page":"Public","title":"XAM.SAM.FLAG_REVERSE","text":"0x0010: the read is mapped to the reverse strand\n\n\n\n\n\n","category":"constant"},{"location":"api/public/#XAM.SAM.FLAG_SECONDARY","page":"Public","title":"XAM.SAM.FLAG_SECONDARY","text":"0x0100: not primary alignment\n\n\n\n\n\n","category":"constant"},{"location":"api/public/#XAM.SAM.FLAG_SUPPLEMENTARY","page":"Public","title":"XAM.SAM.FLAG_SUPPLEMENTARY","text":"0x0800: supplementary alignment\n\n\n\n\n\n","category":"constant"},{"location":"api/public/#XAM.SAM.FLAG_UNMAP","page":"Public","title":"XAM.SAM.FLAG_UNMAP","text":"0x0004: the read itself is unmapped; conflictive with SAM.FLAGPROPERPAIR\n\n\n\n\n\n","category":"constant"},{"location":"api/public/#XAM.SAM.Header-Tuple{}","page":"Public","title":"XAM.SAM.Header","text":"SAM.Header()\n\nCreate an empty header.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.MetaInfo-Tuple{AbstractString,Any}","page":"Public","title":"XAM.SAM.MetaInfo","text":"MetaInfo(tag::AbstractString, value)\n\nCreate a SAM metainfo with tag and value.\n\ntag is a two-byte ASCII string. If tag is \"CO\", value must be a string; otherwise, value is an iterable object with key and value pairs.\n\nExamples\n\njulia> SAM.MetaInfo(\"CO\", \"some comment\")\nBioAlignments.SAM.MetaInfo:\n tag: CO\n value: some comment\n\njulia> string(ans)\n\"@CO\tsome comment\"\n\njulia> SAM.MetaInfo(\"SQ\", [\"SN\" => \"chr1\", \"LN\" => 12345])\nBioAlignments.SAM.MetaInfo:\n tag: SQ\n value: SN=chr1 LN=12345\n\njulia> string(ans)\n\"@SQ\tSN:chr1\tLN:12345\"\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.MetaInfo-Tuple{AbstractString}","page":"Public","title":"XAM.SAM.MetaInfo","text":"MetaInfo(str::AbstractString)\n\nCreate a SAM metainfo from str.\n\nExamples\n\njulia> SAM.MetaInfo(\"@CO\tsome comment\")\nBioAlignments.SAM.MetaInfo:\n tag: CO\n value: some comment\n\njulia> SAM.MetaInfo(\"@SQ\tSN:chr1\tLN:12345\")\nBioAlignments.SAM.MetaInfo:\n tag: SQ\n value: SN=chr1 LN=12345\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.Reader-Tuple{IO}","page":"Public","title":"XAM.SAM.Reader","text":"SAM.Reader(input::IO)\n\nCreate a data reader of the SAM file format.\n\nArguments\n\ninput: data source\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.Record-Tuple{AbstractString}","page":"Public","title":"XAM.SAM.Record","text":"SAM.Record(str::AbstractString)\n\nCreate a SAM record from str. This function verifies the format and indexes fields for accessors.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.Record-Tuple{Array{UInt8,1}}","page":"Public","title":"XAM.SAM.Record","text":"SAM.Record(data::Vector{UInt8})\n\nCreate a SAM record from data. This function verifies the format and indexes fields for accessors. Note that the ownership of data is transferred to a new record object.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.Record-Tuple{}","page":"Public","title":"XAM.SAM.Record","text":"SAM.Record()\n\nCreate an unfilled SAM record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.Writer","page":"Public","title":"XAM.SAM.Writer","text":"Writer(output::IO, header::Header=Header())\n\nCreate a data writer of the SAM file format.\n\nArguments\n\noutput: data sink\nheader=Header(): SAM header object\n\n\n\n\n\n","category":"type"},{"location":"api/public/#Base.findall-Tuple{XAM.SAM.Header,AbstractString}","page":"Public","title":"Base.findall","text":"find(header::Header, key::AbstractString)::Vector{MetaInfo}\n\nFind metainfo objects satisfying SAM.tag(metainfo) == key.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#BioCore.header-Tuple{XAM.SAM.Reader}","page":"Public","title":"BioCore.header","text":"header(reader::Reader)::Header\n\nGet the header of reader.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.alignlength-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.alignlength","text":"alignlength(record::Record)::Int\n\nGet the alignment length of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.alignment-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.alignment","text":"alignment(record::Record)::BioAlignments.Alignment\n\nGet the alignment of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.auxdata-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.auxdata","text":"auxdata(record::Record)::Dict{String,Any}\n\nGet the auxiliary data (optional fields) of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.cigar-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.cigar","text":"cigar(record::Record)::String\n\nGet the CIGAR string of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.flag-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.flag","text":"flag(record::Record)::UInt16\n\nGet the bitwise flag of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.iscomment-Tuple{XAM.SAM.MetaInfo}","page":"Public","title":"XAM.SAM.iscomment","text":"iscomment(metainfo::MetaInfo)::Bool\n\nTest if metainfo is a comment (i.e. its tag is \"CO\").\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.ismapped-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.ismapped","text":"ismapped(record::Record)::Bool\n\nTest if record is mapped.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.isnextmapped-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.isnextmapped","text":"isnextmapped(record::Record)::Bool\n\nTest if the mate/next read of record is mapped.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.isprimary-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.isprimary","text":"isprimary(record::Record)::Bool\n\nTest if record is a primary line of the read.\n\nThis is equivalent to flag(record) & 0x900 == 0.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.keyvalues-Tuple{XAM.SAM.MetaInfo}","page":"Public","title":"XAM.SAM.keyvalues","text":"keyvalues(metainfo::MetaInfo)::Vector{Pair{String,String}}\n\nGet the values of metainfo as string pairs.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.mappingquality-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.mappingquality","text":"mappingquality(record::Record)::UInt8\n\nGet the mapping quality of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.nextposition-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.nextposition","text":"nextposition(record::Record)::Int\n\nGet the position of the mate/next read of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.nextrefname-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.nextrefname","text":"nextrefname(record::Record)::String\n\nGet the reference name of the mate/next read of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.position-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.position","text":"position(record::Record)::Int\n\nGet the 1-based leftmost mapping position of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.quality-Tuple{Type{String},XAM.SAM.Record}","page":"Public","title":"XAM.SAM.quality","text":"quality(::Type{String}, record::Record)::String\n\nGet the ASCII-encoded base quality of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.quality-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.quality","text":"quality(record::Record)::Vector{UInt8}\n\nGet the Phred-scaled base quality of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.refname-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.refname","text":"refname(record::Record)::String\n\nGet the reference sequence name of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.rightposition-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.rightposition","text":"rightposition(record::Record)::Int\n\nGet the 1-based rightmost mapping position of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.seqlength-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.seqlength","text":"seqlength(record::Record)::Int\n\nGet the sequence length of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.sequence-Tuple{Type{String},XAM.SAM.Record}","page":"Public","title":"XAM.SAM.sequence","text":"sequence(::Type{String}, record::Record)::String\n\nGet the segment sequence of record as String.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.sequence-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.sequence","text":"sequence(record::Record)::BioSequences.DNASequence\n\nGet the segment sequence of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.tag-Tuple{XAM.SAM.MetaInfo}","page":"Public","title":"XAM.SAM.tag","text":"tag(metainfo::MetaInfo)::String\n\nGet the tag of metainfo.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.templength-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.templength","text":"templength(record::Record)::Int\n\nGet the template length of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.tempname-Tuple{XAM.SAM.Record}","page":"Public","title":"XAM.SAM.tempname","text":"tempname(record::Record)::String\n\nGet the query template name of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.SAM.value-Tuple{XAM.SAM.MetaInfo}","page":"Public","title":"XAM.SAM.value","text":"value(metainfo::MetaInfo)::String\n\nGet the value of metainfo as a string.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#BAM-API-1","page":"Public","title":"BAM API","text":"","category":"section"},{"location":"api/public/#","page":"Public","title":"Public","text":"The following methods and types are provided by the BAM submodule for public use.","category":"page"},{"location":"api/public/#","page":"Public","title":"Public","text":"Modules = [XAM.BAM]\nprivate = false","category":"page"},{"location":"api/public/#XAM.BAM.BAI-Tuple{AbstractString}","page":"Public","title":"XAM.BAM.BAI","text":"BAI(filename::AbstractString)\n\nLoad a BAI index from filename.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.BAI-Tuple{IO}","page":"Public","title":"XAM.BAM.BAI","text":"BAI(input::IO)\n\nLoad a BAI index from input.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.Reader","page":"Public","title":"XAM.BAM.Reader","text":"BAM.Reader(input::IO; index=nothing)\n\nCreate a data reader of the BAM file format.\n\nArguments\n\ninput: data source\nindex=nothing: filepath to a random access index (currently bai is supported)\n\n\n\n\n\n","category":"type"},{"location":"api/public/#XAM.BAM.Record","page":"Public","title":"XAM.BAM.Record","text":"BAM.Record()\n\nCreate an unfilled BAM record.\n\n\n\n\n\n","category":"type"},{"location":"api/public/#XAM.BAM.Writer","page":"Public","title":"XAM.BAM.Writer","text":"BAM.Writer(output::BGZFStream, header::SAM.Header)\n\nCreate a data writer of the BAM file format.\n\nArguments\n\noutput: data sink\nheader: SAM header object\n\n\n\n\n\n","category":"type"},{"location":"api/public/#BioCore.header-Tuple{XAM.BAM.Reader}","page":"Public","title":"BioCore.header","text":"header(reader::Reader; fillSQ::Bool=false)::SAM.Header\n\nGet the header of reader.\n\nIf fillSQ is true, this function fills missing \"SQ\" metainfo in the header.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.alignlength-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.alignlength","text":"alignlength(record::Record)::Int\n\nGet the alignment length of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.alignment-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.alignment","text":"alignment(record::Record)::BioAlignments.Alignment\n\nGet the alignment of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.auxdata-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.auxdata","text":"auxdata(record::Record)::BAM.AuxData\n\nGet the auxiliary data of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.cigar","page":"Public","title":"XAM.BAM.cigar","text":"cigar(record::Record)::String\n\nGet the CIGAR string of record.\n\nNote that in the BAM specification, the field called cigar typically stores the cigar string of the record. However, this is not always true, sometimes the true cigar is very long, and due to some constraints of the BAM format, the actual cigar string is stored in an extra tag: CG:B,I, and the cigar field stores a pseudo-cigar string.\n\nCalling this method with checkCG set to true (default) this method will always yield the true cigar string, because this is probably what you want the vast majority of the time.\n\nIf you have a record that stores the true cigar in a CG:B,I tag, but you still want to access the pseudo-cigar that is stored in the cigar field of the BAM record, then you can set checkCG to false.\n\nSee also BAM.cigar_rle.\n\n\n\n\n\n","category":"function"},{"location":"api/public/#XAM.BAM.cigar_rle","page":"Public","title":"XAM.BAM.cigar_rle","text":"cigar_rle(record::Record, checkCG::Bool = true)::Tuple{Vector{BioAlignments.Operation},Vector{Int}}\n\nGet a run-length encoded tuple (ops, lens) of the CIGAR string in record.\n\nNote that in the BAM specification, the field called cigar typically stores the cigar string of the record. However, this is not always true, sometimes the true cigar is very long, and due to some constraints of the BAM format, the actual cigar string is stored in an extra tag: CG:B,I, and the cigar field stores a pseudo-cigar string.\n\nCalling this method with checkCG set to true (default) this method will always yield the true cigar string, because this is probably what you want the vast majority of the time.\n\nIf you have a record that stores the true cigar in a CG:B,I tag, but you still want to access the pseudo-cigar that is stored in the cigar field of the BAM record, then you can set checkCG to false.\n\nSee also BAM.cigar.\n\n\n\n\n\n","category":"function"},{"location":"api/public/#XAM.BAM.flag-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.flag","text":"flag(record::Record)::UInt16\n\nGet the bitwise flag of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.ismapped-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.ismapped","text":"ismapped(record::Record)::Bool\n\nTest if record is mapped.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.isnextmapped-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.isnextmapped","text":"isnextmapped(record::Record)::Bool\n\nTest if the mate/next read of record is mapped.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.ispositivestrand-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.ispositivestrand","text":"ispositivestrand(record::Record)::Bool\n\nTest if record is aligned to the positive strand.\n\nThis is equivalent to flag(record) & 0x10 == 0.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.isprimary-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.isprimary","text":"isprimary(record::Record)::Bool\n\nTest if record is a primary line of the read.\n\nThis is equivalent to flag(record) & 0x900 == 0.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.mappingquality-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.mappingquality","text":"mappingquality(record::Record)::UInt8\n\nGet the mapping quality of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.n_cigar_op","page":"Public","title":"XAM.BAM.n_cigar_op","text":"n_cigar_op(record::Record, checkCG::Bool = true)\n\nReturn the number of operations in the CIGAR string of record.\n\nNote that in the BAM specification, the field called cigar typically stores the cigar string of the record. However, this is not always true, sometimes the true cigar is very long, and due to some constraints of the BAM format, the actual cigar string is stored in an extra tag: CG:B,I, and the cigar field stores a pseudo-cigar string.\n\nCalling this method with checkCG set to true (default) this method will always yield the number of operations in the true cigar string, because this is probably what you want, the vast majority of the time.\n\nIf you have a record that stores the true cigar in a CG:B,I tag, but you still want to get the number of operations in the cigar field of the BAM record, then set checkCG to false.\n\n\n\n\n\n","category":"function"},{"location":"api/public/#XAM.BAM.nextposition-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.nextposition","text":"nextposition(record::Record)::Int\n\nGet the 1-based leftmost mapping position of the next/mate read of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.nextrefid-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.nextrefid","text":"nextrefid(record::Record)::Int\n\nGet the next/mate reference sequence ID of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.nextrefname-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.nextrefname","text":"nextrefname(record::Record)::String\n\nGet the reference name of the mate/next read of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.position-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.position","text":"position(record::Record)::Int\n\nGet the 1-based leftmost mapping position of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.quality-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.quality","text":"quality(record::Record)::Vector{UInt8}\n\nGet the base quality of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.refid-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.refid","text":"refid(record::Record)::Int\n\nGet the reference sequence ID of record.\n\nThe ID is 1-based (i.e. the first sequence is 1) and is 0 for a record without a mapping position.\n\nSee also: BAM.rname\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.reflen-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.reflen","text":"reflen(record::Record)::Int\n\nGet the length of the reference sequence this record applies to.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.refname-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.refname","text":"refname(record::Record)::String\n\nGet the reference sequence name of record.\n\nSee also: BAM.refid\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.rightposition-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.rightposition","text":"rightposition(record::Record)::Int\n\nGet the 1-based rightmost mapping position of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.seqlength-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.seqlength","text":"seqlength(record::Record)::Int\n\nGet the sequence length of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.sequence-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.sequence","text":"sequence(record::Record)::BioSequences.DNASequence\n\nGet the segment sequence of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.templength-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.templength","text":"templength(record::Record)::Int\n\nGet the template length of record.\n\n\n\n\n\n","category":"method"},{"location":"api/public/#XAM.BAM.tempname-Tuple{XAM.BAM.Record}","page":"Public","title":"XAM.BAM.tempname","text":"tempname(record::Record)::String\n\nGet the query template name of record.\n\n\n\n\n\n","category":"method"}]
}
