@gmod/hic 1.3.2 → 2.1.0

package/src/hicFile.ts

@@ -5,7 +5,6 @@ import { LocalFile } from 'generic-filehandle2'
 import { binWindow } from './binWindow.ts'
 import BinaryParser from './binary.ts'
 import BufferedFile from './bufferedFile.ts'
-import LRU from './lru.ts'
 import Matrix from './matrix.ts'
 import NormalizationVector from './normalizationVector.ts'
 import { readerFromFilehandle } from './reader.ts'
@@ -16,6 +15,7 @@ import type {
   BaseOpts,
   BlockIndexEntry,
   Chromosome,
+  ExpectedValues,
   HicMetadata,
   HicRegion,
   ProgressOpts,
@@ -50,6 +50,36 @@ interface SignalOpts extends ProgressOpts {
   signal: AbortSignal
 }
 
+/** One expected-value vector: its values on disk and its chromosome scale factors. */
+interface ExpectedChunk {
+  vector: NormalizationVector
+  nValues: number
+  chrScaleFactors: Map<number, number>
+}
+
+/** A walked expected-value section, and where the next section starts. */
+interface ExpectedSection {
+  chunks: Map<string, ExpectedChunk>
+  end: number
+}
+
+function getExpectedKey(type: string, unit: string, binSize: number) {
+  return `${type}_${unit}_${binSize}`
+}
+
+// The range of `|bin2 - bin1|` over two half-open bin windows.
+function distanceRange(
+  [x1, x2]: readonly [number, number],
+  [y1, y2]: readonly [number, number],
+) {
+  const overlap = x1 < y2 && y1 < x2
+  const nearest = overlap
+    ? 0
+    : Math.min(Math.abs(y1 - (x2 - 1)), Math.abs(x1 - (y2 - 1)))
+  const farthest = Math.max(Math.abs(y2 - 1 - x1), Math.abs(x2 - 1 - y1))
+  return [nearest, farthest] as const
+}
+
 export interface HicConfig {
   /** a `generic-filehandle2` handle, e.g. `RemoteFile` for a URL */
   filehandle?: GenericFilehandle
@@ -66,8 +96,7 @@ export interface HicConfig {
   /**
    * Ceiling on the decompressed contacts the block cache holds, in bytes.
    * Defaults to 128 MB. Lower it where the budget is tight and re-reading is
-   * cheaper than the memory; raising it buys nothing once a fetch's working set
-   * fits, since the entry cap bounds the cache too.
+   * cheaper than the memory.
    */
   blockCacheMaxBytes?: number
 }
@@ -75,7 +104,7 @@ export interface HicConfig {
 // Cached blocks are the decompressed records and nothing else. hic-straw also
 // hung the MatrixZoomData and the block-index entry off each Block; neither was
 // ever read back, and the zoom data pinned a whole `blockIndex` record per
-// cached block for the lifetime of the LRU.
+// cached block for the lifetime of the cache.
 interface Block {
   blockNumber: number
   records: ContactRecords
@@ -122,15 +151,13 @@ function truncateRecords(records: ContactRecords, n: number): ContactRecords {
 // The cliffs are exactly these three capacities. Note the first column: 41% of a
 // cold whole-genome fetch's reads were re-reads of normalization vectors the
 // same fetch had already fetched.
-const BLOCK_CACHE_MAX_ENTRIES = 1024
-// The bound the entry cap was standing in for. Blocks became struct-of-arrays
-// (see contactRecords.ts), so a cached contact is 12 bytes of untraced
-// ArrayBuffer rather than ~55 on the GC-traced heap — but a block still holds
-// every contact in its bin square, which is the one thing here that can hold
-// real memory, and block sizes vary by more than an order of magnitude with
-// binsize. Measured on the file above: 0.05 MB at 2.5 Mb, 0.23 MB at 100 kb. So
-// the entry cap now tracks the working set and this tracks the memory, instead
-// of one number answering both badly. See LRU's WeightOpts.
+//
+// Blocks became struct-of-arrays (see contactRecords.ts), so a cached contact is
+// 12 bytes of untraced ArrayBuffer rather than ~55 on the GC-traced heap — but a
+// block still holds every contact in its bin square, which is the one thing here
+// that can hold real memory, and block sizes vary by more than an order of
+// magnitude with binsize. Measured on the file above: 0.05 MB at 2.5 Mb, 0.23 MB
+// at 100 kb. So the block cache's only bound is its byte budget.
 //
 // This is the one capacity here a caller can override (`blockCacheMaxBytes`),
 // because it is the only one that bounds MEMORY. The two entry caps below are
@@ -152,7 +179,10 @@ const NORM_VECTOR_CACHE_SIZE = 64
 // so no separate resolution generation is needed to keep entries apart —
 // hic-straw's extra `resolution` field only made the cache single-resolution
 // (every zoom step threw the previous level away).
-function blockCacheWeight(block: Block) {
+function blockCacheWeight(block: Block | undefined) {
+  if (!block) {
+    return 0
+  }
   const { bin1, bin2, counts } = block.records
   return bin1.byteLength + bin2.byteLength + counts.byteLength
 }
@@ -167,7 +197,7 @@ function getNormalizationVectorKey(
 }
 
 export class HicFile {
-  private config: HicConfig
+  private nvi: string | undefined
   private file: Reader
 
   // These caches share the in-flight read, not just its result. A
@@ -181,6 +211,9 @@ export class HicFile {
     string,
     NormVectorIndex | undefined
   >()
+  // 'raw' and 'normalized', each walked once: the sections carry no index, so
+  // a chunk's position is known only by walking every chunk before it.
+  private expectedSectionCache = new SharedReadCache<string, ExpectedSection>()
   private normVectorCache = new SharedReadCache<
     string,
     NormalizationVector | undefined
@@ -190,31 +223,32 @@ export class HicFile {
   })
   // Assigned in the constructor rather than here, since its byte budget is
   // configurable and a field initializer cannot see `config`.
-  private blockCache: LRU<string, Block>
+  private blockCache: SharedReadCache<string, Block | undefined>
   private normVectorIndexPosition = -1
   private normVectorIndexSize = -1
 
   private version = 0
   private genomeId = ''
   private footerPosition = 0
+  // Where the raw (NONE) expected values begin, right after the master index.
+  private expectedValuesPosition = 0
   // Where the file's normalization data begins, and so also where a file
   // carrying none of it ends. Public so a test can cut a real file there to
   // make that second shape.
   normExpectedValueVectorsPosition: number | undefined
 
   private chromosomes: Chromosome[] = []
-  private chromosomeIndexMap: Record<string, number> = {}
-  private chrAliasTable: Record<string, string> = {}
+  private chromosomeIndexMap = new Map<string, number>()
   private bpResolutions: number[] = []
   private masterIndex: Record<string, MasterIndexEntry> = {}
   private meta: HicMetadata | undefined
 
   constructor(config: HicConfig) {
-    const { filehandle, path, reader, blockCacheMaxBytes } = config
-    this.config = config
-    this.blockCache = new LRU<string, Block>(BLOCK_CACHE_MAX_ENTRIES, {
-      maxBytes: blockCacheMaxBytes ?? BLOCK_CACHE_MAX_BYTES,
-      weigh: blockCacheWeight,
+    const { filehandle, path, reader, nvi, blockCacheMaxBytes } = config
+    this.nvi = nvi
+    this.blockCache = new SharedReadCache({
+      maxSize: blockCacheMaxBytes ?? BLOCK_CACHE_MAX_BYTES,
+      sizeOf: blockCacheWeight,
     })
     if (reader) {
       this.file = reader
@@ -255,8 +289,11 @@ export class HicFile {
     }
     const footerPosition = binaryParser.getLong()
 
-    const { masterIndex, normExpectedValueVectorsPosition } =
-      await this.readFooter(version, footerPosition, signal)
+    const {
+      masterIndex,
+      expectedValuesPosition,
+      normExpectedValueVectorsPosition,
+    } = await this.readFooter(version, footerPosition, signal)
 
     const bodyPosition = Object.values(masterIndex).reduce(
       (min, entry) => Math.min(min, entry.start),
@@ -282,7 +319,7 @@ export class HicFile {
     }
 
     const chromosomes: Chromosome[] = []
-    const chromosomeIndexMap: Record<string, number> = {}
+    const chromosomeIndexMap = new Map<string, number>()
     let nChrs = binaryParser.getInt()
     let i = 0
     while (nChrs-- > 0) {
@@ -292,7 +329,7 @@ export class HicFile {
         size: version < 9 ? binaryParser.getInt() : binaryParser.getLong(),
       }
       chromosomes.push(chr)
-      chromosomeIndexMap[chr.name] = chr.index
+      chromosomeIndexMap.set(chr.name, chr.index)
       i++
     }
 
@@ -302,20 +339,10 @@ export class HicFile {
       bpResolutions.push(binaryParser.getInt())
     }
 
-    const chrAliasTable: Record<string, string> = {}
-    for (const chrName of Object.keys(chromosomeIndexMap)) {
-      if (chrName.startsWith('chr')) {
-        chrAliasTable[chrName.slice(3)] = chrName
-      } else if (chrName === 'MT') {
-        chrAliasTable.chrM = chrName
-      } else {
-        chrAliasTable[`chr${chrName}`] = chrName
-      }
-    }
-
     throwIfAborted(signal)
     this.version = version
     this.footerPosition = footerPosition
+    this.expectedValuesPosition = expectedValuesPosition
     this.masterIndex = masterIndex
     this.normExpectedValueVectorsPosition = normExpectedValueVectorsPosition
     this.genomeId = genomeId
@@ -324,7 +351,6 @@ export class HicFile {
     this.chromosomes = chromosomes
     this.chromosomeIndexMap = chromosomeIndexMap
     this.bpResolutions = bpResolutions
-    this.chrAliasTable = chrAliasTable
     this.meta = {
       version,
       genome: genomeId,
@@ -364,10 +390,15 @@ export class HicFile {
       masterIndex[key] = { start: pos, size }
     }
 
+    const expectedValuesPosition = footerPosition + skip + binaryParser.position
     // Normalized expected values start after the expected values
     const normExpectedValueVectorsPosition =
       version > 5 ? footerPosition + (version < 9 ? 4 : 8) + nBytes : undefined
-    return { masterIndex, normExpectedValueVectorsPosition }
+    return {
+      masterIndex,
+      expectedValuesPosition,
+      normExpectedValueVectorsPosition,
+    }
   }
 
   async getMatrix(chrIdx1: number, chrIdx2: number, opts?: BaseOpts) {
@@ -397,14 +428,13 @@ export class HicFile {
     normalization: string,
     region1: HicRegion,
     region2: HicRegion,
-    units: string,
     binsize: number,
     opts?: ProgressOpts,
   ) {
     await this.init(opts)
 
-    const idx1 = this.chromosomeIndexMap[this.getFileChrName(region1.chr)]
-    const idx2 = this.chromosomeIndexMap[this.getFileChrName(region2.chr)]
+    const idx1 = this.chromosomeIndexMap.get(region1.chr)
+    const idx2 = this.chromosomeIndexMap.get(region2.chr)
 
     // A `.hic` stores only `bin1 <= bin2`, so a query whose x window sits to the
     // right of its y window has to be swapped or it asks for the half of the
@@ -444,7 +474,7 @@ export class HicFile {
     // resolved once per pair rather than per block, each paired with the bin
     // offset its values start at.
     const [norm, blocks] = await Promise.all([
-      this.getNormVectors(normalization, r1, r2, units, binsize, opts),
+      this.getNormVectors(normalization, r1, r2, binsize, opts),
       // The measurable half of the pair: blocks are counted and the two norm
       // vectors are not, because the vector chain is two hops whatever the
       // query and the block chain is the one that grows with the region.
@@ -522,9 +552,8 @@ export class HicFile {
     //
     // `transposed` says the query was swapped, so `bin1` runs along `region2`.
     // Reported rather than left for the caller to re-derive: it is decided here
-    // from this file's own alias table and chromosome indices, and a caller
-    // re-deriving it off a divergent chr-name scheme would silently un-swap the
-    // wrong axis.
+    // from this file's chromosome indices, which a caller would otherwise have
+    // to look up again to know which axis to un-swap.
     return {
       records: contactRecords,
       appliedNormalization: norm ? normalization : 'NONE',
@@ -536,59 +565,29 @@ export class HicFile {
     normalization: string,
     r1: HicRegion,
     r2: HicRegion,
-    units: string,
     binsize: number,
     opts?: BaseOpts,
   ) {
+    if (!normalization || normalization === 'NONE') {
+      return undefined
+    }
     const signalOpts = { signal: opts?.signal }
-    let result:
-      | {
-          v1: Float64Array
-          v2: Float64Array
-          offset1: number
-          offset2: number
-        }
-      | undefined
-    if (normalization && normalization !== 'NONE') {
-      const chr1 = this.getFileChrName(r1.chr)
-      const chr2 = this.getFileChrName(r2.chr)
-      const offset1 = Math.floor(r1.start / binsize)
-      const offset2 = Math.floor(r2.start / binsize)
-      const nv1 = await this.getNormalizationVector(
-        normalization,
-        chr1,
-        units,
-        binsize,
-        signalOpts,
-      )
-      const nv2 =
-        chr1 === chr2
-          ? nv1
-          : await this.getNormalizationVector(
-              normalization,
-              chr2,
-              units,
-              binsize,
-              signalOpts,
-            )
-      if (nv1 && nv2) {
-        result = {
-          v1: await nv1.getValues(
-            offset1,
-            Math.ceil(r1.end / binsize),
-            signalOpts,
-          ),
-          v2: await nv2.getValues(
-            offset2,
-            Math.ceil(r2.end / binsize),
-            signalOpts,
-          ),
-          offset1,
-          offset2,
-        }
-      }
+    const [offset1, end1] = binWindow(r1, binsize)
+    const [offset2, end2] = binWindow(r2, binsize)
+    // Awaited in sequence, an inter-chromosomal pair would pay four
+    // round-trip waves for what is two hops per vector.
+    const [nv1, nv2] = await Promise.all([
+      this.getNormalizationVector(normalization, r1.chr, binsize, signalOpts),
+      this.getNormalizationVector(normalization, r2.chr, binsize, signalOpts),
+    ])
+    if (!nv1 || !nv2) {
+      return undefined
     }
-    return result
+    const [v1, v2] = await Promise.all([
+      nv1.getValues(offset1, end1, signalOpts),
+      nv2.getValues(offset2, end2, signalOpts),
+    ])
+    return { v1, v2, offset1, offset2 }
   }
 
   async getBlocks(
@@ -601,10 +600,8 @@ export class HicFile {
       `${zd.getKey()}_${blockNumber}`
 
     await this.init(opts)
-    const chr1 = this.getFileChrName(region1.chr)
-    const chr2 = this.getFileChrName(region2.chr)
-    const idx1 = this.chromosomeIndexMap[chr1]
-    const idx2 = this.chromosomeIndexMap[chr2]
+    const idx1 = this.chromosomeIndexMap.get(region1.chr)
+    const idx2 = this.chromosomeIndexMap.get(region2.chr)
 
     let blocks: (Block | undefined)[] = []
     if (idx1 === undefined) {
@@ -627,45 +624,42 @@ export class HicFile {
         }
 
         const blockNumbers = zd.getBlockNumbers(region1, region2, this.version)
-        const blockNumbersToQuery: number[] = []
-        for (const num of blockNumbers) {
-          const cached = this.blockCache.get(blockKey(num, zd))
-          if (cached) {
-            blocks.push(cached)
-          } else {
-            blockNumbersToQuery.push(num)
-          }
-        }
+        const keys = blockNumbers.map(num => blockKey(num, zd))
+        const cached = keys.map(key => this.blockCache.has(key))
 
         // Cached blocks are already done, not absent: a pan that reuses most
         // of its blocks reads most of the way along rather than restarting at
         // zero, which is what the bar should say — the work left is the reads.
+        // A block another fetch has in flight counts as cached too.
         //
         // A query covering no blocks at all reports nothing rather than `0, 0`:
         // there is no fraction in it, and a caller dividing would get NaN.
         const { onProgress } = opts ?? {}
-        let done = blocks.length
-        if (blockNumbers.length > 0) {
-          onProgress?.(done, blockNumbers.length)
+        const total = blockNumbers.length
+        let done = cached.filter(Boolean).length
+        if (total > 0) {
+          onProgress?.(done, total)
         }
-        // Still one `Promise.all`, so every block is still issued in one wave:
-        // what a remote file pays is round-trip DEPTH, and counting the
-        // completions must not turn one wave into a queue. `readChainDepth`
-        // pins that.
-        const newBlocks = await Promise.all(
-          blockNumbersToQuery.map(async blockNumber => {
-            const block = await this.readBlock(blockNumber, zd, signalOpts)
-            done++
-            onProgress?.(done, blockNumbers.length)
+        // One `Promise.all`, so every block is issued in one wave: what a
+        // remote file pays is round-trip DEPTH, and counting the completions
+        // must not turn one wave into a queue. `readChainDepth` pins that.
+        //
+        // A block number missing from the index has no data, so it skips the
+        // cache, which would otherwise keep a weightless entry for it forever.
+        blocks = await Promise.all(
+          blockNumbers.map(async (num, i) => {
+            const block = zd.blockIndex[num]
+              ? await this.blockCache.get(keys[i]!, opts?.signal, signal =>
+                  this.readBlock(num, zd, { signal }),
+                )
+              : undefined
+            if (!cached[i]) {
+              done++
+              onProgress?.(done, total)
+            }
             return block
           }),
         )
-        for (const block of newBlocks) {
-          if (block) {
-            this.blockCache.set(blockKey(block.blockNumber, zd), block)
-          }
-        }
-        blocks = blocks.concat(newBlocks)
       }
     }
     return blocks
@@ -793,17 +787,16 @@ export class HicFile {
   async getNormalizationVector(
     type: string,
     chr: string,
-    unit: string,
     binSize: number,
     opts?: BaseOpts,
   ) {
     await this.init(opts)
 
-    const chrIdx = this.chromosomeIndexMap[this.getFileChrName(chr)]
+    const chrIdx = this.chromosomeIndexMap.get(chr)
     if (chrIdx === undefined) {
       return undefined
     }
-    const key = getNormalizationVectorKey(type, chrIdx, unit, binSize)
+    const key = getNormalizationVectorKey(type, chrIdx, 'BP', binSize)
 
     // Sharing the in-flight read is what keeps concurrent region pairs sharing
     // one vector: a chromosome appears in every pair it takes part in, so with a
@@ -872,8 +865,8 @@ export class HicFile {
         },
         opts.signal,
       )
-    } else if (this.config.nvi) {
-      const nviArray = decodeURIComponent(this.config.nvi).split(',')
+    } else if (this.nvi) {
+      const nviArray = decodeURIComponent(this.nvi).split(',')
       return this.readNormVectorIndex(
         {
           start: parseInt(nviArray[0]!),
@@ -923,114 +916,210 @@ export class HicFile {
     const { signal } = opts
     let index: NormVectorIndex | undefined
     if (this.normExpectedValueVectorsPosition !== undefined) {
-      const nviStart = await this.skipExpectedValues(
-        this.normExpectedValueVectorsPosition,
-        opts,
-      )
-      let byteCount = INT
-
-      let data = await this.file.read(nviStart, INT, { signal })
+      const nviStart = (await this.getExpectedSection('normalized', opts)).end
+      const data = await this.file.read(nviStart, INT, { signal })
       // Possible if there are no norm vectors. A legal v8 file, though uncommon.
       if (data.byteLength !== 0) {
-        const binaryParser = new BinaryParser(new DataView(data))
-        const nEntries = binaryParser.getInt()
-        const sizeEstimate = nEntries * 30
-        data = await this.file.read(nviStart + byteCount, sizeEstimate, {
-          signal,
-        })
+        const nEntries = new BinaryParser(new DataView(data)).getInt()
         const found: NormVectorIndex = { entries: {}, types: ['NONE'] }
 
-        const processEntries = async (remaining: number, buf: ArrayBuffer) => {
-          const parser = new BinaryParser(new DataView(buf))
-          let n = remaining
-          while (n-- > 0) {
-            if (parser.available() < 100) {
-              n++ // Reset counter as entry is not processed
-              byteCount += parser.position
-              const est = Math.max(1000, n * 30)
-              const more = await this.file.read(nviStart + byteCount, est, {
-                signal,
-              })
-              await processEntries(n, more)
-              return
-            }
-            this.parseNormVectorEntry(parser, found)
+        let position = nviStart + INT
+        let requested = nEntries * 30
+        let buf = await this.file.read(position, requested, { signal })
+        let parser = new BinaryParser(new DataView(buf))
+        for (let n = nEntries; n > 0; n--) {
+          // A short read means the buffer already runs to EOF, and refilling
+          // it would only return the same bytes again.
+          if (parser.available() < 100 && buf.byteLength === requested) {
+            position += parser.position
+            requested = Math.max(1000, n * 30)
+            buf = await this.file.read(position, requested, { signal })
+            parser = new BinaryParser(new DataView(buf))
           }
-          byteCount += parser.position
+          this.parseNormVectorEntry(parser, found)
         }
-
-        await processEntries(nEntries, data)
         throwIfAborted(signal)
-        this.config.nvi = `${nviStart},${byteCount}`
         index = found
       }
     }
     return index
   }
 
-  // Used when the position of the norm vector index is unknown: skip the
-  // normalized expected values to find the index.
-  private async skipExpectedValues(start: number, opts: SignalOpts) {
+  /**
+   * The expected count for a region pair at `binsize`, the denominator of
+   * observed/expected, as straw computes it. `normalization` must be the one
+   * the pair's records carry (`getContactRecords`' `appliedNormalization`),
+   * since each normalization has its own vector. Undefined where the file has
+   * no expected value for it: no vector at this binsize, or a version 5 file
+   * asked for a normalized one.
+   *
+   * Within a chromosome the vector is read for only the distances the pair
+   * spans. Between chromosomes straw divides by the map's average contact, the
+   * raw `sumCounts` over its bins, whatever the normalization.
+   */
+  async getExpectedValues(
+    normalization: string,
+    region1: HicRegion,
+    region2: HicRegion,
+    binsize: number,
+    opts?: ProgressOpts,
+  ): Promise<ExpectedValues | undefined> {
+    await this.init(opts)
+    const idx1 = this.chromosomeIndexMap.get(region1.chr)
+    const idx2 = this.chromosomeIndexMap.get(region2.chr)
+    if (idx1 === undefined || idx2 === undefined) {
+      return undefined
+    }
+    if (idx1 !== idx2) {
+      const matrix = await this.getMatrix(idx1, idx2, opts)
+      const zd = matrix?.getZoomData(binsize)
+      if (!zd) {
+        return undefined
+      }
+      // straw's bin counts leave out a chromosome's partial last bin
+      const nBins1 = Math.max(
+        1,
+        Math.floor(this.chromosomes[idx1]!.size / binsize),
+      )
+      const nBins2 = Math.max(
+        1,
+        Math.floor(this.chromosomes[idx2]!.size / binsize),
+      )
+      return { kind: 'inter', average: zd.sumCounts / nBins1 / nBins2 }
+    }
+    const normalized = !!normalization && normalization !== 'NONE'
+    if (normalized && this.normExpectedValueVectorsPosition === undefined) {
+      return undefined
+    }
+    const section = await this.getExpectedSection(
+      normalized ? 'normalized' : 'raw',
+      opts ?? {},
+    )
+    const chunk = section.chunks.get(
+      getExpectedKey(normalized ? normalization : 'NONE', 'BP', binsize),
+    )
+    if (!chunk || chunk.nValues === 0) {
+      return undefined
+    }
+    const [first, last] = distanceRange(
+      binWindow(region1, binsize),
+      binWindow(region2, binsize),
+    )
+    const signalOpts = { signal: opts?.signal }
+    const stored = await chunk.vector.getValues(first, last + 1, signalOpts)
+    const tail =
+      stored.length < last + 1 - first
+        ? (
+            await chunk.vector.getValues(
+              chunk.nValues - 1,
+              chunk.nValues,
+              signalOpts,
+            )
+          )[0]!
+        : 0
+    // straw divides by 1 where the section names no factor for the chromosome
+    const factor = chunk.chrScaleFactors.get(idx1) ?? 1
+    const values = new Float64Array(last + 1 - first)
+    for (let i = 0; i < values.length; i++) {
+      values[i] = (i < stored.length ? stored[i]! : tail) / factor
+    }
+    return { kind: 'intra', firstDistance: first, values }
+  }
+
+  private async getExpectedSection(
+    section: 'raw' | 'normalized',
+    opts: ProgressOpts,
+  ) {
+    return this.expectedSectionCache.get(section, opts.signal, signal =>
+      this.walkExpectedSection(
+        section === 'raw'
+          ? this.expectedValuesPosition
+          : this.normExpectedValueVectorsPosition!,
+        section === 'normalized',
+        { signal, onProgress: opts.onProgress },
+      ),
+    )
+  }
+
+  // Walk one expected-value section, recording where each chunk's values sit
+  // and its chromosome scale factors. The normalized section's end is also
+  // where a pre-v9 file's normalization vector index begins.
+  //
+  // A chunk's two reads land a whole expected-value vector apart — one per bin
+  // of the genome's longest chromosome, so megabytes at a fine binsize — which
+  // is further than the buffer reaches. On a remote file that is two round
+  // trips per chunk that nothing can merge, and it is why this walk, not the
+  // index it leads to, is the slow part of opening a pre-v9 file. It is also
+  // why the chunk is the unit worth counting: known before the first read, each
+  // costing about the same. Chunks are walked in order, since each one's size
+  // is known only once the one before it has been parsed.
+  private async walkExpectedSection(
+    start: number,
+    normalized: boolean,
+    opts: SignalOpts,
+  ): Promise<ExpectedSection> {
     const { signal, onProgress } = opts
     const version = this.version
+    const valueSize = version < 9 ? DOUBLE : FLOAT
     const file = new BufferedFile({ file: this.file, size: 256000 })
+    const chunks = new Map<string, ExpectedChunk>()
     const data = await file.read(start, INT, { signal })
-    // A file with no normalization at all ends where this section would start,
-    // so the count this is about to read is past EOF. That is the same "no norm
-    // vectors" case `readNormExpectedValuesAndNormVectorIndex` guards its own
-    // read for, and it has to be caught HERE too, because this runs first:
-    // a v9 file that records no norm-vector-index position takes the v8
-    // discovery path, and that path starts by skipping a section that isn't
-    // there. Answering `start` leaves the caller's guard to do the rest.
+    // A file with no normalization at all ends where the normalized section
+    // would start, so the count this is about to read is past EOF. A v9 file
+    // that records no norm-vector-index position takes the v8 discovery path,
+    // which starts by walking a section that isn't there, so the empty answer
+    // has to come from here.
     if (data.byteLength < INT) {
-      return start
+      return { chunks, end: start }
     }
-    const binaryParser = new BinaryParser(new DataView(data))
-    const nEntries = binaryParser.getInt() // Total # of expected value chunks
-
-    // Skip one chunk, answering where the next one starts.
-    //
-    // Its two reads land a whole expected-value vector apart — one per bin of
-    // the genome, so tens of MB at a fine binsize — which is further than the
-    // buffer reaches. On a remote file that is two round trips per chunk that
-    // nothing can merge, and it is why this walk, not the index it is looking
-    // for, is the slow part of opening a pre-v9 file. It is also why the chunk
-    // is the unit worth counting: `nEntries` of them, known before the first
-    // read, each costing about the same.
-    const skipChunk = async (chunkStart: number) => {
-      let chunkSize = 0
-
-      let buf = await file.read(chunkStart, 500, { signal })
-      let parser = new BinaryParser(new DataView(buf))
-      parser.getString() // type
-      parser.getString() // unit
-      parser.getInt() // binSize
-      const nValues = version < 9 ? parser.getInt() : parser.getLong()
-      chunkSize += parser.position + nValues * (version < 9 ? DOUBLE : FLOAT)
-
-      buf = await file.read(chunkStart + chunkSize, INT, { signal })
-      parser = new BinaryParser(new DataView(buf))
-      const nChrScaleFactors = parser.getInt()
-      chunkSize +=
-        INT + nChrScaleFactors * (INT + (version < 9 ? DOUBLE : FLOAT))
-
-      return chunkStart + chunkSize
-    }
-
-    // A loop rather than the tail recursion this was, because the position is
-    // the only thing carried between chunks and a counter now rides along with
-    // it. Chunks must be walked in order — each one's size is only known once
-    // the one before it has been parsed — so the awaits are sequential by
-    // nature, not by oversight.
+    const nEntries = new BinaryParser(new DataView(data)).getInt()
     if (nEntries > 0) {
       onProgress?.(0, nEntries)
     }
     let position = start + INT
     for (let done = 0; done < nEntries; done++) {
-      position = await skipChunk(position)
+      let parser = new BinaryParser(
+        new DataView(await file.read(position, 500, { signal })),
+      )
+      const type = normalized ? parser.getString() : 'NONE'
+      const unit = parser.getString()
+      const binSize = parser.getInt()
+      const nValues = version < 9 ? parser.getInt() : parser.getLong()
+      const valuesPosition = position + parser.position
+      const factorsPosition = valuesPosition + nValues * valueSize
+
+      parser = new BinaryParser(
+        new DataView(await file.read(factorsPosition, INT, { signal })),
+      )
+      const nFactors = parser.getInt()
+      const factorBytes = nFactors * (INT + valueSize)
+      parser = new BinaryParser(
+        new DataView(
+          await file.read(factorsPosition + INT, factorBytes, { signal }),
+        ),
+      )
+      const chrScaleFactors = new Map<number, number>()
+      for (let i = 0; i < nFactors; i++) {
+        const chrIdx = parser.getInt()
+        chrScaleFactors.set(
+          chrIdx,
+          version < 9 ? parser.getDouble() : parser.getFloat(),
+        )
+      }
+      chunks.set(getExpectedKey(type, unit, binSize), {
+        vector: new NormalizationVector(
+          this.file,
+          valuesPosition,
+          nValues,
+          valueSize,
+        ),
+        nValues,
+        chrScaleFactors,
+      })
+      position = factorsPosition + INT + factorBytes
       onProgress?.(done + 1, nEntries)
     }
-    return position
+    return { chunks, end: position }
   }
 
   private parseNormVectorEntry(
@@ -1044,15 +1133,11 @@ export class HicFile {
     const filePosition = binaryParser.getLong() // 8
     const sizeInBytes =
       this.version < 9 ? binaryParser.getInt() : binaryParser.getLong() // 4:8
-    const key = `${type}_${chrIdx}_${unit}_${binSize}`
+    const key = getNormalizationVectorKey(type, chrIdx, unit, binSize)
 
     if (!index.types.includes(type)) {
       index.types.push(type)
     }
     index.entries[key] = { filePosition, size: sizeInBytes }
   }
-
-  getFileChrName(chrAlias: string) {
-    return this.chrAliasTable[chrAlias] ?? chrAlias
-  }
 }