@gmod/hic 1.3.1 → 1.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +29 -26
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -6,10 +6,10 @@
6
6
  Read `.hic` contact matrix files, in Node.js or the browser.
7
7
 
8
8
  A fork of [hic-straw](https://github.com/aidenlab/hic-straw), rewritten in
9
- TypeScript and retuned for a genome browser's access pattern — many region
10
- pairs per fetch, arbitrary viewport windows, and contacts handed to a GPU
11
- renderer. See [docs/optimizations.md](docs/optimizations.md) and
12
- [docs/correctness.md](docs/correctness.md) for what changed and why.
9
+ TypeScript for a genome browser: many region pairs per fetch, arbitrary
10
+ viewport windows, and contacts handed to a GPU renderer. See
11
+ [docs/optimizations.md](docs/optimizations.md) and
12
+ [docs/correctness.md](docs/correctness.md) for what changed.
13
13
 
14
14
  ## Install
15
15
 
@@ -37,11 +37,14 @@ records.bin2 // Int32Array of bin indices along region2
37
37
  records.counts // Float32Array of contact counts
38
38
  ```
39
39
 
40
- `getNormalizationOptions()` and `getContactRecords()` both take an optional
41
- trailing `{ onProgress }`, called `(current, total)` as the work lands, so a
42
- loading indicator can show a bar rather than a spinner. The unit is the block for a
43
- contact fetch and the expected-value chunk for the normalization-index walk —
44
- the slow part of opening a pre-v9 file. See [docs/api.md](docs/api.md#progress).
40
+ `getNormalizationOptions()` and `getContactRecords()` take an optional trailing
41
+ `{ onProgress }`, called as `(current, total)`:
42
+
43
+ - The unit is the block for a contact fetch.
44
+ - The unit is the expected-value chunk for the normalization-index walk, the
45
+ slow part of opening a pre-v9 file.
46
+
47
+ See [docs/api.md](docs/api.md#progress).
45
48
 
46
49
  ```js
47
50
  await hic.getContactRecords('KR', region, region, 'BP', 2_500_000, {
@@ -65,15 +68,16 @@ const hic = new HicFile({
65
68
  ```
66
69
 
67
70
  **Over HTTP, put a byte-range cache underneath. It is worth more than every
68
- other optimization in this package combined.** A contact-matrix query reads many
69
- small blocks scattered through the file — a whole-genome view of the test file
70
- issues over a thousand of them — and a browser runs about six requests per
71
- origin at a time, so the request count sets the wall clock.
72
- [`@gmod/range-cache-filehandle`](https://github.com/GMOD/range-cache-filehandle)
73
- is a drop-in for `RemoteFile` that serves those reads out of 256 KiB chunks, so
74
- neighboring blocks share a request. Measured in headless Chrome against a real
75
- 69 GB ENCODE file, whole chr1 at 5 kb: **24.0 s and 225 requests becomes 1.8 s
76
- and 45**, for byte-identical output.
71
+ other optimization in this package combined.**
72
+
73
+ - A contact-matrix query reads many small blocks scattered through the file, and
74
+ a browser runs about six requests per origin at a time, so the number of
75
+ requests sets the load time.
76
+ - [`@gmod/range-cache-filehandle`](https://github.com/GMOD/range-cache-filehandle)
77
+ is a drop-in for `RemoteFile` that reads 256 KiB chunks, so neighboring blocks
78
+ share a request.
79
+ - Whole chr1 at 5 kb of a real 69 GB ENCODE file, in headless Chrome: **24.0 s
80
+ and 225 requests becomes 1.8 s and 45**, with byte-identical output.
77
81
 
78
82
  ```js
79
83
  import { RemoteFileWithRangeCache } from '@gmod/range-cache-filehandle'
@@ -83,8 +87,8 @@ const hic = new HicFile({
83
87
  })
84
88
  ```
85
89
 
86
- Anything that can read `length` bytes at `position` works too, which is the
87
- hook for a caller with its own IO layer or cache:
90
+ A caller with its own IO layer or cache can supply anything that reads `length`
91
+ bytes at `position`:
88
92
 
89
93
  ```js
90
94
  const hic = new HicFile({
@@ -99,12 +103,11 @@ See [docs/api.md](docs/api.md) for the full API reference.
99
103
  - Bin indices are **absolute for their chromosome**, not relative to the
100
104
  requested region.
101
105
  - A `.hic` stores only the `bin1 <= bin2` half of the matrix, so a query whose x
102
- window sits right of its y window gets swapped before it goes out;
103
- `transposed` marks that swap, and `bin1` then runs along `region2`.
104
- - `appliedNormalization` names the normalization the file actually applied,
105
- which is not always the one you asked for — a `.hic` carries normalization
106
- vectors per (type, chromosome, unit, binsize), so it can offer KR at 5 kb and
107
- nothing at 2.5 Mb.
106
+ window sits right of its y window gets swapped. `transposed` marks the swap,
107
+ and `bin1` then runs along `region2`.
108
+ - `appliedNormalization` names the normalization the file applied, which may
109
+ differ from the one you asked for. The file stores vectors per (type,
110
+ chromosome, unit, binsize), so it can offer KR at 5 kb and nothing at 2.5 Mb.
108
111
  - `BP` is the only unit this fork supports; it drops the FRAG code paths.
109
112
  - Each `HicFile` caches up to 128 MB of decompressed contacts. Pass
110
113
  `blockCacheMaxBytes` to change that ceiling.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gmod/hic",
3
- "version": "1.3.1",
3
+ "version": "1.3.2",
4
4
  "packageManager": "pnpm@11.15.1",
5
5
  "description": "Read .hic contact matrix files in node or the browser",
6
6
  "license": "MIT",