n_op¶| Parameters: | qual_string (str or bytes) – Phred quality scores without offset |
-
|---|---|
| Returns: | ASCII-encoded Phred scores offest by adding 33 to base score. | -
| Return type: | (str) | -
-
+
- Parameters +
qual_string (
+strorbytes) – Phred quality scores without offset
+- Returns +
ASCII-encoded Phred scores offest by adding 33 to base score.
+
+- Return type +
(str)
+
+
Examples
>>> qual_score = ''
>>> ''.join(offset_qual(qual_score))
@@ -269,28 +264,24 @@
class bamnostic.core.AlignmentFile(filepath_or_object, mode='rb', max_cache=128, index_filename=None, filename=None, check_header=False, check_sq=True, reference_filename=None, filepath_index=None, require_index=False, duplicate_filehandle=None, ignore_truncation=False, compresslevel=6, ignore_overwrite=False, copy_header=None, header=b'', reference_names=None, reference_lengths=None)[source]¶
Bases: bamnostic.bam.BamReader, bamnostic.bam.BamWriter
Wrapper to allow drop in replacement for BAM functionality in a pysam-like API.
| Parameters: |
|
-
|---|
-
@@ -479,40 +470,35 @@
-
get_tag(tag, with_value_type=False)[source]¶ Gets the value associated with a given tag key.
--
+- - - Parameters: -
-
- tag (str) – the tag of interest -
- with_value_type (bool) – return what kind of value the tag +
- Parameters +
-
+
tag (str) – the tag of interest
+with_value_type (bool) – return what kind of value the tag
-
+
Returns: the value associated with a given tag or the value and type + +
- Returns
+the value associated with a given tag or the value and type of value (as seen in BAM format)
-
+
Returns all the tags for a given read
--
+- - - Parameters: with_value_type (bool) – return the tag value type (as defined by BAM format) -Returns: list of tag tuples (with or without tag value type) -Return type: f_tags( -list)-
+
- Parameters +
with_value_type (bool) – return the tag value type (as defined by BAM format)
+
+- Returns +
list of tag tuples (with or without tag value type)
+
+- Return type +
f_tags(
+list)
+
-
@@ -520,17 +506,15 @@
Gets the counts of each CIGAR operation in the read and number of nucleotides related to those given operations.
--
+- - - Returns: list of CIGAR operation counts -nt_counts ( -list): list of nucleotide counts for each operationReturn type: op_blocks ( -list)-
+
- Returns +
list of CIGAR operation counts +nt_counts (
+list): list of nucleotide counts for each operation
+- Return type +
op_blocks (
+list)
+
get_cigar_stats()[source]¶
-
@@ -540,32 +524,28 @@
- Returns +
generated reference sequence
+
+- Return type +
(str)
+
+- Raises +
KeyError – if read does not contain MD tag
+
+
Uses the CIGAR string and MD tag to recreate the reference sequence associated with the aligned segment. This is done without the need for looking up the reference genome.
-| Returns: | generated reference sequence | -
|---|---|
| Return type: | (str) | -
| Raises: | KeyError – if read does not contain MD tag |
-
-
+
-
to_bam()[source]¶ Writes the alignment record to a BAM file
--
+- - - Parameters: bam_file (string or -bamnostic.bam.BamWriter) – BAM file path or open bam file in a write mode-
+
- Parameters +
bam_file (string or
+bamnostic.bam.BamWriter) – BAM file path or open bam file in a write mode
+
Note
-Does not progress file cursor position.
+Note
+Does not progress file cursor position.
| Parameters: |
|
-
|---|---|
| Returns: | Complete BGZF block - |
-
| Raises: |
|
-
Complete BGZF block
+ValueError – if the BGZF block header is malformed
+Example
>>> bam_header = get_block(bamnostic.example_bam)
>>> try:
@@ -688,27 +664,23 @@
within the deflated BGZF block where the position starts. The virtual offset
is defined as
virtual_offset = coffset << 16 | uoffset
-| Parameters: | virtual_offset (int) – 64-bit unsigned composite byte offset - |
-
|---|---|
| Returns: | an echo of the new position - |
-
| Return type: | virtual_offset (int) - |
-
| Raises: |
|
-
Example
>>> bam = bamnostic.AlignmentFile(bamnostic.example_bam, 'rb')
>>> bam.seek(10)
@@ -727,27 +699,23 @@
read(size=-1)[source]¶Read method for the BGZF module.
-| Parameters: | size (int) – the number of bytes to read from file. Advances the cursor. - |
-
|---|---|
| Returns: | byte string of length size - |
-
| Return type: | data ( |
-
| Raises: |
|
-
-
@@ -769,8 +737,8 @@
Return True indicating the BGZF supports random access.
-Note
-Modified from original Bio.BgzfReader: checks to see if BAM +
Note
+Modified from original Bio.BgzfReader: checks to see if BAM file has associated index file (BAI)
seekable()[source]¶
bamnostic.bai.reg2bin(rbeg, rend)[source]¶Finds the largest superset bin of region. Numeric values taken from hts-specs
-| Parameters: |
|
-
|---|---|
| Returns: | distinct bin ID for largest superset bin of region - |
-
| Return type: | (int) - |
-
distinct bin ID for largest superset bin of region
+(int)
+-
bamnostic.bai.reg2bins(rbeg, rend)[source]¶ Generates bin ids which overlap the specified region.
--
+- - - Parameters: -
-
- rbeg (int) – inclusive beginning position of region -
- rend (int) – exclusive end position of region +
- Parameters +
-
+
rbeg (int) – inclusive beginning position of region
+rend (int) – exclusive end position of region
-
+
Yields: (int) – bin IDs for overlapping bins of region
-Raises: AssertionError (Exception) – if the range is malformed or invalid
-
+- Yields +
(int) – bin IDs for overlapping bins of region
+
+- Raises +
AssertionError (Exception) – if the range is malformed or invalid
+
+
-
@@ -1001,84 +961,66 @@
-
_io¶ opened BAI file object
--
+- - - Type: fileObject --
+
- Type +
fileObject
+
+
-
_LINEAR_INDEX_WINDOW¶ constant of the linear interval window size
--
+- - - Type: int --
+
- Type +
int
+
+
-
_UNMAP_BIN¶ constant for bin ID of unmapped read stats
--
+- - - Type: int --
+
- Type +
int
+
+
-
magic¶ first 4 bytes of file. Must be equal to b’BAI’
--
+- - - Type: bytes --
+
- Type +
bytes
+
+
-
n_refs¶ number of references in BAI
--
+- - - Type: int --
+
- Type +
int
+
+
-
unmapped¶ dictionary of the unmapped read stats by each reference
--
+- - - Type: dict --
+
- Type +
dict
+
+
-
@@ -1087,56 +1029,44 @@
dictionary of the current reference loaded into memory. It contains the a dictionary of bin IDs and their respective chunks, and a list of linear intervals.
--
+- - - Type: None|dict --
+
- Type +
None|dict
+
+
-
ref_indices¶ dictionary of reference ids and their start/stop offsets within the BAI file
--
+- - - Type: dict --
+
- Type +
dict
+
+
-
n_no_coord¶ if present in BAI, is the number of reads that have no coordinates
--
+- - - Type: None|int --
+
- Type +
None|int
+
+
-
_last_pos¶ used for indexing, the byte position of the file head.
--
+- - - Type: int --
+
- Type +
int
+
+
-
@@ -1150,22 +1080,21 @@
- a list of Chunk objects with the attributes of -
- chunks[i] are .voffset_beg and voffset_end +
- Parameters +
n_chunks (int) – number of chunks to be unpacked from stream
+
+- Returns +
-
+
- a list of Chunk objects with the attributes of
chunks[i] are .voffset_beg and voffset_end
+
+
+- Return type +
chunks (list)
+
Note: a special case of a chunk is in any Bin labeled as 37450. These bins always contain 2 chunks that provide the statistics of the number of reads that are unmapped to that reference.
-| Parameters: | n_chunks (int) – number of chunks to be unpacked from stream | -
|---|---|
| Returns: |
|
-
| Return type: | chunks (list) | -
-
@@ -1180,18 +1109,17 @@
- Parameters +
n_int (int) – number of intervals to unpack
+
+- Returns +
list of virtual offsets for n_int number of linear intervals
+
+- Return type +
intervals (list)
+
+
Note: a caveat to using linear interval with long reads: A long read can span multiple linear intervals. As such, the current encoding could potentially shift the expected region of interest to the left more than expected.
-| Parameters: | n_int (int) – number of intervals to unpack | -
|---|---|
| Returns: | list of virtual offsets for n_int number of linear intervals | -
| Return type: | intervals (list) | -
-
+
-
@@ -1213,24 +1141,24 @@
- None if just indexing the index file or a dictionary -
- of bin_id: chunks pairs +
- Parameters +
n_int (int) – number of bins to be unpacked from stream
+
+- Returns +
-
+
- None if just indexing the index file or a dictionary
of bin_id: chunks pairs
+
+
+- Return type +
bins (None | dict)
+
+- Raises +
AssertionError (Exception) – if bin 37450 does not contain 2 chunks exactly
+
As a secondary feature, this function will also quickly seek over regions for the purposes of documenting the start and stop byte offsets of a given reference block within the file. This is invoked by setting idx=True
-| Parameters: | n_int (int) – number of bins to be unpacked from stream | -
|---|---|
| Returns: |
|
-
| Return type: | bins (None | dict) | -
| Raises: | AssertionError (Exception) – if bin 37450 does not contain 2 chunks exactly | -
-
@@ -1247,30 +1175,26 @@
loaded. Because of this constant loading, functools.lru_cache was applied to cache recently
used reference blocks to speed up computation. It is assumed that when querying is done, most
users are looking and just a few references at a time.
-
- ref_id (None|int) – used for random access or indexing the BAI -
- idx (bool) – Flag for setting whether or not to run an index of the BAI +
- Parameters +
-
+
ref_id (None|int) – used for random access or indexing the BAI
+idx (bool) – Flag for setting whether or not to run an index of the BAI
- Returns +
namedtuple containing the byte offsets of the reference start, stop, and number of bins or Ref: namedtuple containing a dictionary of bins and list of linear intervals
-- Return type +
- + +
- Raises +
AssertionError (Exception) – if, when random access is used, the current reference offset + does not match indexed reference offset.
+
+
| Parameters: |
|
-
|---|---|
| Returns: | namedtuple containing the byte offsets of the reference start, stop, and number of bins + + |
-
| Return type: | - | -
| Raises: | AssertionError (Exception) – if, when random access is used, the current reference offset -does not match indexed reference offset. - |
-
-
@@ -1278,58 +1202,49 @@
Main query function for determining seek offset to BAM section that AlignedRead objects from specified region start
--
+- - - Parameters: -
-
- ref (int) – which reference/chromosome TID -
- start (int) – left most bp position of region (zero-based) -
- stop (int) – right most bp position of region (zero-based) +
- Parameters +
-
+
ref (int) – which reference/chromosome TID
+start (int) – left most bp position of region (zero-based)
+stop (int) – right most bp position of region (zero-based)
-
+
Returns: -
-
- the voffset_beg of the first chunk given the chunk’s voffset_end -
is greater than the voffset of the linear index that overlaps +
+- Returns +
-
+
- the voffset_beg of the first chunk given the chunk’s voffset_end
is greater than the voffset of the linear index that overlaps the region of interest’s start offset
Return type: (int)
-
+- Return type +
(int)
+
+
query(ref_id, start, stop=-1)[source]¶
-
seek(offset=None, whence=0)[source]¶ Simple seek function for binary files
--
-- - - Parameters: -
-
- offset (None|int) – byte offset from whence to move the file head to. -
- whence (int) – 0 := from start of file, 1:= from current position, 2:= from end of file +
- Parameters +
-
+
offset (None|int) – byte offset from whence to move the file head to.
+whence (int) – 0 := from start of file, 1:= from current position, 2:= from end of file
-
+
Returns: new byte position of file head
-Return type: (int)
--
-
- Raise: -
- ValueError (Exception): if the offset is not an integer or is not provided +
+- Returns +
new byte position of file head
+
+- Return type +
(int)
+
+
-
+
- Raise:
ValueError (Exception): if the offset is not an integer or is not provided
+
read(size=-1)[source]¶Simple read function for binary files
-| Parameters: | size (int) – number of bytes to read in (default: -1 –whole file) | -
|---|---|
| Returns: | the number of bytes read from file | -
| Return type: | (bytes) | -
-
+
- Parameters +
size (int) – number of bytes to read in (default: -1 –whole file)
+
+- Returns +
the number of bytes read from file
+
+- Return type +
(bytes)
+
+
-
tell()[source]¶ Simple tell function for reporting byte position of file head
--
+- - - Returns: byte position of file head -Return type: (int) --
+
- Returns +
byte position of file head
+
+- Return type +
(int)
+
+
bamnostic.utils.format_warnings(message, category, filename, lineno, file=None, line=None)[source]¶Sets STDOUT warnings
-| Parameters: |
|
-
|---|---|
| Returns: | formatted warning string - |
-
formatted warning string
+-
@@ -1446,36 +1354,36 @@
flags are used for read filtering and QC. The flags are described below.
Additionally, they can be found here
- Parameters +
flag_code (int) – either a standalone integer/bit flag or the read object itself
+
+- Returns +
list of flag and flag description tuples.
+
+- Return type +
(
+listoftuple)
+- Raises +
ValueError – if provided flag is not a valid entry
+
+
Any given read’s flag is determined by the or (|) operand of all appropriate bit flags.
-| Parameters: | flag_code (int) – either a standalone integer/bit flag or the read object itself | -
|---|---|
| Returns: | list of flag and flag description tuples. | -
| Return type: | (list of tuple) |
-
| Raises: | ValueError – if provided flag is not a valid entry |
-
-
+
Example
If a flag is 516 it is comprised of flag 4 and flag 512
>>> flag_decode(516)
[(4, 'read unmapped'), (512, 'QC fail')]
