# @gmod/hic 中文文档

规范地址：https://npmcn.com/package/%40gmod/hic/

版本：2\.4\.0
npm 元数据更新时间：2026-10-31T00:40:38.444Z
中文译文更新时间：2026-11-16T17:11:51.737Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gmod/hic
原文对照：https://npmcn.com/package/%40gmod/hic/?lang=original
项目主页：https://github.com/GMOD/hic#readme
源码仓库：https://github.com/GMOD/hic

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：320 kB，81 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-08-15T22:03:15.076Z
- 最新版本发布：2026-10-31T00:40:38.133Z
- 近 30 天下载量：11679（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

在节点或浏览器中读取.hic 联系人矩阵文件

## 安装

```sh
npm install @gmod/hic
```

也可以使用：`pnpm add @gmod/hic`、`yarn add @gmod/hic`、`bun add @gmod/hic`

## README

# 翻译:

[![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)

读取 `.hic` 联系人矩阵文件,在Node.js或浏览器中.

`@gmod/hic` 是一个叉子 [高地画](https://github.com/aidenlab/hic-straw), (中文(简体) ), 在 TypeScript 中重写为获取多个区域对的基因组浏览器 一次超过任意的取景窗口.

## 安装

```
$ npm install @gmod/hic
```

## 使用量

```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, 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()` 财务报告和审定财务报表 `getContactRecords()` 使用可选的跟踪 `{ onProgress }`,称为 `(current, total)`; 见 [文件/附录](https://npmcn.com/package/%40gmod/hic/docs/api.md#progress)。 。 。 .

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

每个同步方法也都需要一个 `AbortSignal` 同样的方式, `{ signal }`,以及 转发到每个已读;见 [文件/附录](https://npmcn.com/package/%40gmod/hic/docs/api.md#cancellation)。 。 。 .

在浏览器中,或对于HTTP上的文件,通过一个 `filehandle` 从 [`generic-filehandle2`](https://www.npmjs.com/package/generic-filehandle2) 而不是一个 `path`数字 :

```js
import { RemoteFile } from 'generic-filehandle2'

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

**通过HTTP,在下面放一个字节距缓存.** 一个查询读取了许多小 分散的块,所以请求数设置了负载时间. [`@gmod/range-cache-filehandle`](https://github.com/GMOD/range-cache-filehandle) 从 69 GB ENCODE 文件切换到 24.0 s 到 1. 8 s (单位:千美元)[文件/优化](https://npmcn.com/package/%40gmod/hic/docs/optimizations.md#round-trips-not-cpu-dominate-a-remote-fetch)) (中文(简体) ).

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

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

拥有自己的 IO 层或缓存的呼叫者可以提供任何读取 `length` 字节数 `position`数字 :

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

见 [文件/附录](https://npmcn.com/package/%40gmod/hic/docs/api.md) 用于完整的API参考.

## 页:1

-   Bin 指数为 **绝对的染色体**,而不是相对于 请求区域.
-   A 类 `.hic` 只存储 `bin1 <= bin2` 矩阵的一半,所以查询其x 窗口的右侧是 y 窗口被交换. `transposed` 标记交换, 财务报告和审定财务报表 `bin1` 然后继续走 `region2`。 。 。 .
-   `appliedNormalization` 用户名称 和你要求的不一样 文件存储矢量每( 类型 :, 染色体,单位,二进制大小,可以提供KR以5kb,而无提供为2.5mb.
-   Bins 仅是碱基对;此叉会降低FRAG( 限制- 分解) 代码路径.
-   与文件本身完全吻合,没有 `chr` 别名.
-   每个 `HicFile` 缓存最多128 MB 已解压的联系人,并丢入 a 屏蔽三分钟内没有读取。 过 `blockCacheMaxBytes` 更改 或共享的 `blockCacheBudget` 将多个文件绑在一起.
-   记录顺序未说明——结果将整块组合,缓存 先来一杯.

## 文档

-   [文件/附录](https://npmcn.com/package/%40gmod/hic/docs/api.md) ——每个构造器选项,方法和返回形状
-   [文件/数据流.md](https://npmcn.com/package/%40gmod/hic/docs/dataflow.md) ——取来如何流出,为什么路径 叉入两条链
-   [文件/优化](https://npmcn.com/package/%40gmod/hic/docs/optimizations.md) 业绩对照 高高地画,什么衡量它
-   [文件/正确性](https://npmcn.com/package/%40gmod/hic/docs/correctness.md) ——分析与 高地画
-   [捐款额](https://npmcn.com/package/%40gmod/hic/CONTRIBUTING.md) - 发展和释放步骤

## 学术用途

这一一揽子计划是利用来自 [(原始内容存档于2018-09-21) (韩语). NHGRI](http://genome.gov/) 作为 页:1 [J 浏览](http://jbrowse.org/) 项目。 如果你在学术中使用它 请引用最近发表的JBrowse论文 链接从 [jbrowse.org (英语)](http://jbrowse.org/)。 。 。 .

如果您使用 `.hic` 请同时引用来自 [艾登实验室](https://github.com/aidenlab)由谁做的.

## 许可证

麻省理工学院,如上游高地画;见 [自由主义](https://npmcn.com/package/%40gmod/hic/LICENSE)。 。 。 .

## 常见问题

### @gmod/hic 是什么？

在节点或浏览器中读取\.hic 联系人矩阵文件

### 如何安装 @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 和提交记录判断。

