@gmod/hic

中文文档
2.4.0发布于 2026/10/31MITTypeScriptESM + CJS构建来源已验证近 30 天下载 1.2万

Read .hic contact matrix files in node or the browser

原始使用文档
文档目录6 节
  1. Install
  2. Usage
  3. Notes
  4. Docs
  5. Academic use
  6. License

@gmod/hic

NPM version Build Status

Read .hic contact matrix files, in Node.js or the browser.

@gmod/hic is a fork of hic-straw, rewritten in TypeScript for a genome browser that fetches many region pairs at once over arbitrary viewport windows.

Install

$ npm install @gmod/hic

Usage

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, 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

getNormalizationOptions() and getContactRecords() take an optional trailing { onProgress }, called as (current, total); see docs/api.md.

await hic.getContactRecords('KR', region, region, 2_500_000, {
  onProgress: (current, total) => showBar(current / total),
})

Every async method also takes an AbortSignal the same way, { signal }, and forwards it to each read; see docs/api.md.

In the browser, or for a file over HTTP, pass a filehandle from generic-filehandle2 instead of a path:

import { RemoteFile } from 'generic-filehandle2'

const hic = new HicFile({
  filehandle: new RemoteFile('https://example.com/file.hic'),
})

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 cut a whole-chr1 fetch from a 69 GB ENCODE file from 24.0 s to 1.8 s (docs/optimizations.md).

import { RemoteFileWithRangeCache } from '@gmod/range-cache-filehandle'

const hic = new HicFile({
  filehandle: new RemoteFileWithRangeCache('https://example.com/file.hic'),
})

A caller with its own IO layer or cache can supply anything that reads length bytes at position:

const hic = new HicFile({
  reader: { read: (position, length) => myCache.read(position, length) },
})

See 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 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, and drops a block nothing has read for three minutes. Pass blockCacheMaxBytes to change that ceiling, or a shared blockCacheBudget to bound several files together.
  • Record order is unspecified — the result concatenates whole blocks, cached ones first.

Docs

Academic use

This package was written with funding from the NHGRI as part of the JBrowse 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.

If you use .hic files, please also cite the Juicer/Juicebox papers from the Aiden Lab, whose hic-straw this is derived from.

License

MIT, as is upstream hic-straw; see LICENSE.

版本与发布记录

@gmod/hic 共发布 12 个版本,首次发布于 2026/08/16;过去 12 个月发布了 12 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
2.4.0latest2026/10/3116 天前
2.3.02026/10/3116 天前
2.2.02026/10/2324 天前
2.1.02026/10/2325 天前
2.0.02026/10/151 个月前
1.3.22026/10/121 个月前

关于 @gmod/hic 的常见问题

@gmod/hic 是什么?

Read .hic contact matrix files in node or the browser

如何安装 @gmod/hic?

在项目目录运行 npm install @gmod/hic,或使用 pnpm add / yarn add / bun add。

@gmod/hic 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gmod/hic 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@gmod/hic 可以商用吗?

@gmod/hic 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gmod/hic 的下载量有多少?

根据 npm 官方下载统计,@gmod/hic 在 2026/10/17 – 2026/11/15 这 30 天内被下载 11,679 次,日均约 389 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gmod/hic 还在维护吗?

最新版本 2.4.0 发布于 2026/10/31(16 天前);至今共发布 12 个版本,其中过去 12 个月发布了 12 个;首次发布于 2026/08/16。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。