@gmod/gff

中文文档
2.1.0发布于 2026/03/18MITTypeScriptESM + CJS零依赖近 30 天下载 8.7万

读取和写入 GFF3 数据为流

中文使用文档
文档目录41 节
  1. 兼容性
  2. 安装
  3. 使用量
  4. 节点.js 实例
  5. 浏览器示例
  6. 对象格式
  7. 特性
  8. 指令
  9. 评论
  10. 序列
  11. API 密码
  12. 解析选项
  13. GFF 转换器
  14. 解析同步
  15. 格式同步
  16. 格式选项
  17. GFF 格式转换器
  18. 关于 util
  19. 用户
  20. 无法回避
  21. 逃脱
  22. 越狱
  23. 解析属性
  24. 剖析形状
  25. 解析指令
  26. 格式属性
  27. 格式
  28. 格式指令
  29. 格式Comment
  30. 格式顺序
  31. 项目
  32. GFF3 属性
  33. GFF3 外观线
  34. GFF3 带有参考文献的外观线
  35. GFF3 形状
  36. 基础GFF3 指令
  37. GFF3 顺序管理指令
  38. GFF3 Genome 构建指令
  39. GFF3( GFF3) Comment
  40. GFF3 顺序
  41. 许可证

@gmod/gff (英语)

Build Status

读写GFF3数据表现良好. 本单元旨在完成 执行情况 GFF 3 (英语) 规格。 。 。 .

注:本模块使用国家防范机制流套件,需要节点.js多填充器供网络使用。 我们还创造了 https://github.com/cmdcolin/gff-nostream 互联网档案馆的存檔,存档日期2013-12-22 包允许不需要多填充的非流式版本

  • 流出解析和流出格式
  • 属性和列值的正确逃出和解去
  • 支持具有多个位置的特性和具有多个父母的特性
  • 重建两者的特征等级 Parent 财务报告和审定财务报表 Derives_from 关系
  • 剖析 FASTA 段落
  • 除下列因素外,不作任何验证: Parent 财务报告和审定财务报表 Derives_from 关系( 能够禁用从引用检查中获取) 与 disableDerivesFromReferences(中文(简体) )
  • 仅兼容 GFF3

兼容性

在浏览器中工作,并与Node.js v18并上.

安装

$ npm install --save @gmod/gff

使用量

节点.js 实例

import {
  createReadStream,
  createWriteStream,
  readFileSync,
  writeFileSync,
} from 'fs'
import { Readable, Writable } from 'stream'
import { TransformStream } from 'stream/web'
import {
  formatSync,
  parseStringSync,
  GFFTransformer,
  GFFFormattingTransformer,
} from '@gmod/gff'

// parse a file from a file name. parses only features and sequences by default,
// set options to parse directives and/or comments
;(async () => {
  const readStream = createReadStream('/path/to/my/file.gff3')
  const streamOfGFF3 = Readable.toWeb(readStream).pipeThrough(
    new TransformStream(
      new GFFTransformer({ parseComments: true, parseDirectives: true }),
    ),
  )
  for await (const data of streamOfGFF3) {
    if ('directive' in data) {
      console.log('got a directive', data)
    } else if ('comment' in data) {
      console.log('got a comment', data)
    } else if ('sequence' in data) {
      console.log('got a sequence from a FASTA section')
    } else {
      console.log('got a feature', data)
    }
  }

  // parse a string of gff3 synchronously
  const stringOfGFF3 = readFileSync('/path/to/my/file.gff3', 'utf8')
  const arrayOfGFF3ITems = parseStringSync(stringOfGFF3)

  // format an array of items to a string
  const newStringOfGFF3 = formatSync(arrayOfGFF3ITems)
  writeFileSync('/path/to/new/file.gff3', newStringOfGFF3)

  // read a file, format it, and write it to a new file. inserts sync marks and
  // a '##gff-version 3' header if one is not already present
  await Readable.toWeb(createReadStream('/path/to/my/file.gff3'))
    .pipeThrough(
      new TransformStream(
        new GFFTransformer({ parseComments: true, parseDirectives: true }),
      ),
    )
    .pipeThrough(new TransformStream(new GFFFormattingTransformer()))
    .pipeTo(Writable.toWeb(createWriteStream('/path/to/my/file.gff3')))
})()

浏览器示例

import { GFFTransformer } from '@gmod/gff'

// parse a file from a URL. parses only features and sequences by default, set
// options to parse directives and/or comments
;(async () => {
  const response = await fetch('http://example.com/file.gff3')
  if (!response.ok) {
    throw new Error('Bad response')
  }
  if (!response.body) {
    throw new Error('No response body')
  }
  const streamOfGFF3 = response.body.pipeThrough(
    new TransformStream(
      new GFFTransformer({ parseComments: true, parseDirectives: true }),
    ),
  )
  for await (const chunk of streamOfGFF3) {
    if ('directive' in data) {
      console.log('got a directive', data)
    } else if ('comment' in data) {
      console.log('got a comment', data)
    } else if ('sequence' in data) {
      console.log('got a sequence from a FASTA section')
    } else {
      console.log('got a feature', data)
    }
  }
})()

