BAM information on Iso‐Seq data

In the context of BAM files generated from PacBio Iso-Seq (Isoform Sequencing) analysis, the flags in the BAM file header generally do not differ from the standard SAM/BAM flags used across many sequencing technologies. However, each flag is a bitmask that provides information about each read's properties in the context of the sequencing and alignment process.

Here’s a brief overview of the standard SAM/BAM flags that you might encounter in any BAM file, including those from PacBio Iso-Seq:

Commonly Used Flags in SAM/BAM Files:

0x001 (1): Read is paired in sequencing (not relevant for most single-molecule sequencing like PacBio).
0x002 (2): Read is mapped in a proper pair (also not typically relevant for single-molecule sequencing).
0x004 (4): Read is unmapped.
0x008 (8): Mate is unmapped (relevant if paired-end reads are considered).
0x010 (16): Read is reverse complemented (indicates the read is mapped to the reverse complement of the reference).
0x020 (32): Mate is reverse complemented.
0x040 (64): First in pair (for paired-end data).
0x080 (128): Second in pair.
0x100 (256): Not primary alignment (the read aligns in more than one location, and this is not the best alignment).
0x200 (512): Read fails platform/vendor quality checks.
0x400 (1024): Read is PCR or optical duplicate.
0x800 (2048): Supplementary alignment (used in split or chimeric alignments).

For PacBio sequencing data, including Iso-Seq data, certain flags are more commonly relevant:

0x004 (4) Unmapped: Important to check as it indicates reads that did not align to the reference genome.
0x010 (16) Reverse complemented: Indicates the orientation of the read relative to the reference genome, which is particularly relevant given the nature of full-length transcript sequencing.
0x100 (256) Not primary alignment: This can be quite relevant for transcripts that might map to multiple locations (e.g., due to repetitive elements or similar genes).

For Iso-Seq specifically, where each read is supposed to represent a full-length non-chimeric (FLNC) transcript, you might find flags indicating whether a read is considered a full-length transcript and whether it has passed quality filters (like high accuracy in predicted poly-A tail sites).

TAGS

PacBio Iso-Seq data, particularly from clustered BAM files, includes specific tags that provide essential information about each read. These tags are useful for understanding the characteristics of the sequenced transcripts, such as their origins, the quality of the sequence, and specific attributes relevant to full-length transcript data.

Each tag in a BAM file has three main parts:

Tag: A two-character identifier that specifies what kind of data the tag contains. For example, NM indicates the edit distance to the reference.

Type: A single character that tells you the type of data stored in the tag. 
Common types include:
* A: character 
* i: integer 
* f: floating point 
* Z: zero-terminated string (used for text strings) 
* H: byte array in hexadecimal format 
* B: general array (the type of array elements is specified further) 

Value: The actual data of the tag, which can vary in type depending on what the tag is used for. 

Here are some of the key tags you might find in a PacBio Iso-Seq clustered BAM file:

Standard PacBio Tags

PL (Platform): Contains 'PacBio'
PM (Platform model): Contains PacBio instrument series (ASTRO/RS/SEQUEL)
PU (Platform unit): PacBio movie name
LB (Well sample name): Contains user-supplie name of the library.
SM (Bio Sample Name): User-supplied name of the biological sample.
BC (barcodes): Contains barcode sequences associated with this read group. Not required in all PacBio bam files, but must be provided when the read group ID includes barcode labels. 
RG (Read Group): Read group ID.
DS (Description): Semantic information about reads in the group. 


