@gmod/hic 1.0.0

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2019 hic-straw contributors (https://github.com/aidenlab/hic-straw)
+Copyright (c) 2026 Colin Diesh
+
+This package is a fork of hic-straw, whose MIT license notice is preserved
+above.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# @gmod/hic
+
+[![NPM version](https://img.shields.io/npm/v/@gmod/hic.svg?style=flat-square)](https://npmjs.org/package/@gmod/hic)
+![Build Status](https://img.shields.io/github/actions/workflow/status/GMOD/hic/publish.yml?branch=main)
+
+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) for what changed
+and why.
+
+## Install
+
+    $ npm install @gmod/hic
+
+## Usage
+
+```js
+import { HicFile } from '@gmod/hic'
+
+const hic = new HicFile({ path: 'path/to/file.hic' })
+
+const meta = await hic.getMetaData()
+// { version, genome, chromosomes: [{ index, name, size }], resolutions }
+
+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)
+
+// records is struct-of-arrays: three parallel typed arrays
+records.bin1 // Int32Array of bin indices along region1
+records.bin2 // Int32Array of bin indices along region2
+records.counts // Float32Array of contact counts
+```
+
+In the browser, or for a file over HTTP, pass a `filehandle` from
+[`generic-filehandle2`](https://www.npmjs.com/package/generic-filehandle2)
+instead of a `path`:
+
+```js
+import { RemoteFile } from 'generic-filehandle2'
+
+const hic = new HicFile({
+  filehandle: new RemoteFile('https://example.com/file.hic'),
+})
+```
+
+Anything that can read `length` bytes at `position` works too, which is the
+hook for a caller with its own IO layer or cache:
+
+```js
+const hic = new HicFile({
+  reader: { read: (position, length) => myCache.read(position, length) },
+})
+```
+
+See [docs/api.md](docs/api.md) for the full API reference.
+
+## Notes
+
+- 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 left of its y window is swapped before it is issued;
+  `transposed` says so, and `bin1` then runs along `region2`.
+- `appliedNormalization` is what was actually applied, which is not always what
+  was asked for — normalization vectors are stored per (type, chromosome, unit,
+  binsize), so a file can offer KR at 5 kb and nothing at 2.5 Mb.
+- `BP` is the only unit supported; the FRAG code paths were dropped.
+
+## Academic use
+
+This package was written with funding from the [NHGRI](http://genome.gov) as
+part of the [JBrowse](http://jbrowse.org) project. If you use it in an academic
+project that you publish, please cite the most recent JBrowse paper, which will
+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).

package/dist/binWindow.d.ts

@@ -0,0 +1,24 @@
+import type { HicRegion } from './types.ts';
+/**
+ * Half-open `[first, last+1)` range of bin indices **overlapping** a region.
+ *
+ * Upstream hic-straw compares bin indices against the raw fractional quotients
+ * `start/binsize` and `end/binsize`, which is exact only for the
+ * chromosome-aligned queries juicebox issues. A genome browser queries
+ * arbitrary viewport windows, where `start % binsize !== 0` essentially always
+ * holds, and the raw quotient then (a) drops the bin straddling the region's
+ * start — a missing column at the left edge of every block, jittering as the
+ * user pans — while keeping the one straddling the end, and (b) selects
+ * *nothing at all* for a region narrower than one bin, which is reachable by
+ * locking a coarse binsize while zoomed in.
+ *
+ * Flooring/ceiling also matches `getNormVectors`, which already builds its
+ * vector slice over `[floor(start/binsize), ceil(end/binsize))` — so
+ * `rec.bin1 - norm.offset1` indexes exactly the values that were fetched.
+ *
+ * Lives in its own module because both the record filter (`hicFile`) and the
+ * block-number selection (`matrixZoomData`) must agree on the window: widening
+ * only one of them still drops records, since a bin can sit in a block the
+ * other never asked for.
+ */
+export declare function binWindow(region: HicRegion, binsize: number): readonly [number, number];

package/dist/binWindow.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.binWindow = binWindow;
+/**
+ * Half-open `[first, last+1)` range of bin indices **overlapping** a region.
+ *
+ * Upstream hic-straw compares bin indices against the raw fractional quotients
+ * `start/binsize` and `end/binsize`, which is exact only for the
+ * chromosome-aligned queries juicebox issues. A genome browser queries
+ * arbitrary viewport windows, where `start % binsize !== 0` essentially always
+ * holds, and the raw quotient then (a) drops the bin straddling the region's
+ * start — a missing column at the left edge of every block, jittering as the
+ * user pans — while keeping the one straddling the end, and (b) selects
+ * *nothing at all* for a region narrower than one bin, which is reachable by
+ * locking a coarse binsize while zoomed in.
+ *
+ * Flooring/ceiling also matches `getNormVectors`, which already builds its
+ * vector slice over `[floor(start/binsize), ceil(end/binsize))` — so
+ * `rec.bin1 - norm.offset1` indexes exactly the values that were fetched.
+ *
+ * Lives in its own module because both the record filter (`hicFile`) and the
+ * block-number selection (`matrixZoomData`) must agree on the window: widening
+ * only one of them still drops records, since a bin can sit in a block the
+ * other never asked for.
+ */
+function binWindow(region, binsize) {
+    return [
+        Math.floor(region.start / binsize),
+        Math.ceil(region.end / binsize),
+    ];
+}
+//# sourceMappingURL=binWindow.js.map

package/dist/binWindow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binWindow.js","sourceRoot":"","sources":["../src/binWindow.ts"],"names":[],"mappings":";;AAwBA,8BAKC;AA3BD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAgB,SAAS,CAAC,MAAiB,EAAE,OAAe;IAC1D,OAAO;QACL,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,GAAG,OAAO,CAAC;QAClC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,GAAG,OAAO,CAAC;KACvB,CAAA;AACZ,CAAC"}

package/dist/binary.d.ts

@@ -0,0 +1,15 @@
+export default class BinaryParser {
+    position: number;
+    private view;
+    private length;
+    private littleEndian;
+    constructor(dataView: DataView, littleEndian?: boolean);
+    available(): number;
+    getByte(): number;
+    getShort(): number;
+    getInt(): number;
+    getLong(): number;
+    getString(): string;
+    getFloat(): number;
+    getDouble(): number;
+}

package/dist/binary.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+class BinaryParser {
+    position = 0;
+    view;
+    length;
+    littleEndian;
+    constructor(dataView, littleEndian = true) {
+        this.view = dataView;
+        this.length = dataView.byteLength;
+        this.littleEndian = littleEndian;
+    }
+    available() {
+        return this.length - this.position;
+    }
+    getByte() {
+        const ret = this.view.getUint8(this.position);
+        this.position += 1;
+        return ret;
+    }
+    getShort() {
+        const ret = this.view.getInt16(this.position, this.littleEndian);
+        this.position += 2;
+        return ret;
+    }
+    getInt() {
+        const ret = this.view.getInt32(this.position, this.littleEndian);
+        this.position += 4;
+        return ret;
+    }
+    // No native 64-bit read that lands in a `number`, so compose two 32-bit words
+    // (deliberately not getBigUint64 — every caller is a file offset or a count
+    // that stays well inside Number.MAX_SAFE_INTEGER, and a BigInt would have to
+    // be converted back at each use site). hic-straw accumulated byte-by-byte
+    // through a throwaway 8-element array, which is a per-entry allocation in the
+    // block-index parse loop.
+    getLong() {
+        const p = this.position;
+        const le = this.littleEndian;
+        const first = this.view.getUint32(p, le);
+        const second = this.view.getUint32(p + 4, le);
+        this.position += 8;
+        // little-endian puts the low word first, big-endian the high word
+        return le ? second * 0x1_0000_0000 + first : first * 0x1_0000_0000 + second;
+    }
+    getString() {
+        let s = '';
+        let c = this.view.getUint8(this.position++);
+        while (c !== 0) {
+            s += String.fromCharCode(c);
+            c = this.view.getUint8(this.position++);
+        }
+        return s;
+    }
+    getFloat() {
+        const ret = this.view.getFloat32(this.position, this.littleEndian);
+        this.position += 4;
+        return ret;
+    }
+    getDouble() {
+        const ret = this.view.getFloat64(this.position, this.littleEndian);
+        this.position += 8;
+        return ret;
+    }
+}
+exports.default = BinaryParser;
+//# sourceMappingURL=binary.js.map

package/dist/binary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary.js","sourceRoot":"","sources":["../src/binary.ts"],"names":[],"mappings":";;AAAA,MAAqB,YAAY;IAC/B,QAAQ,GAAG,CAAC,CAAA;IACJ,IAAI,CAAU;IACd,MAAM,CAAQ;IACd,YAAY,CAAS;IAE7B,YAAY,QAAkB,EAAE,YAAY,GAAG,IAAI;QACjD,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAA;QACpB,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAA;QACjC,IAAI,CAAC,YAAY,GAAG,YAAY,CAAA;IAClC,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAA;IACpC,CAAC;IAED,OAAO;QACL,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QAC7C,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAA;QAClB,OAAO,GAAG,CAAA;IACZ,CAAC;IAED,QAAQ;QACN,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,YAAY,CAAC,CAAA;QAChE,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAA;QAClB,OAAO,GAAG,CAAA;IACZ,CAAC;IAED,MAAM;QACJ,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,YAAY,CAAC,CAAA;QAChE,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAA;QAClB,OAAO,GAAG,CAAA;IACZ,CAAC;IAED,8EAA8E;IAC9E,4EAA4E;IAC5E,6EAA6E;IAC7E,0EAA0E;IAC1E,8EAA8E;IAC9E,0BAA0B;IAC1B,OAAO;QACL,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAA;QACvB,MAAM,EAAE,GAAG,IAAI,CAAC,YAAY,CAAA;QAC5B,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;QACxC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAA;QAC7C,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAA;QAClB,kEAAkE;QAClE,OAAO,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,aAAa,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,aAAa,GAAG,MAAM,CAAA;IAC7E,CAAC;IAED,SAAS;QACP,IAAI,CAAC,GAAG,EAAE,CAAA;QACV,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAA;QAC3C,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACf,CAAC,IAAI,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAA;YAC3B,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAA;QACzC,CAAC;QACD,OAAO,CAAC,CAAA;IACV,CAAC;IAED,QAAQ;QACN,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,YAAY,CAAC,CAAA;QAClE,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAA;QAClB,OAAO,GAAG,CAAA;IACZ,CAAC;IAED,SAAS;QACP,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,YAAY,CAAC,CAAA;QAClE,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAA;QAClB,OAAO,GAAG,CAAA;IACZ,CAAC;CACF;AAvED,+BAuEC"}

package/dist/bufferedFile.d.ts

@@ -0,0 +1,13 @@
+import type { Reader } from './types.ts';
+export default class BufferedFile {
+    private file;
+    private size;
+    private bufferStart;
+    private bufferLength;
+    private buffer;
+    constructor(args: {
+        file: Reader;
+        size?: number;
+    });
+    read(position: number, length: number): Promise<ArrayBuffer>;
+}

package/dist/bufferedFile.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+function concatBuffers(buffer1, buffer2) {
+    const tmp = new Uint8Array(buffer1.byteLength + buffer2.byteLength);
+    tmp.set(new Uint8Array(buffer1), 0);
+    tmp.set(new Uint8Array(buffer2), buffer1.byteLength);
+    return tmp.buffer;
+}
+class BufferedFile {
+    file;
+    size;
+    bufferStart = 0;
+    bufferLength = 0;
+    buffer;
+    constructor(args) {
+        this.file = args.file;
+        this.size = args.size ?? 64000;
+    }
+    async read(position, length) {
+        const start = position;
+        const end = position + length;
+        const bufferStart = this.bufferStart;
+        const bufferEnd = this.bufferStart + this.bufferLength;
+        const buf = this.buffer;
+        let result;
+        if (length > this.size) {
+            // Request larger than max buffer size, pass through to underlying file
+            this.buffer = undefined;
+            this.bufferStart = 0;
+            this.bufferLength = 0;
+            result = await this.file.read(position, length);
+        }
+        else if (buf && start >= bufferStart && end <= bufferEnd) {
+            // Request within buffer bounds
+            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);
+            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
+            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);
+                this.buffer = next;
+                this.bufferStart = bufferEnd;
+                this.bufferLength = next.byteLength;
+                result = concatBuffers(a1, next.slice(0, l2));
+            }
+            else {
+                result = a1;
+            }
+        }
+        else {
+            // No overlap with buffer
+            const next = await this.file.read(position, this.size);
+            this.buffer = next;
+            this.bufferStart = position;
+            this.bufferLength = next.byteLength;
+            result = next.slice(0, length);
+        }
+        return result;
+    }
+}
+exports.default = BufferedFile;
+//# sourceMappingURL=bufferedFile.js.map

package/dist/bufferedFile.js.map

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

package/dist/contactRecords.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A run of contact records, held struct-of-arrays.
+ *
+ * hic-straw models a contact as an object, and the whole read path inherits
+ * that shape: a block holds `ContactRecord[]` and the window filter rebuilds
+ * the array. A renderer then has to unpack that into typed arrays anyway, so a
+ * contact was allocated several times over on its way to a vertex buffer — and
+ * a matrix is routinely millions of contacts.
+ *
+ * The per-contact allocation is the obvious cost, but the block cache is the
+ * expensive one: cached blocks are long-lived, so as objects they left millions
+ * of live pointers for every GC to trace for the rest of the session. Twelve
+ * bytes a contact here against ~50 for an object, and nothing for the collector
+ * to walk.
+ *
+ * The three arrays are always exactly the same length — `bin1.length` is the
+ * record count. Counts are float32 because that is what the file stores
+ * (`getFloat`/`getShort`) and what a GPU renderer takes, so carrying them as
+ * doubles only ever widened a value on its way back down to float32.
+ */
+export interface ContactRecords {
+    bin1: Int32Array;
+    bin2: Int32Array;
+    counts: Float32Array;
+}

package/dist/contactRecords.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=contactRecords.js.map

package/dist/contactRecords.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contactRecords.js","sourceRoot":"","sources":["../src/contactRecords.ts"],"names":[],"mappings":""}

package/dist/hicFile.d.ts

@@ -0,0 +1,94 @@
+import BinaryParser from './binary.ts';
+import Matrix from './matrix.ts';
+import NormalizationVector from './normalizationVector.ts';
+import type { ContactRecords } from './contactRecords.ts';
+import type MatrixZoomData from './matrixZoomData.ts';
+import type { BlockIndexEntry, HicMetadata, HicRegion, Reader } from './types.ts';
+import type { GenericFilehandle } from 'generic-filehandle2';
+/**
+ * Prefix of the error thrown when a region pair has no matrix at the requested
+ * binsize. A caller fetching many region pairs at once will want to drop that
+ * pair rather than fail the whole fetch, and it can only tell this apart from a
+ * real failure by the message — so it is exported instead of hand-copied.
+ */
+export declare const NO_DATA_FOR_RESOLUTION = "No data available for resolution";
+export interface HicConfig {
+    /** a `generic-filehandle2` handle, e.g. `RemoteFile` for a URL */
+    filehandle?: GenericFilehandle;
+    /** a local path, node only */
+    path?: string;
+    /** any object that can read `length` bytes at `position` */
+    reader?: Reader;
+    /**
+     * `"position,size"` of the normalization vector index, if it is known. Skips
+     * the walk through the expected-value vectors that locating it otherwise
+     * costs on a pre-v9 file.
+     */
+    nvi?: string;
+}
+interface Block {
+    blockNumber: number;
+    records: ContactRecords;
+}
+export declare class HicFile {
+    private config;
+    private file;
+    private normVectorCache;
+    private normalizationTypes;
+    private matrixCache;
+    private blockCache;
+    private normVectorIndexPosition;
+    private normVectorIndexSize;
+    private initPromise;
+    private normVectorIndexP;
+    private version;
+    private genomeId;
+    private footerPosition;
+    normExpectedValueVectorsPosition: number | undefined;
+    private normVectorIndex;
+    private chromosomes;
+    private chromosomeIndexMap;
+    private chrAliasTable;
+    private bpResolutions;
+    private masterIndex;
+    private meta;
+    constructor(config: HicConfig);
+    init(): Promise<void>;
+    getMetaData(): Promise<HicMetadata>;
+    readHeaderAndFooter(): Promise<void>;
+    readFooter(): Promise<void>;
+    getMatrix(chrIdx1: number, chrIdx2: number): Promise<Matrix | undefined>;
+    readMatrix(chrIdx1: number, chrIdx2: number): Promise<Matrix | undefined>;
+    getContactRecords(normalization: string, region1: HicRegion, region2: HicRegion, units: string, binsize: number): Promise<{
+        records: ContactRecords;
+        appliedNormalization: string;
+        transposed: boolean;
+    }>;
+    private getNormVectors;
+    getBlocks(region1: HicRegion, region2: HicRegion, binSize: number): Promise<(Block | undefined)[]>;
+    readBlock(blockNumber: number, zd: MatrixZoomData): Promise<Block | undefined>;
+    /**
+     * Decode one block's records straight into typed arrays.
+     *
+     * Every encoding here knows its length up front, so each array is allocated
+     * once and filled by a write cursor. Where a filter can drop records (the
+     * dense encoding's empty cells) the arrays are sized to the upper bound and
+     * copied down to the true length at the end — blocks are cached for the life
+     * 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): Promise<NormalizationVector | undefined>;
+    private readNormalizationVector;
+    getNormVectorIndex(): Promise<Record<string, BlockIndexEntry> | undefined>;
+    private loadNormVectorIndex;
+    getNormalizationOptions(): Promise<string[]>;
+    readNormVectorIndex(range: {
+        start: number;
+        size: number;
+    }): Promise<Record<string, BlockIndexEntry>>;
+    readNormExpectedValuesAndNormVectorIndex(): Promise<void>;
+    skipExpectedValues(start: number): Promise<number>;
+    parseNormVectorEntry(binaryParser: BinaryParser): void;
+    getFileChrName(chrAlias: string): string;
+}
+export {};