跳到主要内容

IGV 基因组浏览器

规格​

标签值
版本0.1.1（更新于 2026-05-31）
开发者Labii Inc.
类型章节
支持配置是

概述​

IGV Genome Browser 小插件将 Integrative Genomics Viewer 团队开发的交互式基因组可视化组件 igv.js 直接嵌入 Labii 记录章节。实验室团队无需离开当前记录，即可打开参考基因组、跳转到某个位点、加载一条或多条基因组轨道，并叠加感兴趣区域。该小插件适合结合实验备注、样品元数据和其他 Labii 内容查看比对结果、注释、变异或自定义基因组区间。其配置遵循 IGV.js 的核心浏览器创建模型，尤其是官方的浏览器创建、参考基因组和 ROI 文档。

使用场景​

  • NGS 结果审查：在测序运行记录旁显示 BAM、CRAM、BigWig、BED 或变异轨道，以便快速进行目视检查。
  • 靶向检测验证：打开已知位点并叠加感兴趣区域，确认特定扩增子或基因的覆盖情况或变异证据。
  • 特定参考序列项目：为非模式生物、专有组装或项目专属重叠群加载自定义 FASTA 或 twoBit 参考序列。
  • 注释比较：在同一浏览器中组合基因模型、覆盖度轨道和变异轨道，比较不同轨道类型的证据。
  • 协作式记录审查：将可复现的浏览器设置保存在章节中，使团队成员打开相同的初始基因组、位点和轨道布局。
  • 质量与合规工作流程：将基因组可视化证据附加到记录中，同时记录解读、批准和后续决策。

界面​

只读视图​

只读视图在章节中显示嵌入式 IGV.js 浏览器。Labii 保留 IGV 的核心浏览体验，同时提供多项特别适用于以记录为中心的工作流程的菜单操作：

  • Genome menu：选择为小插件配置的当前基因组或参考上下文。
  • Tracks menu：使用 Labii 专用批量操作管理可见轨道，包括显示或隐藏所选轨道、选择所有轨道和取消选择所有轨道。
  • Sample Info menu：在当前工作流程中可用时，打开与已加载浏览器会话关联的样品元数据。
  • Session menu：处理当前浏览器会话状态。
  • Save Image menu：从下拉菜单导出当前浏览器视图。
  • 位点导航：自动加载初始位点；导航控件可以提供搜索、放大和缩小操作。
  • 轨道显示：在 Tracks JSON 中定义的轨道以堆叠泳道形式呈现，并提供 IGV.js 专用的检查和交互控件。
  • 染色体示意图和标尺：可选的染色体示意图和基因组标尺元素提供染色体上下文和基因组坐标。
  • 视觉辅助线：可选的中心辅助线和光标辅助线帮助用户在检查密集基因组数据时聚焦到准确坐标。
  • ROI 叠加层：配置后，感兴趣区域会以半透明叠加层形式显示在轨道上。

此章节主要用作查看器。大多数用户交互通过平移、缩放、搜索、会话控制和轨道检查完成，而不是编辑记录文本。

编辑视图​

在编辑模式下，小插件仍然是交互式基因组浏览器，但主要更改通常通过章节配置完成，而不是以内联方式输入内容。用户可以在编辑记录时继续检查位点和轨道，并根据需要通过小插件配置面板调整基因组、轨道、ROI、存储或界面设置。

Labii 还扩展了此视图中的默认 IGV 轨道交互方式。标准 IGV 通常支持用户逐条拖动轨道进行重新排序；在 Labii IGV 小插件中，用户可以选择多条轨道并一起拖动整个选择，从而更快地重组较大的轨道集合。

IGV 基因组浏览器章节小插件编辑视图

信息

当远程基因组文件托管在支持 CORS 和字节范围请求的 Web 服务器上时，IGV Genome Browser 小插件的效果最佳；索引基因组格式通常需要这些功能。

配置​

IGV Genome Browser 小插件直接对应标准 IGV.js 浏览器配置概念。在 IGV.js 中，必须提供基因组标识符或参考对象之一。在 Labii 中，这意味着应先配置 Genome 或 Reference JSON，浏览器才能加载有意义的数据。

将章节添加到记录，并从小插件库中选择 IGV Genome Browser。

配置基因组上下文：

  • Genome：输入受支持的 IGV 基因组标识符，例如 hg38、hg19 或其他托管/GenArk 组装 ID。
  • Reference JSON：如果需要使用自己的 FASTA 或 twoBit URL 定义自定义参考序列，请使用此项代替 Genome。