pb (PacBio version): version used, captured in header. 
bc (Barcode Calls/ Barcode Sequence): This tag contains the sequence of the barcode used, if barcoding was applied during the sequencing preparation. It helps in demultiplexing samples (per-ZMW).
bq (Barcode Quality): Represents the quality of the barcode sequence (per-ZMW).
bl (barcode sequence): Clipped from leading end.
bt (Barcode sequence): clipped from trailing end.
ql (qualities of barcode bases): clipped from leading end, stored as FASTQ string.
qt (qualities of barcode bases): clipped from trailing end, stored as FASTQ string.
bx (): Pair of clipped barcode sequence lengths. 
np (Number of Passes): Indicates the number of times the polymerase read through the insert, which can be a proxy for read quality in circular consensus sequencing (CCS).
rq (Read Quality): A value representing the predicted accuracy of the polished isoform or a consensus sequence, typically present in CCS reads.
zm (ZMW Hole Number): A unique identifier for the zero-mode waveguide (ZMW) from which the read originated, which is useful for tracing the read back to its physical origin in the sequencing process.
rg (Read Group): The RG:Z tag is used to identify the read group to which a read belongs. Read groups are important in sequencing data because they contain reads that share certain characteristics, typically because they were generated in the same run or from the same sample.
mg (): Added by pbmm2. Stores gap-compressed alignment identity, defined as nM/(nM + nMM + nInsEvents + nDelEvents).
ec (Effective coverage): For CCS reads, the average subread coverage across all windows (only in CCS reads).
sn (Signal to Noise ratio): 4 floats for the average ratio of A,C,G, and T (in that order) over the HQRegion. 

Tags that are reserved for specific keys:

dq (DeletionQV)
dt (DeletionTag)
iq (InsertionQV)
mq (MergeQV)
sq (SubstitutionQV)
st (SubstitutionTag)
ip (Ipd:Frames/ Ipd:CodecV1)
pw (PulseWidth:Frames/PulseWidth:CodecV1)
fi (Forward IPD)
ri (Reverse IPD)
fp (Forward PulseWidth(CodecV1)
rp (Reverse PulseWidth(CodecV1)
fn (Forward number of complete passes)
rn (Reverse number of complete passes)
Mm:Z (Base modifications/methylation)
MI:B,C (Base modification probabilities)
sz:A (ZMW classification annotation: normal/control/malformed/sentinel)
sc:A (scrap region-type annotation: adapter/barcode, LQRegion, filtered)
cx:i (subread local context flags)
ac:B,i (Array with 4 counts, detected adapters left/start, missing adapters left/start, detected adapters right/end, missing adapters right/end)
ma:i (Bitmask storing if andapter is missing on either side of the molecule)

Iso-Seq Specific Tags

ic (Input consensus): Number of reads used to generate consensus. If less than is, this means that reads were downsampled when consensus-calling.
is (Input sequences): Number of reads asssociated with isoform. 
iz (Max subreads used): Maximum number of subreads used for polishing.
it (Trimmed): List of barcodes/UMIs clipped during tag. 
im (Names): List of names of input reads used in generating consensus. 
qf (Quality of FL): Indicates whether a read is considered a high-quality full-length read.
qs (Start of Sequence): This tag might be used to indicate the starting point of the high-quality segment of the read.
qe (End of Sequence): Similar to qs, this indicates the end of the high-quality segment.
cx or GX (Transcript Isoform Annotation): Contains information about the isoform and other annotation details that have been inferred from the clustering and alignment processes.
mi (Molecule Info): Information about the molecule from which the read was generated, particularly in cases of multiple consensus reads from the same original RNA molecule.

Custom Iso-Seq tags that we are integrating onto our bam files [integrating information from pigeon output file pigeon_classification.txt] :

haplotype (HP:i:)
isoform (in:Z:)
structural_category (sc:Z:)
associated_gene (gn:Z:)
associated_transcript (tn:Z:)
subcategory (sb:Z:)
isoform_haplotype_noncyclo_counts (hn:i:)
isoform_haplotype_cyclo_counts (hc:i:)
isoform_noncyclo_counts (sn:i:)
isoform_cyclo_counts (sc:i:)

https://pacbiofileformats.readthedocs.io/en/11.0/BAM.html https://isoseq.how/isoseq-tags.html