API Reference

0x0400: optical or PCR duplicate

0x0020: the mate is mapped to the reverse strand

0x0008: the mate is unmapped

0x0001: the read is paired in sequencing, no matter whether it is mapped in a pair

0x0002: the read is mapped in a proper pair

0x0200: QC failure

0x0040: this is read1

0x0080: this is read2

0x0010: the read is mapped to the reverse strand

0x0100: not primary alignment

0x0800: supplementary alignment

0x0004: the read itself is unmapped; conflictive with SAM.FLAGPROPERPAIR

SAM.Header()

Create an empty header.

MetaInfo(tag::AbstractString, value)

Create a SAM metainfo with tag and value.

tag 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.

Examples

julia> SAM.MetaInfo("CO", "some comment")
BioAlignments.SAM.MetaInfo:
    tag: CO
  value: some comment

julia> string(ans)
"@CO	some comment"

julia> SAM.MetaInfo("SQ", ["SN" => "chr1", "LN" => 12345])
BioAlignments.SAM.MetaInfo:
    tag: SQ
  value: SN=chr1 LN=12345

julia> string(ans)
"@SQ	SN:chr1	LN:12345"

MetaInfo(str::AbstractString)

Create a SAM metainfo from str.

Examples

julia> SAM.MetaInfo("@CO	some comment")
BioAlignments.SAM.MetaInfo:
    tag: CO
  value: some comment

julia> SAM.MetaInfo("@SQ	SN:chr1	LN:12345")
BioAlignments.SAM.MetaInfo:
    tag: SQ
  value: SN=chr1 LN=12345

SAM.Reader(input::IO)

Create a data reader of the SAM file format.

Arguments

• input: data source

SAM.Record(str::AbstractString)

Create a SAM record from str. This function verifies the format and indexes fields for accessors.

SAM.Record(data::Vector{UInt8})

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.

SAM.Record()

Create an unfilled SAM record.

Writer(output::IO, header::Header=Header())

Create a data writer of the SAM file format.

Arguments

• output: data sink
• header=Header(): SAM header object

find(header::Header, key::AbstractString)::Vector{MetaInfo}

Find metainfo objects satisfying SAM.tag(metainfo) == key.

header(reader::Reader)::Header

Get the header of reader.

alignlength(record::Record)::Int

Get the alignment length of record.

alignment(record::Record)::BioAlignments.Alignment

Get the alignment of record.

auxdata(record::Record)::Dict{String,Any}

Get the auxiliary data (optional fields) of record.

cigar(record::Record)::String

Get the CIGAR string of record.

flag(record::Record)::UInt16

Get the bitwise flag of record.

iscomment(metainfo::MetaInfo)::Bool

Test if metainfo is a comment (i.e. its tag is "CO").

ismapped(record::Record)::Bool

Test if record is mapped.

isnextmapped(record::Record)::Bool

Test if the mate/next read of record is mapped.

isprimary(record::Record)::Bool

Test if record is a primary line of the read.

This is equivalent to flag(record) & 0x900 == 0.

keyvalues(metainfo::MetaInfo)::Vector{Pair{String,String}}

Get the values of metainfo as string pairs.

mappingquality(record::Record)::UInt8

Get the mapping quality of record.

nextposition(record::Record)::Int

Get the position of the mate/next read of record.

nextrefname(record::Record)::String

Get the reference name of the mate/next read of record.

position(record::Record)::Int

Get the 1-based leftmost mapping position of record.

quality(::Type{String}, record::Record)::String

Get the ASCII-encoded base quality of record.

quality(record::Record)::Vector{UInt8}

Get the Phred-scaled base quality of record.

refname(record::Record)::String

Get the reference sequence name of record.

rightposition(record::Record)::Int

Get the 1-based rightmost mapping position of record.

seqlength(record::Record)::Int

Get the sequence length of record.

sequence(::Type{String}, record::Record)::String

Get the segment sequence of record as String.

sequence(record::Record)::BioSequences.LongDNASeq

Get the segment sequence of record.

tag(metainfo::MetaInfo)::String

Get the tag of metainfo.

templength(record::Record)::Int

Get the template length of record.

tempname(record::Record)::String

Get the query template name of record.

value(metainfo::MetaInfo)::String

Get the value of metainfo as a string.

BAI(filename::AbstractString)

Load a BAI index from filename.

BAI(input::IO)

Load a BAI index from input.

BAM.Reader(input::IO; index=nothing)

Create a data reader of the BAM file format.

Arguments

• input: data source
• index=nothing: filepath to a random access index (currently bai is supported)

BAM.Record()

Create an unfilled BAM record.

BAM.Writer(output::BGZFStream, header::SAM.Header)

Create a data writer of the BAM file format.

Arguments

• output: data sink
• header: SAM header object

header(reader::Reader; fillSQ::Bool=false)::SAM.Header

Get the header of reader.

If fillSQ is true, this function fills missing "SQ" metainfo in the header.

alignlength(record::Record)::Int

Get the alignment length of record.

alignment(record::Record)::BioAlignments.Alignment

Get the alignment of record.

auxdata(record::Record)::BAM.AuxData

Get the auxiliary data of record.

cigar(record::Record)::String

Get 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 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.

See also BAM.cigar_rle.

cigar_rle(record::Record, checkCG::Bool = true)::Tuple{Vector{BioAlignments.Operation},Vector{Int}}

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.

See also BAM.cigar.

flag(record::Record)::UInt16

Get the bitwise flag of record.

ismapped(record::Record)::Bool

Test if record is mapped.

isnextmapped(record::Record)::Bool

Test if the mate/next read of record is mapped.

ispositivestrand(record::Record)::Bool

Test if record is aligned to the positive strand.

This is equivalent to flag(record) & 0x10 == 0.

isprimary(record::Record)::Bool

Test if record is a primary line of the read.

This is equivalent to flag(record) & 0x900 == 0.

mappingquality(record::Record)::UInt8

Get the mapping quality of record.

n_cigar_op(record::Record, checkCG::Bool = true)

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.

nextposition(record::Record)::Int

Get the 1-based leftmost mapping position of the next/mate read of record.

nextrefid(record::Record)::Int

Get the next/mate reference sequence ID of record.

nextrefname(record::Record)::String

Get the reference name of the mate/next read of record.

position(record::Record)::Int

Get the 1-based leftmost mapping position of record.

quality(record::Record)::Vector{UInt8}

Get the base quality of record.

refid(record::Record)::Int

Get the reference sequence ID of record.

The ID is 1-based (i.e. the first sequence is 1) and is 0 for a record without a mapping position.

See also: BAM.rname

reflen(record::Record)::Int

Get the length of the reference sequence this record applies to.

refname(record::Record)::String

Get the reference sequence name of record.

See also: BAM.refid

rightposition(record::Record)::Int

Get the 1-based rightmost mapping position of record.

seqlength(record::Record)::Int

Get the sequence length of record.

sequence(record::Record)::BioSequences.LongDNASeq

Get the segment sequence of record.

templength(record::Record)::Int

Get the template length of record.

tempname(record::Record)::String

Get the query template name of record.