eduKateSG · Why Science?
Find alignments in one genomic interval without scanning an entire BAM—while respecting coordinate order, virtual offsets and index limits
Choose the closest route, then return to the full index whenever you need the wider evidence chain.
Science learning becomes powerful when students can tell a measured pattern from a model, a statistical decision from a mechanism, and a useful lead from a finished conclusion. A BAM index, commonly stored as BAI, is a binary companion that maps reference-coordinate regions to chunks of a coordinate-sorted BAM file. The SAM/BAM specification describes a hierarchical binning index plus a linear index in 16-kilobase windows. Chunks store BGZF virtual offsets, allowing software to seek near candidate alignments and then filter decoded records for true overlap. BAI is efficient and widely supported, but it has a fixed coordinate range and is tied to one exact BAM byte stream. An index does not repair unsorted records, validate alignments or confer biological meaning. This guide supports Primary Science, PSLE Science, Secondary Science, O-Level Science and STEM education as a longform evidence-reading route; it is not medical advice, a laboratory protocol, an admission promise or a career guarantee.
Related eduKate reading: BAM and binary sequence alignment storage; SAM and human-readable sequence alignments; BED and genomic feature coordinates; Science Learning Hub; Education Hub; STEM Education; Careers by Subject Capability.
Primary and official sources checked on 12 October 2026: Official SAM/BAM Format Specification Working Group specification, version 1.6, 12 August 2025; Official CSI index specification and BAI-compatible parameter description; Official SAMtools index manual, current documentation viewed 12 October 2026; 2026 Singapore–Cambridge O-Level Biology syllabus; MOE G2/G3 Lower Secondary Science teaching and learning syllabus; 2026 MOE G2 Computing syllabus. Specifications, tools and recommendations can change, so preserve the dated documentation, exact source bytes, parser rules and software versions used.
A deeper reading route
BAI is a search map, not a second copy of the alignments. The BAM header supplies the reference dictionary, the BAM records supply genomic coordinates, and the index points to compressed chunks likely to contain overlaps. A regional query still decodes records and applies overlap logic because bins are deliberately coarse. This separation keeps the index compact and retrieval fast.
The binning scheme is hierarchical. Small intervals are assigned to fine bins, while longer intervals can live in broader bins. A query interval is mapped to every bin that could contain an overlapping record. The reader then gathers associated file chunks. The hierarchy limits how much irrelevant data must be read without maintaining one index entry per base.
The linear index complements binning. For each reference, it stores the smallest virtual offset associated with successive 16-kilobase windows. A reader can use the window containing the query start to discard chunks that end too early. Binning narrows spatial candidates; the linear index provides an additional lower-bound shortcut.
Chunks are half-open ranges of BGZF virtual offsets. They identify byte-stream regions, not biological intervals. Adjacent or overlapping chunks may be merged to avoid repeated reads. Because the offsets depend on BGZF blocks, any BAM rewrite, recompression, header edit or record reorder can make a previously correct BAI stale.
BAI’s fixed hierarchy has a maximum addressable reference coordinate of 512 mebibases. That is sufficient for many commonly used references but not all assemblies or contigs. CSI generalises the same idea with configurable minimum shift and depth. Choosing BAI because it is familiar is unsafe when the reference exceeds its representable range.
Unmapped and coordinate-less records deserve explicit treatment. BAM coordinate sorting can place records without coordinates after mapped records, and BAI may store a count of unplaced unmapped records. A regional query is not a complete accounting of the file. Whole-file quality summaries need the BAM itself and clear handling of records that no genomic interval can retrieve.
A reliable implementation also guards the binary parser itself. Reference counts, bin counts, chunk counts and interval counts arrive from the file and must be checked before memory allocation. Virtual offsets should be monotonic within a chunk, chunk beginnings should not exceed their ends, and reserved bins need their specified interpretation. These checks protect availability and prevent a damaged index from being mistaken for an empty biological region.
Operationally, BAI should be treated as rebuildable derived data. The durable objects are the BAM records, header, reference identity and workflow provenance. Rebuilding the index in a clean environment and obtaining the same regional record sets is a stronger preservation test than merely copying an old .bai. It also reveals hidden dependencies on filenames, stale caches or one software version.
For students, BAI resembles a library catalogue with shelves nested by area. The catalogue sends you to a small run of shelves, but you still inspect each book to find the exact paragraph. That analogy makes two habits memorable: an index speeds discovery, and the source remains the evidence.
| Stage | Question | Evidence | Responsible output |
|---|---|---|---|
| Order | Is the BAM organised for coordinate lookup? | Header dictionary and verified coordinate sort | An indexable alignment stream |
| Map | Which bins and windows may contain the query? | Hierarchical bins plus 16-kilobase linear windows | Candidate chunks |
| Seek | Where are those chunks in BGZF? | Virtual offset begin and end pairs | Selective decompression |
| Verify | Does the index match the BAM and reference limits? | Hashes, range tests and full-scan comparisons | Trustworthy regional retrieval |
Inside this guide
1–12 · Foundations and design
- 1. Start with a regional question
- 2. Use the current specification
- 3. Treat BAI as a companion
- 4. Check the BAI magic
- 5. Match reference counts
- 6. Require coordinate sorting
- 7. Understand hierarchical bins
- 8. Use zero-based half-open intervals internally
- 9. Map queries to candidate bins
- 10. Read chunks as file ranges
- 11. Merge chunks safely
- 12. Use the linear index
13–24 · Models and estimation
- 13. Treat absent windows carefully
- 14. Understand virtual offsets
- 15. Know the 512-mebibase limit
- 16. Choose CSI when needed
- 17. Handle placed unmapped records
- 18. Handle unplaced unmapped records
- 19. Read metadata pseudo-bins
- 20. Do not infer coverage from chunks
- 21. Protect freshness after edits
- 22. Check naming conventions
- 23. Test empty references
- 24. Test boundary queries
25–36 · Diagnostics and interpretation
- 25. Compare with a full scan
- 26. Check duplicate retrieval
- 27. Plan remote retrieval
- 28. Connect to Primary Science
- 29. Connect to Secondary Science
- 30. Connect to mathematics
- 31. Connect to computing
- 32. Connect to pathways
- 33. Did you know?
- 34. Write a reader-ready indexing note
- 35. Build a validation ladder
- 36. Finish with a reproducible bundle
Section 1 of 36
1. Start with a regional question
BAI is designed to retrieve coordinate-overlapping alignments from BAM. Write the reference sequence and half-open query interval before examining the index.
Working checkpoint — BAI: Keep query coordinates, reference identity and BAM hash together. Keep BAM and BAI hashes, header dictionary, verified coordinate order, builder and boundary tests together.
For a classroom model, index fictional cards in nested location boxes.
Section 2 of 36
2. Use the current specification
The SAM/BAM version 1.6 specification dated 12 August 2025 contains the canonical BAI description.
Working checkpoint — BAM index: Record the specification and indexing software version. Read every regional result beside the same full-scan filter and the reference interval actually requested.
For future study, connect interval search to biology, mathematics and systems engineering while checking pathways separately.
Section 3 of 36
3. Treat BAI as a companion
The index depends on the BAM header, record order and BGZF byte layout. It is not meaningful as a standalone biological dataset.
Working checkpoint — binning index: Pair it with the exact BAM by hash rather than basename alone. Preserve unplaced and unmapped records; a regional view is never the complete file.
For scientific writing, report source identity, sort contract, index limits and comparison tests.
Section 4 of 36
4. Check the BAI magic
The binary file begins with the specified BAI magic bytes and then reference-index structures. An extension alone does not establish type.
Working checkpoint — linear index: Validate magic and length before allocating structures. Separate efficient retrieval from alignment accuracy, coverage, mechanism and clinical meaning.
For students, ask how a catalogue narrows the shelves without deciding which book is correct.
Section 5 of 36
5. Match reference counts
BAI stores an index for references corresponding to the BAM reference dictionary. Count or order mismatch makes numeric reference IDs ambiguous.
Working checkpoint — chunk: Compare BAI reference count with the decoded BAM header. Treat virtual offsets, reference order and coordinate conversion as scientific inputs: one stale companion can hide evidence.
For parents, ask whether indexed speed was tested against a complete scan.
Section 6 of 36
6. Require coordinate sorting
Binning and linear offsets assume records are grouped by reference and leftmost coordinate. An incorrect sort declaration can create incomplete queries.
Working checkpoint — virtual offset: Scan actual order before trusting or rebuilding the index. Keep BAM and BAI hashes, header dictionary, verified coordinate order, builder and boundary tests together.
For a classroom model, index fictional cards in nested location boxes.
Section 7 of 36
7. Understand hierarchical bins
BAI uses nested genomic bins at several scales. A record is placed in the smallest bin able to contain its alignment interval.
Working checkpoint — BAI: Test short, long and boundary-spanning alignments. Read every regional result beside the same full-scan filter and the reference interval actually requested.
For future study, connect interval search to biology, mathematics and systems engineering while checking pathways separately.
Section 8 of 36
8. Use zero-based half-open intervals internally
Indexing calculations use zero-based half-open coordinates even though SAM POS is displayed one-based. The codec must convert consistently.
Working checkpoint — BAM index: Add first-base and one-base fixtures for off-by-one detection. Preserve unplaced and unmapped records; a regional view is never the complete file.
For scientific writing, report source identity, sort contract, index limits and comparison tests.
Section 9 of 36
9. Map queries to candidate bins
A query interval can overlap bins at several hierarchy levels. The reader enumerates all relevant bins rather than guessing one.
Working checkpoint — binning index: Compare bin enumeration with the specification algorithm. Separate efficient retrieval from alignment accuracy, coverage, mechanism and clinical meaning.
For students, ask how a catalogue narrows the shelves without deciding which book is correct.
Section 10 of 36
10. Read chunks as file ranges
Each bin holds chunks described by virtual-offset beginnings and ends. They delimit compressed-file work, not biological certainty.
Working checkpoint — linear index: Decode records and apply an exact overlap filter after seeking. Treat virtual offsets, reference order and coordinate conversion as scientific inputs: one stale companion can hide evidence.
For parents, ask whether indexed speed was tested against a complete scan.
Section 11 of 36
11. Merge chunks safely
Chunks can overlap or touch and may be coalesced to reduce seeks. Incorrect merging can skip data or read needless regions.
Working checkpoint — chunk: Preserve half-open range rules and monotonic order. Keep BAM and BAI hashes, header dictionary, verified coordinate order, builder and boundary tests together.
For a classroom model, index fictional cards in nested location boxes.
Section 12 of 36
12. Use the linear index
BAI’s linear component records offsets for successive 16-kilobase windows and helps ignore chunks ending before the query region.
Working checkpoint — virtual offset: Test windows with no records and windows at reference ends. Read every regional result beside the same full-scan filter and the reference interval actually requested.
For future study, connect interval search to biology, mathematics and systems engineering while checking pathways separately.
Section 13 of 36
13. Treat absent windows carefully
A missing or zero linear entry can reflect no usable offset for that window, not a biological absence of alignments everywhere nearby.
Working checkpoint — BAI: Follow fallback rules rather than converting zero to no coverage. Preserve unplaced and unmapped records; a regional view is never the complete file.
For scientific writing, report source identity, sort contract, index limits and comparison tests.
Section 14 of 36
14. Understand virtual offsets
A BAI chunk boundary combines a BGZF block address and an uncompressed in-block position. It is tied to exact compressed bytes.
Working checkpoint — BAM index: Never substitute a plain file byte offset. Separate efficient retrieval from alignment accuracy, coverage, mechanism and clinical meaning.
For students, ask how a catalogue narrows the shelves without deciding which book is correct.
Section 15 of 36
15. Know the 512-mebibase limit
The fixed BAI binning scheme cannot represent coordinates at or beyond its designed range. Some references therefore require CSI.
Working checkpoint — binning index: Check every contig length before choosing BAI. Treat virtual offsets, reference order and coordinate conversion as scientific inputs: one stale companion can hide evidence.
For parents, ask whether indexed speed was tested against a complete scan.
Section 16 of 36
16. Choose CSI when needed
CSI generalises binning with configurable minimum shift and depth, avoiding BAI’s fixed ceiling. Tool support and downstream consumers still matter.
Working checkpoint — linear index: Document why the chosen index format fits the reference. Keep BAM and BAI hashes, header dictionary, verified coordinate order, builder and boundary tests together.
For a classroom model, index fictional cards in nested location boxes.
Section 17 of 36
17. Handle placed unmapped records
An unmapped read may retain a reference and coordinate based on its mapped mate and can therefore appear among coordinate-sorted records.
Working checkpoint — chunk: Use FLAG and coordinate fields together during filtering. Read every regional result beside the same full-scan filter and the reference interval actually requested.
For future study, connect interval search to biology, mathematics and systems engineering while checking pathways separately.
Section 18 of 36
18. Handle unplaced unmapped records
Records with no reference coordinate usually appear at the end and cannot be found by an ordinary regional query.
Working checkpoint — virtual offset: Use whole-file scans when counting every record. Preserve unplaced and unmapped records; a regional view is never the complete file.
For scientific writing, report source identity, sort contract, index limits and comparison tests.
Section 19 of 36
19. Read metadata pseudo-bins
BAI can carry a reserved metadata bin containing reference-level virtual-offset and mapped or unmapped counts. It should not be treated as a genomic bin.
Working checkpoint — BAI: Parse reserved bins by definition and validate count semantics. Separate efficient retrieval from alignment accuracy, coverage, mechanism and clinical meaning.
For students, ask how a catalogue narrows the shelves without deciding which book is correct.
Section 20 of 36
20. Do not infer coverage from chunks
A chunk says where relevant records may reside, not how many bases are covered or whether an alignment is high quality.
Working checkpoint — BAM index: Compute coverage from decoded, filtered records. Treat virtual offsets, reference order and coordinate conversion as scientific inputs: one stale companion can hide evidence.
For parents, ask whether indexed speed was tested against a complete scan.
Section 21 of 36
21. Protect freshness after edits
Changing a header, filtering records, marking duplicates, resorting or recompressing changes offsets or contents.
Working checkpoint — binning index: Regenerate BAI after every BAM rewrite. Keep BAM and BAI hashes, header dictionary, verified coordinate order, builder and boundary tests together.
For a classroom model, index fictional cards in nested location boxes.
Section 22 of 36
22. Check naming conventions
A BAM index may be stored as file.bam.bai or file.bai depending on tools. Discovery by name must still verify content identity.
Working checkpoint — linear index: Prefer explicit paths and hashes in workflows. Read every regional result beside the same full-scan filter and the reference interval actually requested.
For future study, connect interval search to biology, mathematics and systems engineering while checking pathways separately.
Section 23 of 36
23. Test empty references
The reference dictionary can include sequences with no alignments. Their index structures must be handled without shifting later reference IDs.
Working checkpoint — chunk: Include empty contigs in validation fixtures. Preserve unplaced and unmapped records; a regional view is never the complete file.
For scientific writing, report source identity, sort contract, index limits and comparison tests.
Section 24 of 36
24. Test boundary queries
Queries starting or ending exactly at bin and window boundaries expose interval and conversion errors.
Working checkpoint — virtual offset: Use zero-length-invalid, one-base and boundary-spanning tests. Separate efficient retrieval from alignment accuracy, coverage, mechanism and clinical meaning.
For students, ask how a catalogue narrows the shelves without deciding which book is correct.
Section 25 of 36
25. Compare with a full scan
A trustworthy index should return the same qualifying records as a sequential BAM scan for representative regions.
Working checkpoint — BAI: Compare names, coordinates and counts across both routes. Treat virtual offsets, reference order and coordinate conversion as scientific inputs: one stale companion can hide evidence.
For parents, ask whether indexed speed was tested against a complete scan.
Section 26 of 36
26. Check duplicate retrieval
The same record can be reached through overlapping candidate chunks if merging is wrong. Duplicating it biases counts.
Working checkpoint — BAM index: Detect duplicate virtual positions in test queries. Keep BAM and BAI hashes, header dictionary, verified coordinate order, builder and boundary tests together.
For a classroom model, index fictional cards in nested location boxes.
Section 27 of 36
27. Plan remote retrieval
BAI enables byte-range access to BAM stored remotely, but the server must support correct ranges and stable object identity.
Working checkpoint — binning index: Validate ETags or hashes, retries and partial responses. Read every regional result beside the same full-scan filter and the reference interval actually requested.
For future study, connect interval search to biology, mathematics and systems engineering while checking pathways separately.
Section 28 of 36
28. Connect to Primary Science
A classroom catalogue can point to boxes likely to contain observations, after which each card is checked exactly.
Working checkpoint — linear index: Use fictional labels and distinguish candidate boxes from confirmed matches. Preserve unplaced and unmapped records; a regional view is never the complete file.
For scientific writing, report source identity, sort contract, index limits and comparison tests.
Section 29 of 36
29. Connect to Secondary Science
An index speeds access to evidence but does not evaluate measurement quality, mapping ambiguity or experimental design.
Working checkpoint — chunk: Separate retrieval correctness from alignment validity. Separate efficient retrieval from alignment accuracy, coverage, mechanism and clinical meaning.
For students, ask how a catalogue narrows the shelves without deciding which book is correct.
Section 30 of 36
30. Connect to mathematics
Nested bins, powers of two, half-open intervals and range unions connect BAI to number systems and geometry.
Working checkpoint — virtual offset: Draw the bin hierarchy for a toy reference. Treat virtual offsets, reference order and coordinate conversion as scientific inputs: one stale companion can hide evidence.
For parents, ask whether indexed speed was tested against a complete scan.
Section 31 of 36
31. Connect to computing
Binary parsing, random access, caching and interval algorithms show how data structures make large scientific files usable.
Working checkpoint — BAI: Test malformed counts, offsets and truncated index files. Keep BAM and BAI hashes, header dictionary, verified coordinate order, builder and boundary tests together.
For a classroom model, index fictional cards in nested location boxes.
Section 32 of 36
32. Connect to pathways
Coordinate indexing connects genomics, algorithm design, storage systems and cloud infrastructure and can illuminate STEM pathways.
Working checkpoint — BAM index: Check current official qualifications separately. Read every regional result beside the same full-scan filter and the reference interval actually requested.
For future study, connect interval search to biology, mathematics and systems engineering while checking pathways separately.
Section 33 of 36
33. Did you know?
BAI uses both hierarchical bins and a 16-kilobase linear index; the two structures cooperate to reduce unnecessary reads.
Working checkpoint — binning index: Explain which filtering job belongs to each structure. Preserve unplaced and unmapped records; a regional view is never the complete file.
For scientific writing, report source identity, sort contract, index limits and comparison tests.
Section 34 of 36
34. Write a reader-ready indexing note
Name the BAM and hash, reference, sort order, BAI builder and version, coordinate limits, tests and retrieval software.
Working checkpoint — linear index: State whether unplaced records were included in summaries. Separate efficient retrieval from alignment accuracy, coverage, mechanism and clinical meaning.
For students, ask how a catalogue narrows the shelves without deciding which book is correct.
Section 35 of 36
35. Build a validation ladder
Check magic, reference count, sort order, bins, chunks, linear windows, virtual offsets, limits and full-scan equivalence.
Working checkpoint — chunk: Stop before scientific interpretation when retrieval differs. Treat virtual offsets, reference order and coordinate conversion as scientific inputs: one stale companion can hide evidence.
For parents, ask whether indexed speed was tested against a complete scan.
Section 36 of 36
36. Finish with a reproducible bundle
Deliver BAM and BAI hashes, header, indexing command, environment, boundary fixtures, full-scan comparisons and bounded outputs.
Working checkpoint — virtual offset: Make every regional result traceable to source records. Keep BAM and BAI hashes, header dictionary, verified coordinate order, builder and boundary tests together.
For a classroom model, index fictional cards in nested location boxes.
Contents · Previous section · Continue to the Science Learning Hub