对象格式

特性

在GFF3中,特征可以拥有多个位置. 我们分析特征 作为所有共享该特性ID的行的阵列. 数值为 . 在GFF3中为: null 在输出中.

一个简单的特征,它只位于一个地方:

[
  {
    "seq_id": "ctg123",
    "source": null,
    "type": "gene",
    "start": 1000,
    "end": 9000,
    "score": null,
    "strand": "+",
    "phase": null,
    "attributes": {
      "ID": ["gene00001"],
      "Name": ["EDEN"]
    },
    "child_features": [],
    "derived_features": []
  }
]

一个CDS呼叫 cds00001 位于两地:

[
  {
    "seq_id": "ctg123",
    "source": null,
    "type": "CDS",
    "start": 1201,
    "end": 1500,
    "score": null,
    "strand": "+",
    "phase": "0",
    "attributes": {
      "ID": ["cds00001"],
      "Parent": ["mRNA00001"]
    },
    "child_features": [],
    "derived_features": []
  },
  {
    "seq_id": "ctg123",
    "source": null,
    "type": "CDS",
    "start": 3000,
    "end": 3902,
    "score": null,
    "strand": "+",
    "phase": "0",
    "attributes": {
      "ID": ["cds00001"],
      "Parent": ["mRNA00001"]
    },
    "child_features": [],
    "derived_features": []
  }
]

指令

parseDirective("##gff-version 3\n")
// returns
{
  "directive": "gff-version",
  "value": "3"
}
parseDirective('##sequence-region ctg123 1 1497228\n')
// returns
{
  "directive": "sequence-region",
  "value": "ctg123 1 1497228",
  "seq_id": "ctg123",
  "start": "1",
  "end": "1497228"
}

评论

parseComment('# hi this is a comment\n')
// returns
{
  "comment": "hi this is a comment"
}

序列

这些来自任何嵌入 ##FASTA gFF3文件中的章节.

parseSequences(`##FASTA
>ctgA test contig
ACTGACTAGCTAGCATCAGCGTCGTAGCTATTATATTACGGTAGCCA`)[
  // returns
  {
    id: 'ctgA',
    description: 'test contig',
    sequence: 'ACTGACTAGCTAGCATCAGCGTCGTAGCTATTATATTACGGTAGCCA',
  }
]

API 密码

目录

解析选项

解析选项

禁用参考文献

是否解决来自特性的引用

类型 : 布尔

剖析形状

是否分析特性, 默认为真

类型 : 布尔

解析指令

是否分析指令, 默认错误

类型 : 布尔

解析Comment

是否分析注释, 默认为虚假

类型 : 布尔

解析顺序

是否解析序列, 默认为真

类型 : 布尔

缓冲大小

GFF3 缓冲的最大行数, 默认无限

类型 : 编号

GFF 转换器

将文本数据流分析成特性、指令、注释、, 序列对象.

参数

  • options 欧? 解析选项

解析同步

同步解析包含 GFF3 的字符串并返回数组 解析项目.

参数

  • str 字符串 GFF3 字符串
  • inputOptions 欧? 分析选项

回返 任意 一系列解析的特征、指令、评论和/或序列

格式同步

将 GFF3 项( 特征、 方向、 注释) 的数组格式化为 GFF3. 不插入同步 (QQ) 标记 .

参数

  • items 阵列<GFF3项目> 特征、指令、评论和/或顺序组合

回返 字符串 格式化的 GFF 3

格式选项

主题选项

分钟同步线

同步( QQ) 指令之间发出的最小行数, 默认 100个

类型 : 编号

插入变位指令

是否在格式化开头插入版本指令 如果一个不存在, 默认为真实

类型 : 布尔

GFF 格式转换器

将一系列特征、指令、评论和/或顺序转换成 gFF3 文本流.

自动插入同步 (QQ) 标记 .

参数

  • options 格式选项 格式选项( 可选, 默认) {}(中文(简体) )

关于 util

还有一个 util 模块,其中包含处理行和部分行的超低级函数.

import { util } from '@gmod/gff'

const gff3Lines = util.formatItem({
  seq_id: 'ctgA',
  ...
})

用户

目录

无法回避

取消 GFF3 属性中使用的字符串值.

参数

  • stringVal 字符串 已逃出 GFF3 字符串值

回返 字符串 未脱逃的字符串值

逃脱

逃避 GFF3 属性值中的值.

参数

  • rawVal (单位:千美元)字符串 | 编号(中文(简体) ) Raw GFF3 属性值

回返 字符串 已逃出字符串值

越狱

退出 GFF3 列值中的值.

