@gmod/hic 1.0.0

package/esm/binary.js.map

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

package/esm/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/esm/bufferedFile.js

@@ -0,0 +1,75 @@
+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;
+}
+export default 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;
+    }
+}
+//# sourceMappingURL=bufferedFile.js.map

package/esm/bufferedFile.js.map

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

package/esm/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/esm/contactRecords.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contactRecords.js.map

package/esm/contactRecords.js.map

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

package/esm/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 {};