设置初始视图和数据源：

  • Locus：定义初始基因组位置，例如 chr17:7,572,927-7,579,912。
  • Tracks JSON：提供 IGV.js 轨道配置对象的 JSON 数组，以便启动时加载。
  • Regions Of Interest JSON：根据需要提供 ROI 定义，以突出显示各轨道上的区间。

调整浏览器行为和外观：

  • Track Defaults JSON：为受支持的轨道类型提供默认设置。
  • Browser folder：根据需要设置本地文件夹路径，用于存储从浏览器添加的文件。
  • Minimum Bases：设置最小缩放窗口大小，以碱基对为单位。
  • Height：设置查看器高度，以像素为单位。
  • Show navigation、Show ideogram、Show ruler、Show SVG button、Show center guide、Show cursor track guide：开启或关闭界面元素。
  • Query parameters supported：如果部署使用共享 URL 或外部启动参数，请启用 IGV.js 查询参数初始化行为。

保存章节，并验证浏览器是否加载预期的基因组、位点和轨道。

必填设置​

  • Genome：IGV.js 可识别的基因组标识符。内置 IGV 托管基因组或 UCSC GenArk 组装足以满足需求时，请使用此项。
  • Reference JSON：自定义参考对象。需要明确控制 FASTA 或 twoBit 文件、索引、细胞遗传带、别名或与参考序列关联的轨道时，请使用此项。
信息

至少配置 Genome 或 Reference JSON 之一。实际使用中，标准组装请使用 Genome；自定义基因组或需要完全控制参考资源时，请使用 Reference JSON。

可选设置​

  • Locus：初始基因组位置。通常为类似 chr1:1-1000 的字符串，决定用户最先看到的内容。
  • Tracks JSON：小插件打开时加载的 IGV.js 轨道对象数组。用于预加载比对、注释、变异、覆盖度和其他受支持的轨道。
  • Reference JSON：设置 Genome 后为可选项；需要自定义参考元数据或 URL 时应优先使用。
  • Track Defaults JSON：定义轨道类型默认显示属性的 JSON 对象，帮助多条轨道保持一致的外观。
  • Browser folder：映射到 local_folder_path 配置。如果希望从小插件添加的文件复制到指定的本地浏览器文件夹，而不是上传到 Labii 文件系统，请使用此项。
  • Regions Of Interest JSON：ROI 配置对象数组。可以通过 BED/GFF 等注释文件或明确的 {chr, start, end} 特征数组提供 ROI 集合。
  • Minimum Bases：放大时以碱基对为单位的最小窗口大小。IGV.js 默认为 40；提高此值可以防止过度放大。
  • Height：嵌入式浏览器视口的高度，以像素为单位。
  • Show navigation：显示搜索和缩放等基本导航控件。
  • Show ideogram：在浏览器标题中显示染色体示意图。
  • Show ruler：显示基因组标尺轨道。
  • Show SVG button：显示用于将当前浏览器视图导出为 SVG 的控件。
  • Show center guide：显示中心标记线，框定当前视图中心位置。
  • Show cursor track guide：显示跟随指针在各轨道间移动的垂直辅助线。
  • Query parameters supported：在托管上下文适用时，允许 IGV.js 使用受支持的查询参数初始化。

高级配置​

以下示例与 IGV.js 官方指南中记录的结构一致。

本地浏览器文件夹配置​

使用以下配置条目控制新添加文件的存储方式：

local_folder_path: {
  title: "Browser folder",
  description: "Select a browser folder for local IGV file storage. If empty, dropped files are uploaded to Labii."
}

上面的配置标签与小插件设置文本一致。在当前 Labii 使用方式中，最终用户不能将文件直接拖放到浏览器画布；此设置控制通过受支持的工作流程添加新轨道文件时，这些文件的存储位置。

存储行为取决于是否设置此值：

  • 如果未提供 local_folder_path，通过小插件添加的文件将通过 Labii 文件系统上传到 S3。
  • 如果提供了 local_folder_path，添加的文件将复制到该本地文件夹路径，而不会上传。
  • 本地浏览器文件夹通常更适合非常大的序列文件，因为无需让这些文件经过 Labii 管理的对象存储。

Reference JSON 示例​

{
  "id": "custom-hg38",
  "name": "Human GRCh38 Custom",
  "fastaURL": "https://example.org/genomes/hg38.fa",
  "indexURL": "https://example.org/genomes/hg38.fa.fai",
  "cytobandURL": "https://example.org/genomes/cytoBandIdeo.txt"
}

Tracks JSON 示例​

[
  {
    "name": "RefSeq Genes",
    "type": "annotation",
    "format": "bed",
    "url": "https://example.org/tracks/refseq.bed.gz",
    "indexURL": "https://example.org/tracks/refseq.bed.gz.tbi"
  }
]

