@gmod/hic 1.3.1 → 2.0.0

package/README.md

@@ -5,11 +5,9 @@
 
 Read `.hic` contact matrix files, in Node.js or the browser.
 
-A fork of [hic-straw](https://github.com/aidenlab/hic-straw), rewritten in
-TypeScript and retuned for a genome browser's access pattern — many region
-pairs per fetch, arbitrary viewport windows, and contacts handed to a GPU
-renderer. See [docs/optimizations.md](docs/optimizations.md) and
-[docs/correctness.md](docs/correctness.md) for what changed and why.
+`@gmod/hic` is a fork of [hic-straw](https://github.com/aidenlab/hic-straw),
+rewritten in TypeScript for a genome browser that fetches many region pairs at
+once over arbitrary viewport windows.
 
 ## Install
 
@@ -29,7 +27,7 @@ await hic.getNormalizationOptions() // ['NONE', 'VC', 'VC_SQRT', 'KR', 'SCALE']
 
 const region = { chr: '1', start: 0, end: 20_000_000 }
 const { records, appliedNormalization, transposed } =
-  await hic.getContactRecords('KR', region, region, 'BP', 2_500_000)
+  await hic.getContactRecords('KR', region, region, 2_500_000)
 
 // records is struct-of-arrays: three parallel typed arrays
 records.bin1 // Int32Array of bin indices along region1
@@ -37,14 +35,12 @@ records.bin2 // Int32Array of bin indices along region2
 records.counts // Float32Array of contact counts
 ```
 
-`getNormalizationOptions()` and `getContactRecords()` both take an optional
-trailing `{ onProgress }`, called `(current, total)` as the work lands, so a
-loading indicator can show a bar rather than a spinner. The unit is the block for a
-contact fetch and the expected-value chunk for the normalization-index walk —
-the slow part of opening a pre-v9 file. See [docs/api.md](docs/api.md#progress).
+`getNormalizationOptions()` and `getContactRecords()` take an optional trailing
+`{ onProgress }`, called as `(current, total)`; see
+[docs/api.md](docs/api.md#progress).
 
 ```js
-await hic.getContactRecords('KR', region, region, 'BP', 2_500_000, {
+await hic.getContactRecords('KR', region, region, 2_500_000, {
   onProgress: (current, total) => showBar(current / total),
 })
 ```
@@ -64,16 +60,11 @@ const hic = new HicFile({
 })
 ```
 
-**Over HTTP, put a byte-range cache underneath. It is worth more than every
-other optimization in this package combined.** A contact-matrix query reads many
-small blocks scattered through the file — a whole-genome view of the test file
-issues over a thousand of them — and a browser runs about six requests per
-origin at a time, so the request count sets the wall clock.
+**Over HTTP, put a byte-range cache underneath.** A query reads many small
+scattered blocks, so the request count sets the load time.
 [`@gmod/range-cache-filehandle`](https://github.com/GMOD/range-cache-filehandle)
-is a drop-in for `RemoteFile` that serves those reads out of 256 KiB chunks, so
-neighboring blocks share a request. Measured in headless Chrome against a real
-69 GB ENCODE file, whole chr1 at 5 kb: **24.0 s and 225 requests becomes 1.8 s
-and 45**, for byte-identical output.
+cut a whole-chr1 fetch from a 69 GB ENCODE file from 24.0 s to 1.8 s
+([docs/optimizations.md](docs/optimizations.md#round-trips-not-cpu-dominate-a-remote-fetch)).
 
 ```js
 import { RemoteFileWithRangeCache } from '@gmod/range-cache-filehandle'
@@ -83,8 +74,8 @@ const hic = new HicFile({
 })
 ```
 
-Anything that can read `length` bytes at `position` works too, which is the
-hook for a caller with its own IO layer or cache:
+A caller with its own IO layer or cache can supply anything that reads `length`
+bytes at `position`:
 
 ```js
 const hic = new HicFile({
@@ -99,13 +90,14 @@ See [docs/api.md](docs/api.md) for the full API reference.
 - Bin indices are **absolute for their chromosome**, not relative to the
   requested region.
 - A `.hic` stores only the `bin1 <= bin2` half of the matrix, so a query whose x
-  window sits right of its y window gets swapped before it goes out;
-  `transposed` marks that swap, and `bin1` then runs along `region2`.
-- `appliedNormalization` names the normalization the file actually applied,
-  which is not always the one you asked for — a `.hic` carries normalization
-  vectors per (type, chromosome, unit, binsize), so it can offer KR at 5 kb and
-  nothing at 2.5 Mb.
-- `BP` is the only unit this fork supports; it drops the FRAG code paths.
+  window sits right of its y window gets swapped. `transposed` marks the swap,
+  and `bin1` then runs along `region2`.
+- `appliedNormalization` names the normalization the reader applied, which may
+  differ from the one you asked for. The file stores vectors per (type,
+  chromosome, unit, binsize), so it can offer KR at 5 kb and nothing at 2.5 Mb.
+- Bins are base pairs only; this fork drops the FRAG (restriction-fragment)
+  code paths.
+- Chromosome names match the file's own exactly, with no `chr` aliasing.
 - Each `HicFile` caches up to 128 MB of decompressed contacts. Pass
   `blockCacheMaxBytes` to change that ceiling.
 - Record order is unspecified — the result concatenates whole blocks, cached
@@ -132,10 +124,6 @@ be linked from [jbrowse.org](http://jbrowse.org).
 If you use `.hic` files, please also cite the Juicer/Juicebox papers from the
 [Aiden Lab](https://github.com/aidenlab), whose hic-straw this is derived from.
 
-## Contributing
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development and release workflow.
-
 ## License
 
-MIT, as is upstream hic-straw. See [LICENSE](LICENSE).
+MIT, as is upstream hic-straw; see [LICENSE](LICENSE).

package/dist/bufferedFile.js

@@ -35,33 +35,16 @@ class BufferedFile {
             const sliceStart = start - bufferStart;
             result = buf.slice(sliceStart, sliceStart + length);
         }
-        else if (buf && start < bufferStart && end > bufferStart) {
-            // Overlap left (unexpected in straw); we don't adjust the buffer
-            const l1 = bufferStart - start;
-            const a1 = await this.file.read(position, l1, opts);
-            const l2 = length - l1;
-            if (l2 > 0) {
-                result = concatBuffers(a1, buf.slice(0, l2));
-            }
-            else {
-                result = a1;
-            }
-        }
-        else if (buf && start < bufferEnd && end > bufferEnd) {
-            // Overlap right
+        else if (buf && start >= bufferStart && start < bufferEnd) {
+            // Overlap right. The expected-values walk only moves forward, so a
+            // request starting before the buffer takes the fresh read below.
             const l1 = bufferEnd - start;
             const a1 = buf.slice(this.bufferLength - l1, this.bufferLength);
-            const l2 = length - l1;
-            if (l2 > 0) {
-                const next = await this.file.read(bufferEnd, this.size, opts);
-                this.buffer = next;
-                this.bufferStart = bufferEnd;
-                this.bufferLength = next.byteLength;
-                result = concatBuffers(a1, next.slice(0, l2));
-            }
-            else {
-                result = a1;
-            }
+            const next = await this.file.read(bufferEnd, this.size, opts);
+            this.buffer = next;
+            this.bufferStart = bufferEnd;
+            this.bufferLength = next.byteLength;
+            result = concatBuffers(a1, next.slice(0, length - l1));
         }
         else {
             // No overlap with buffer

package/dist/bufferedFile.js.map

@@ -1 +1 @@
-{"version":3,"file":"bufferedFile.js","sourceRoot":"","sources":["../src/bufferedFile.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bufferedFile.js","sourceRoot":"","sources":["../src/bufferedFile.ts"],"names":[],"mappings":"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"}

package/dist/hicFile.d.ts

@@ -27,8 +27,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;
 }
@@ -37,7 +36,7 @@ interface Block {
     records: ContactRecords;
 }
 export declare class HicFile {
-    private config;
+    private nvi;
     private file;
     private headerCache;
     private normVectorIndexCache;
@@ -52,7 +51,6 @@ export declare class HicFile {
     normExpectedValueVectorsPosition: number | undefined;
     private chromosomes;
     private chromosomeIndexMap;
-    private chrAliasTable;
     private bpResolutions;
     private masterIndex;
     private meta;
@@ -63,7 +61,7 @@ export declare class HicFile {
     private readFooter;
     getMatrix(chrIdx1: number, chrIdx2: number, opts?: BaseOpts): Promise<Matrix | undefined>;
     private readMatrix;
-    getContactRecords(normalization: string, region1: HicRegion, region2: HicRegion, units: string, binsize: number, opts?: ProgressOpts): Promise<{
+    getContactRecords(normalization: string, region1: HicRegion, region2: HicRegion, binsize: number, opts?: ProgressOpts): Promise<{
         records: ContactRecords;
         appliedNormalization: string;
         transposed: boolean;
@@ -81,7 +79,7 @@ export declare class HicFile {
      * of the session, so it is worth one memcpy not to pin an oversized buffer.
      */
     private parseBlockRecords;
-    getNormalizationVector(type: string, chr: string, unit: string, binSize: number, opts?: BaseOpts): Promise<NormalizationVector | undefined>;
+    getNormalizationVector(type: string, chr: string, binSize: number, opts?: BaseOpts): Promise<NormalizationVector | undefined>;
     private readNormalizationVector;
     getNormVectorIndex(opts?: ProgressOpts): Promise<Record<string, BlockIndexEntry> | undefined>;
     private getParsedNormVectorIndex;
@@ -91,6 +89,5 @@ export declare class HicFile {
     private readNormExpectedValuesAndNormVectorIndex;
     private skipExpectedValues;
     private parseNormVectorEntry;
-    getFileChrName(chrAlias: string): string;
 }
 export {};

package/dist/hicFile.js

@@ -10,7 +10,6 @@ const generic_filehandle2_1 = require("generic-filehandle2");
 const binWindow_ts_1 = require("./binWindow.js");
 const binary_ts_1 = __importDefault(require("./binary.js"));
 const bufferedFile_ts_1 = __importDefault(require("./bufferedFile.js"));
-const lru_ts_1 = __importDefault(require("./lru.js"));
 const matrix_ts_1 = __importDefault(require("./matrix.js"));
 const normalizationVector_ts_1 = __importDefault(require("./normalizationVector.js"));
 const reader_ts_1 = require("./reader.js");
@@ -65,15 +64,13 @@ function truncateRecords(records, n) {
 // 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
@@ -95,6 +92,9 @@ const NORM_VECTOR_CACHE_SIZE = 64;
 // hic-straw's extra `resolution` field only made the cache single-resolution
 // (every zoom step threw the previous level away).
 function blockCacheWeight(block) {
+    if (!block) {
+        return 0;
+    }
     const { bin1, bin2, counts } = block.records;
     return bin1.byteLength + bin2.byteLength + counts.byteLength;
 }
@@ -102,7 +102,7 @@ function getNormalizationVectorKey(type, chrIdx, unit, resolution) {
     return `${type}_${chrIdx}_${unit}_${resolution}`;
 }
 class HicFile {
-    config;
+    nvi;
     file;
     // These caches share the in-flight read, not just its result. A
     // multi-region fetch runs its region pairs concurrently and they share
@@ -129,17 +129,16 @@ class HicFile {
     // make that second shape.
     normExpectedValueVectorsPosition;
     chromosomes = [];
-    chromosomeIndexMap = {};
-    chrAliasTable = {};
+    chromosomeIndexMap = new Map();
     bpResolutions = [];
     masterIndex = {};
     meta;
     constructor(config) {
-        const { filehandle, path, reader, blockCacheMaxBytes } = config;
-        this.config = config;
-        this.blockCache = new lru_ts_1.default(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 shared_read_cache_1.SharedReadCache({
+            maxSize: blockCacheMaxBytes ?? BLOCK_CACHE_MAX_BYTES,
+            sizeOf: blockCacheWeight,
         });
         if (reader) {
             this.file = reader;
@@ -194,7 +193,7 @@ class HicFile {
             binaryParser.getString(); // attribute value
         }
         const chromosomes = [];
-        const chromosomeIndexMap = {};
+        const chromosomeIndexMap = new Map();
         let nChrs = binaryParser.getInt();
         let i = 0;
         while (nChrs-- > 0) {
@@ -204,7 +203,7 @@ class HicFile {
                 size: version < 9 ? binaryParser.getInt() : binaryParser.getLong(),
             };
             chromosomes.push(chr);
-            chromosomeIndexMap[chr.name] = chr.index;
+            chromosomeIndexMap.set(chr.name, chr.index);
             i++;
         }
         const bpResolutions = [];
@@ -212,18 +211,6 @@ class HicFile {
         while (nBpResolutions-- > 0) {
             bpResolutions.push(binaryParser.getInt());
         }
-        const chrAliasTable = {};
-        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;
-            }
-        }
         (0, shared_read_cache_1.throwIfAborted)(signal);
         this.version = version;
         this.footerPosition = footerPosition;
@@ -235,7 +222,6 @@ class HicFile {
         this.chromosomes = chromosomes;
         this.chromosomeIndexMap = chromosomeIndexMap;
         this.bpResolutions = bpResolutions;
-        this.chrAliasTable = chrAliasTable;
         this.meta = {
             version,
             genome: genomeId,
@@ -279,10 +265,10 @@ class HicFile {
         }
         return matrix;
     }
-    async getContactRecords(normalization, region1, region2, units, binsize, opts) {
+    async getContactRecords(normalization, region1, region2, binsize, opts) {
         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
         // matrix that does not exist. The same-chromosome test compares **starts**,
@@ -318,7 +304,7 @@ 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.
@@ -393,45 +379,41 @@ 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',
             transposed: transpose,
         };
     }
-    async getNormVectors(normalization, r1, r2, units, binsize, opts) {
+    async getNormVectors(normalization, r1, r2, binsize, opts) {
+        if (!normalization || normalization === 'NONE') {
+            return undefined;
+        }
         const signalOpts = { signal: opts?.signal };
-        let result;
-        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] = (0, binWindow_ts_1.binWindow)(r1, binsize);
+        const [offset2, end2] = (0, binWindow_ts_1.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(region1, region2, binSize, opts) {
         const blockKey = (blockNumber, zd) => `${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 = [];
         if (idx1 === undefined) {
             console.warn(`No chromosome named: ${region1.chr}`);
@@ -452,43 +434,37 @@ class HicFile {
                     throw new Error(`${exports.NO_DATA_FOR_RESOLUTION}: ${binSize} for map ${region1.chr}-${region2.chr}`);
                 }
                 const blockNumbers = zd.getBlockNumbers(region1, region2, this.version);
-                const blockNumbersToQuery = [];
-                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;
@@ -595,13 +571,13 @@ class HicFile {
         }
         throw new Error(`Unknown block type: ${type}`);
     }
-    async getNormalizationVector(type, chr, unit, binSize, opts) {
+    async getNormalizationVector(type, chr, binSize, opts) {
         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
         // result-only cache each of those pairs missed while the first was still in
@@ -658,8 +634,8 @@ class HicFile {
                 size: this.normVectorIndexSize,
             }, 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]),
                 size: parseInt(nviArray[1]),
@@ -703,38 +679,27 @@ class HicFile {
         let index;
         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 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 binary_ts_1.default(new DataView(data));
-                const nEntries = binaryParser.getInt();
-                const sizeEstimate = nEntries * 30;
-                data = await this.file.read(nviStart + byteCount, sizeEstimate, {
-                    signal,
-                });
+                const nEntries = new binary_ts_1.default(new DataView(data)).getInt();
                 const found = { entries: {}, types: ['NONE'] };
-                const processEntries = async (remaining, buf) => {
-                    const parser = new binary_ts_1.default(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 binary_ts_1.default(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 binary_ts_1.default(new DataView(buf));
                     }
-                    byteCount += parser.position;
-                };
-                await processEntries(nEntries, data);
+                    this.parseNormVectorEntry(parser, found);
+                }
                 (0, shared_read_cache_1.throwIfAborted)(signal);
-                this.config.nvi = `${nviStart},${byteCount}`;
                 index = found;
             }
         }
@@ -806,15 +771,12 @@ class HicFile {
         const binSize = binaryParser.getInt(); // 4
         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) {
-        return this.chrAliasTable[chrAlias] ?? chrAlias;
-    }
 }
 exports.HicFile = HicFile;
 //# sourceMappingURL=hicFile.js.map