Extracting Sequences
Nanalogue can extract and display read sequences from BAM files with highlighting for insertions, deletions, and modifications. This is useful for inspecting alignment quality and understanding modification patterns at the sequence level.
Quick Reference
| Flag | Effect |
|---|---|
--region <REGION> | Only include reads passing through the given region |
--full-region | Only include reads that pass through the given region in full |
--seq-region <REGION> | Display sequences from a specific genomic region |
--seq-full | Display the entire basecalled sequence |
--show-ins-lowercase | Show insertions as lowercase letters |
--show-mod-z | Show modified bases as Z (or z for modified insertions) |
--show-base-qual | Show basecalling quality scores |
Regions are written in the common genomics notation of contig:start-end e.g. chr1:50-100.
We use 0-based coordinates that are half open i.e. in the example above,
we are including all bases from the 51st base of chr1 to the 100th base.
Display conventions:
- Insertions: lowercase letters (with
--show-ins-lowercase) - Deletions: shown as periods (
.) - Modifications: shown as
Zorz(with--show-mod-z) - Quality at deleted positions:
255
Prerequisites
You will need:
- A BAM file with modification tags (
MMandMLtags) - Nanalogue installed
- For indel examples: a BAM file with insertions and/or deletions
Note: The contig names
contig_00001, etc. are example names used throughout this guide. In real BAM files aligned to a reference genome, you will see names likechr1,chr2,NC_000001.11, or similar depending on your reference.
Basic Sequence Extraction
To extract sequences from a specific region, use --seq-region:
nanalogue read-table-show-mods --tag m --region contig_00001:80-120 \
--seq-region contig_00001:80-120 input.bam
Example output:
# mod-unmod threshold is 0.5
read_id align_length sequence_length_template alignment_type mod_count sequence
0.3b25f6e5-da1b-41bd-a1f2-61415d4e88b5 320 320 primary_forward m:53 AGCGGCTCT
0.9a0352ad-2c37-4078-be82-a2e2a05414cb 283 283 supplementary_reverse m:43 CTCACGTGGGAGACTGTTATAGTTTACCATTAGCGGCTCT
In the above example, you may see sequences of varying length.
This is because not all the reads will pass through the given region in full.
To only include such reads and thus ensure more uniformity, you can use --full-region as shown below.
nanalogue read-table-show-mods --tag m --region contig_00001:80-120 \
--seq-region contig_00001:80-120 --full-region input.bam
Example output:
# mod-unmod threshold is 0.5
read_id align_length sequence_length_template alignment_type mod_count sequence
0.9a0352ad-2c37-4078-be82-a2e2a05414cb 283 283 supplementary_reverse m:43 CTCACGTGGGAGACTGTTATAGTTTACCATTAGCGGCTCT
Inspecting Alignment Quality
Viewing Insertions
Insertions relative to the reference can be highlighted as lowercase letters using --show-ins-lowercase.
We demonstrate usage using a file with indels in it.
nanalogue read-table-show-mods --tag m --region contig_00001:80-120 \
--seq-region contig_00001:80-120 --show-ins-lowercase input_indels.bam
Example output:
# mod-unmod threshold is 0.5
read_id align_length sequence_length_template alignment_type mod_count sequence
0.776541e0-2398-446c-a113-bbb1b394a3e5 200 194 supplementary_reverse m:27 ATTCACACGG..........aaaaCCCGTGCGATGGTTTGTCAG
0.e8556d24-2255-4c0a-a7f8-9a24e58b2079 200 194 supplementary_reverse m:27 ATTCACACGG..........aaaaCCCGTGCGATGGTTTGTCAG
0.1eeec2a8-fbef-454c-a73f-a56645454a50 200 194 primary_forward m:25 ATTCACACGG..........aaaaCCCGTGCGATGGTTTGTCAG
...
In the output, lowercase letters indicate bases that are insertions (present in the read but not in the reference).
Viewing Deletions
Deletions are automatically shown as periods (.) when displaying sequences from a region.
We demonstrate usage using a file with indels in it.
nanalogue read-table-show-mods --tag m --region contig_00001:80-120 \
--seq-region contig_00001:80-120 input_indels.bam
Example output:
# mod-unmod threshold is 0.5
read_id align_length sequence_length_template alignment_type mod_count sequence
0.1eeec2a8-fbef-454c-a73f-a56645454a50 200 194 primary_forward m:25 ATTCACACGG..........AAAACCCGTGCGATGGTTTGTCAG
0.776541e0-2398-446c-a113-bbb1b394a3e5 200 194 supplementary_reverse m:27 ATTCACACGG..........AAAACCCGTGCGATGGTTTGTCAG
0.cb4ce193-cea4-4ce3-8b68-07081786c8ad 200 194 primary_reverse m:27 ATTCACACGG..........AAAACCCGTGCGATGGTTTGTCAG
...
Each period represents a position where the reference has a base but the read does not.
Viewing Modification Patterns
To mark modified bases in the sequence, use --show-mod-z:
nanalogue read-table-show-mods --tag m --region contig_00001:80-120 \
--seq-region contig_00001:80-120 --show-mod-z input.bam
Example output:
# mod-unmod threshold is 0.5
read_id align_length sequence_length_template alignment_type mod_count sequence
0.3b25f6e5-da1b-41bd-a1f2-61415d4e88b5 320 320 primary_forward m:53 AGZGGZTZT
0.9a0352ad-2c37-4078-be82-a2e2a05414cb 283 283 supplementary_reverse m:43 CTCACZTZZZAZACTGTTATAGTTTACCATTAGCZZCTCT
Modified bases are displayed as:
Zfor modified bases on the referencezfor modified bases within an insertion (when combined with--show-ins-lowercase)
In the above example, you may see sequences of varying length.
This is because not all the reads will pass through the given region in full.
To only include such reads and thus ensure more uniformity, you can use --full-region as shown below.
nanalogue read-table-show-mods --tag m --region contig_00001:80-120 \
--seq-region contig_00001:80-120 --show-mod-z --full-region input.bam
Example output:
# mod-unmod threshold is 0.5
read_id align_length sequence_length_template alignment_type mod_count sequence
0.9a0352ad-2c37-4078-be82-a2e2a05414cb 283 283 supplementary_reverse m:43 CTCACZTZZZAZACTGTTATAGTTTACCATTAGCZZCTCT
Combining Display Options
You can combine multiple flags to see insertions, deletions, modifications, and quality scores all at once. We demonstrate usage using a file with indels in it.
nanalogue read-table-show-mods --tag m --region contig_00001:80-120 \
--seq-region contig_00001:80-120 \
--show-ins-lowercase --show-mod-z --show-base-qual \
input_indels.bam
Example output:
# mod-unmod threshold is 0.5
read_id align_length sequence_length_template alignment_type mod_count sequence qualities
0.e8556d24-2255-4c0a-a7f8-9a24e58b2079 200 194 supplementary_reverse m:27 ATTCACACGG..........aaaaCCCGTZCZATZZTTTZTCAG 40.39.24.27.26.32.34.32.37.40.255.255.255.255.255.255.255.255.255.255.36.20.27.22.40.21.22.22.28.37.40.20.20.40.23.24.38.32.38.30.21.22.27.25
0.8b4713fc-36fa-47b6-b3ef-46aa59ae5ce8 200 194 secondary_reverse m:27 ATTCACACGG..........aaaaCCCGTZCZATZZTTTZTCAG 20.22.33.27.22.37.29.21.28.26.255.255.255.255.255.255.255.255.255.255.30.24.37.30.29.21.30.23.36.21.28.39.27.34.29.32.20.21.40.39.30.24.32.22
0.1eeec2a8-fbef-454c-a73f-a56645454a50 200 194 primary_forward m:25 ATTCAZAZGG..........aaaaZZZGTGCGATGGTTTGTCAG 39.24.35.29.37.29.39.40.28.39.255.255.255.255.255.255.255.255.255.255.29.28.30.21.29.35.31.32.35.34.35.21.21.27.37.34.35.29.37.27.27.34.31.20
...
This produces output with:
- Lowercase letters for insertions
- Periods for deletions
Z/zfor modifications- Quality scores as period-separated integers (with
255for deleted positions)
When to Use read-table-hide-mods
The read-table-hide-mods command is a simpler alternative when you don't need modification information.
It supports the same sequence display options (--seq-region, --seq-full, --show-ins-lowercase, --show-base-qual)
but does not include --show-mod-z or modification-related filters.
We demonstrate usage using a file with indels in it.
Use read-table-hide-mods when:
- Your BAM file doesn't have modification data
- You only care about alignment quality (insertions/deletions)
- You want slightly faster processing by skipping modification parsing
nanalogue read-table-hide-mods --region contig_00001:80-120 \
--seq-region contig_00001:80-120 --show-ins-lowercase input_indels.bam
Example output:
read_id align_length sequence_length_template alignment_type sequence
0.8b4713fc-36fa-47b6-b3ef-46aa59ae5ce8 200 194 secondary_reverse ATTCACACGG..........aaaaCCCGTGCGATGGTTTGTCAG
0.776541e0-2398-446c-a113-bbb1b394a3e5 200 194 supplementary_reverse ATTCACACGG..........aaaaCCCGTGCGATGGTTTGTCAG
0.cb4ce193-cea4-4ce3-8b68-07081786c8ad 200 194 primary_reverse ATTCACACGG..........aaaaCCCGTGCGATGGTTTGTCAG
0.e8556d24-2255-4c0a-a7f8-9a24e58b2079 200 194 supplementary_reverse ATTCACACGG..........aaaaCCCGTGCGATGGTTTGTCAG
...
Creating Test Data
To create your own BAM files with insertions, deletions, and modifications for testing, see Test data with indels.
Next Steps
- Quality control of mod data — Assess modification call quality
- Extract raw mod calls — Get detailed modification data
- Finding highly modified reads — Filter reads by modification level
See Also
- Quick look at your data — Initial data inspection
- CLI Reference — Full documentation of all nanalogue commands
- Recipes — Quick copy-paste snippets