Regions Of Interest JSON 示例​

[
  {
    "name": "Clinically relevant regions",
    "url": "https://example.org/tracks/roi.bed",
    "indexed": false,
    "color": "rgba(255, 0, 0, 0.20)"
  }
]
注意

对于大型 BAM、CRAM、VCF、FASTA 和其他索引基因组资源，请先确认源服务器支持范围请求和跨源访问，再排查小插件本身的问题。

其他功能​

启用 Show navigation 后，用户可以使用 IGV.js 提供的内置搜索和缩放控件在基因组区域之间快速移动。这适用于记录审查期间从一个基因或坐标范围跳转到另一个位置。

轨道加载与呈现​

此小插件可以打开 Tracks JSON 中定义的多种轨道类型，使一个章节能够组合注释、比对、变异、覆盖度和其他基因组证据。Track Defaults JSON 有助于规范页面加载时受支持轨道类型的呈现方式。

在 Tracks 下拉菜单中，用户可以：

  • 显示或隐藏所选轨道。
  • 在应用批量操作前选择轨道。
  • 选择所有轨道。
  • 取消选择所有轨道。

Labii 还扩展了默认 IGV 行为，支持同时拖动所有选中的轨道。需要以组为单位重组大量可见轨道，而不是逐条移动时，此功能非常实用。

用户不能通过将文件直接拖放到浏览器画布来添加新轨道。必须通过小插件支持的添加轨道工作流程添加新文件；随后系统会根据 local_folder_path 设置存储文件。

感兴趣区域叠加层​

在 Regions Of Interest JSON 中定义的 ROI 集合会以半透明突出显示区域的形式叠加在轨道上。这适合强调引物、扩增子、外显子区间、致病位点或其他对当前工作流程很重要的区域。

SVG 导出​

如果启用了 Show SVG button，用户可以将当前浏览器视图导出为 SVG 图像。

打开记录并导航到要捕获的基因组区域。

调整可见轨道、缩放级别和突出显示的区间，直到浏览器显示所需视图。

点击小插件标题或浏览器控件中的 SVG 导出按钮。

保存导出的图像，用于报告、审查材料或后续文档。

共享视图和参数化视图​

在兼容的部署中启用 Query parameters supported 后，小插件可以参与基于 IGV.js 查询参数的初始化。这可以支持从外部启动视图，或使用共享链接直接打开特定基因组上下文。

有关完整选项详情，请参阅 IGV.js 官方文档：

最佳实践​

数据准备​

  • 尽可能使用索引基因组文件格式，让用户可以高效浏览大型数据集。
  • 在相关记录中保持参考序列定义稳定，使团队能够根据相同组装比较轨道。
  • 在 Tracks JSON 中为轨道使用清晰名称，让用户可以快速区分注释、比对、覆盖度和变异证据。

性能优化​

  • 加载大型轨道时，让小插件从范围明确的 Locus 开始，而不是非常宽的基因组范围。
  • 使用 Minimum Bases 防止用户将底层数据类型放大到不切实际的小窗口。
  • 将 Height 设置为足以清晰阅读的高度，但在包含许多其他章节的页面中避免使用过大的查看器。
  • 如果希望避免将大型本地序列资源上传到以 S3 为后端的 Labii 存储，请优先使用 Browser folder（local_folder_path）。

部署与访问​

  • 将基因组资源托管在支持 CORS 和字节范围请求的服务器上。
  • 将小插件用于生产模板前，请验证 Reference JSON、Tracks JSON 和 Regions Of Interest JSON 中的外部 URL。
  • 尽可能通过 Genome 使用内置基因组 ID，以减少配置开销和风险。
提示

为确保记录审查可复现，请在小插件配置中存储固定的初始基因组、位点和标准轨道集，使每位用户都从相同的基因组上下文开始。

应避免的常见问题​

  • 避免同时配置宽泛模糊的位点和大量远程大型轨道，否则首次加载可能明显变慢。
  • 避免将未索引的 FASTA 或大型注释文件用于生产规模的浏览，除非这些文件本身确实较小。
  • 避免仅仅因为远程数据源 URL 可以在浏览器标签页中打开，就假设该数据源可访问；索引基因组浏览通常还依赖其他服务器行为。
  • 避免期望在浏览器画布中使用桌面式拖放文件导入；此小插件不支持通过拖放文件创建新轨道。
  • 建议在广泛发布模板之前，使用实际生产 URL 和预期用户权限测试小插件。
编辑此页
最后由 Yonggan Wu 于 更新