参数

  • rawVal (单位:千美元)字符串 | 编号(中文(简体) ) 原始 GFF3 列值

回返 字符串 隐藏的列值

解析属性

解析 GFF3 特性行的第 9 列(属性) .

参数

  • attrString 字符串 GFF3 第9列的字符串

回返 GFF3 属性 解析属性

剖析形状

解析 GFF3 特性行

参数

回返 GFF3 外观线 解析特性

解析指令

解析 GFF3 指令行 .

参数

回返 (GFF3 指令 + ) GFF3 顺序管理指令 | GFF3 Genome 构建指令 无效) 解析指令

格式属性

将属性对象格式化为适合GFF3 第9列的字符串.

参数

回返 字符串 GFF3 第9列字符串

格式

将特征对象或特征对象的数组格式化为一个或多个行 GFF3. (英语).

参数

回返 字符串 一个或多个 GFF3 行的字符串

格式指令

将指令格式化为 GFF3.

参数

  • directive GFF3 指令 指令对象

回返 字符串 指令行字符串

格式Comment

将注释格式化为 GFF3 注释. 是的,我知道这只是增加一个 #和一个新线.

参数

回返 字符串 注释行字符串

格式顺序

将序列对象格式化为 FASTA

参数

回返 字符串 格式化的单一 FASTA 序列字符串

项目

格式化此类项目的指示、注释、顺序或特征或数组, 进入 GFF3 的一行或多行 .

参数

回返 字符串 格式化字符串或字符串数组

GFF3 属性

GFF3 属性标识符和这些标识符值的记录

类型: 记录 <字符串, (中文(简体) ), 阵列<字符串>>

GFF3 外观线

GFF3 文件单行表示

下行编号

为当前特性建立坐标系统的地标标识

类型 : (字符串 无效)

来源

用于描述生成此特性的算法或操作程序的免费文本限定符

类型 : (字符串 无效)

类型

特征的类型

类型 : (字符串 无效)

开始

特性的起始坐标

类型 : (编号 无效)

结束

地物的终点坐标

类型 : (编号 无效)

分数

特征的分数

类型 : (编号 无效)

线条

特征的边缘

类型 : (字符串 无效)

阶段

对于"CDS"类型的特性,相位表示相对于当前 CDS 特性的 5' 端的下个codon 起始位置

类型 : (字符串 无效)

属性

特性属性

类型 : (GFF3 属性 无效)

GFF3 带有参考文献的外观线

扩展 GFF3 外观线

GFF3 特性行, 包括参考在 其“ 父母” 或“ 来自” 属性

子特征( c)

一系列儿童特征

类型 : 阵列<GFF3 形状> 翻译:

属性( f):

从此特性衍生出的一系列特性

类型 : 阵列<GFF3 形状> 翻译:

GFF3 形状

GFF3 特性, 可能包括多个单个特性行

类型 : 阵列<GFF3 带有参考文献的外观线> 翻译:

基础GFF3 指令

GFF3 指令

指令

指令的名称

类型 : 字符串

价值

指令的字符串值

类型 : 字符串

GFF3 顺序管理指令

扩展 BaseGFF3 指令

GFF3 序列区域指令

价值

指令的字符串值

类型 : 字符串

下行编号

从指令解析的序列 ID

类型 : 字符串

开始

序列从指令开始解析

类型 : 字符串

结束

从指令解析的序列端

类型 : 字符串

GFF3 Genome 构建指令

扩展 BaseGFF3 指令

GFF3 基因组建设指令

价值

指令的字符串值

类型 : 字符串

来源

基因组从指令中解析出源

类型 : 字符串

构建Name

基因组构建名称从指令中解析

类型 : 字符串

GFF3( GFF3) Comment

GFF3 评论

注释

评论意见的案文

类型 : 字符串

GFF3 顺序

GFF3 FASTA 单序列

编号

序列的标识

类型 : 字符串

说明

序列的描述

类型 : 字符串

顺序

顺序

类型 : 字符串

许可证

麻省理工学院 罗伯特·布厄尔斯

版本与发布记录

@gmod/gff 共发布 12 个版本,首次发布于 2018/04/04;过去 12 个月发布了 1 个版本。

版本发布日期距今
2.1.0latest2026/03/187 个月前
2.0.02025/10/041.1 年前
1.3.02022/12/073 年前
1.2.32022/10/194 年前
1.2.22022/10/194 年前
1.2.12022/03/314 年前

其他发布通道:beta → 0.0.1。

关于 @gmod/gff 的常见问题

@gmod/gff 是什么?

读取和写入 GFF3 数据为流

如何安装 @gmod/gff?

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

@gmod/gff 支持 TypeScript 吗?

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

@gmod/gff 支持 ESM 还是 CommonJS?

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

@gmod/gff 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=18。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gmod/gff 可以商用吗?

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

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

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

@gmod/gff 还在维护吗?

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