Source code

Download source archive ↓

README_zh.md

1# Galaxy 文本与表格算子
2
3[English](README.md)
4
5本目录提供 15 个通过源码发布的 Scala 算子,基于 [Galaxy tools-devteam](https://github.com/galaxyproject/tools-devteam) 的文本工具实现,上游版本为 `ddbe2a1e6eded54877d786fbcfc18e594fb12932`。原始脚本、XML 定义和标准测试数据保留在 `upstream/`,SHA-256 记录在 `upstream-manifest.json`。本集合包含 15 个文本/FASTA/SAM 工具,并非完整 Galaxy 工具集合,也不是 Galaxy 工作流导入器。
6
7## 选择算子
8
9所有算子的版本均为 `1.0`,包含一个 `source` bytes 输入和一个 `result` bytes 输出,文本编码为 UTF-8。它们通过 JVM SDK 提供结构推导和受大小限制的输出样例。`bytes` 输出表达表格文本,不会声明 Arrow records schema;需要 records 时应连接合适的文本/TSV 解析算子。共享运行时为 `jvm-arrow@2.1`,产物是薄 JAR,无新增运行时依赖。
10
11| 算子 | 参数(默认值) | 行为 / 上游工具 |
12| --- | --- | --- |
13| `galaxy_change_case` | `columns: c1`、`delimiter: tab`、`casing: upper` | 修改所选字段大小写,输出 TSV / `change_case/changeCase.pl` |
14| `galaxy_condense_characters` | `character: tab` | 压缩连续重复字符,输出文本 / `condense_characters/condense_characters.pl` |
15| `galaxy_convert_delimiters` | `character: tab` | 去除每行首尾空白,将连续分隔符转换为制表符,输出 TSV / `convert_characters/convert_characters.py` |
16| `galaxy_cut_columns` | `columns: c1`、`delimiter: tab` | 选择、重排、重复列,跳过 `#` 行,缺失字段填 `.`,输出 TSV / `cut_columns/cutWrapper.pl` |
17| `galaxy_merge_columns` | `columns: c1` | 将所选字段无分隔拼接后附加一列,忽略缺失字段,保留注释和空行,输出 TSV / `merge_cols/mergeCols.py` |
18| `galaxy_add_column` | `value: "1"`、`iterate: false` | 附加常量;启用递增后非负整数从该值递增,其他值生成 `value-0`、`value-1` 等,输出 TSV / `add_value/fixedValueColumn.pl` |
19| `galaxy_fasta_length` | `keep_first: 0`、`id_only: false` | 统计每条序列字符数,输出标题/标识与长度 TSV / `fasta_compute_length/fasta_compute_length.py` |
20| `galaxy_fasta_filter_length` | `min_length: 0`、`max_length: 0` | 保留长度在闭区间中的序列,最大值为零表示无上限 / `fasta_filter_by_length/fasta_filter_by_length.py` |
21| `galaxy_fasta_to_tabular` | `keep_first: 0`、`description_columns: 1` | 输出标题字段和拼接序列 TSV / `fasta_to_tabular/fasta_to_tabular.py` |
22| `galaxy_remove_beginning` | `lines: 10` | 删除前 N 行,保留剩余行的换行格式 / `remove_beginning/remove_beginning.pl` |
23| `galaxy_head` | `lines: 10` | 输出前 N 行,并消费剩余输入 / `show_beginning/headWrapper.pl` |
24| `galaxy_tail` | `lines: 10` | 通过受限滚动缓冲区输出最后 N 行 / `show_tail/tailWrapper.pl` |
25
26| `galaxy_tabular_to_fasta` | `title_columns: "1"`, `sequence_column: 2` | 标题列以下划线拼接并输出 FASTA,缺少选定列时跳过该行 / `tabular_to_fasta/tabular_to_fasta.py` |
27| `galaxy_sam_filter_flags` | `require_flags: 0`, `exclude_flags: 0` | 要求指定标志位全部置位、排除位全部未置位,省略头部 / `sam_bitwise_flag_filter/sam_bitwise_flag_filter.py` |
28| `galaxy_sam_to_interval` | `print_all: false` | 将已映射比对输出为零起点、左闭右开区间 / `sam2interval/sam2interval.py` |
29
30`columns` 从 1 开始,格式如 `c1,c4,c2-c3`,展开后最多 1024 列,最大列号 999999。`delimiter` 可选 `tab`、`comma`、`dash`、`underscore`、`pipe`、`dot`、`whitespace`;`character` 还支持 `space`、`colon`。未知参数、不支持的枚举和错误列配置会在结构推导及执行时失败。`value` 不能包含制表符或换行。参数不是 shell 命令或正则表达式。这些是按分隔符处理的文本工具,不是支持引号的 CSV 工具,不能用来解析带引号的 CSV 字段。
31
32```mermaid
33flowchart LR
34    A[Item bytes 视图] --> B[统一分隔符]
35    B --> C[修改所选列大小写]
36    C --> D[附加行标识]
37    D --> E[TSV bytes 流]
38```
39
40## 执行 Job
41
42发布后,从 XStream 项目根目录执行:
43
44```bash
45xstream-engine/target/universal/stage/bin/xstream-runner \
46  examples/operators/galaxy/engine.yaml examples/operators/galaxy/job.yaml
47```
48
49示例读取 `context:/galaxy/input.txt`,将连续逗号转换为制表符,将第一列改为大写,再附加递增标识,输出:
50
51```text
52SAMPLE	group	row-0
53ALPHA	a	row-1
54BETA	b	row-2
55```
56
57将 `remote_operator_library_urls` 设置为所用仓库,并按需要配置传输信任。发布无需修改核心注册表,也无需重新构建执行服务器。
58
59## 构建与验证
60
61先将 XStream JVM SDK 发布到本地,然后在本目录执行:
62
63```bash
64sbt package 'Test / runMain xstream.galaxy.SafetyCheck'
65python3 make-catalog.py
66python3 verify.py --docker-prefix '' --report /tmp/galaxy-tests.json
67```
68
69验证脚本所用 Python 环境需安装 PyArrow 和 PyYAML。`verify.py` 在本地 Docker 中使用已注册的运行时镜像,执行期间禁用网络。`--docker-prefix` 默认值为本开发机使用的 `sudo -n -u cnic -g docker`;当前用户已有 Docker 权限时使用 `''`。通过 `--runtime IMAGE` 可选择其他兼容镜像。测试比较 28 组 Galaxy 测试数据(其中两个区间预期修正了上游 padding 错误),覆盖 65 个执行用例,包括空输入、两字节 Arrow 分块、Unicode、CRLF、末行无换行;还验证 15 个推导/样例契约、错误参数、非法 UTF-8、超长行和三步算子流水线。`SafetyCheck` 验证取消、I/O 异常传播、参数错误、输出展开限制、FASTA 记录限制和 tail 缓冲区限制。使用 `--artifact FILE --only NAME` 可以在审核前验证单个仓库构建的 JAR。
70
71输入可跨 Arrow 批次连续读取,不会缓存整个 Item。单行限制为 1,048,576 个 UTF-16 字符,所选/生成字段拼接限制为 4,194,304 个字符,参数字符串最多 4096 个字符,所选列最多 1024 个。工作内存受这些单行限制和 SDK 缓冲区约束。输出样例遵守 SDK 字节预算。读取期间和每行处理均检查取消,输入与输出异常传递给引擎。业务逻辑不调用 shell、子进程、网络或应用文件访问。
72
73## 发布源码
74
75```bash
76python3 publish.py --url http://localhost:8820 \
77  --token-file /secure/publisher.token --output /tmp/galaxy-publication
78```
79
80该命令提交 15 份源码归档,由仓库隔离构建 Scala 算子,保持待审核状态。只提交一个工具时,在末尾添加短名称,例如 `cut_columns`。管理员可以增加 `--approve-password-file /secure/admin-password`;该模式等待构建,下载并验证每个候选产物,指定 `Galaxy`、`Text processing`、`Tabular data` 分类(FASTA 工具使用 `Galaxy`、`FASTA`、`Bioinformatics` 分类,SAM 工具使用 `Galaxy`、`SAM`、`Bioinformatics` 分类)和 4 分可信度,再审批发布,并核验公开下载与已测试候选产物一致。测试失败即停止发布。凭据从独立文件读取,不会打包或打印。远程发布必须使用 HTTPS。可信度是评估结果,不是安全保证。审核记录和产物测试报告写入 `--output`。
81
82每份源码归档包含 Scala 实现、上游证据、中英文说明、验证脚本和完整许可文本;发布的 JAR 内包含 `META-INF/LICENSE`、`META-INF/NOTICE` 和对应算子定义。源码公开。仓库管理和构建前提见[源码提交](../../../docs/operator-submission_zh.md)。
83
84## 行为与归属
85
86标准测试数据保持上游行为。有意调整包括:LF/CRLF/CR 均统一为 LF,末行没有换行时不会丢掉最后一个字符;拒绝非法 UTF-8;大小写转换采用不依赖区域设置的 Unicode 规则;`condense_characters` 将连续空白转为一个空格(上游 `s` 选项缺少有效替换分支);点号压缩输出字面量点号,避免原 Perl 脚本的转义替换结果;分隔符采用可读枚举;错误参数直接失败,不再静默忽略。change/cut 的尾部空字段遵循原 Perl 工具,merge 遵循原 Python 工具。资源限制和取消行为明确。
87
88Galaxy Contributors 保留原始工具与测试数据的版权。上游许可将 2024-12-01 前的贡献归为 AFL-3.0,此后的贡献归为 MIT。[LICENSE](LICENSE) 原样包含两种完整许可,混合来源声明为 `AFL-3.0 AND MIT`。另见 [NOTICE](NOTICE)。这些是独立的 XStream 适配实现,不是 Galaxy 官方发行版。
89
90## FASTA 与行选择说明
91
92`keep_first` 按 Unicode 字符截断标题,零表示保留全部;`id_only` 选择标题的第一个单词。FASTA 长度是序列字符数,不是生物学质量或合法性评估。转表格时,`description_columns: 1` 保留完整标题;更大值拆分开头单词,补齐缺失列,并将剩余描述保留在最后一列。序列跨行直接输出,不缓存整个序列。序列出现在 `>` 标题之前时拒绝输入,跳过注释和空行。空 FASTA 不产生记录,不生成虚假的零长度记录。FASTA 输出使用 LF。过滤最多保留一个 8,388,608 字符的记录;超过非零最大长度的记录立即丢弃其序列缓存。按照上游测试数据,只有输入最后一条记录被保留时,该记录末尾才不加换行。这不会将序列强行推导为 records schema。
93
94head/remove-beginning 接受 0–1,000,000 行;tail 接受 0–10,000 行,保留的 UTF-16 字符合计最多 8,388,608 个。这三个工具保留 LF、CRLF、CR 和末行无换行的情况。即使 head 已输出足够行数,也继续消费输入到 Arrow EOS。不调用 `head`、`tail` 或 shell。长度统计与原工具一样去除序列行两端空白;过滤和转表格保留并统计其他序列字符。结构推导和执行均检查参数。
95
96从 XStream 根目录运行第二个完整示例:
97
98```bash
99xstream-engine/target/universal/stage/bin/xstream-runner \
100  examples/operators/galaxy/engine.yaml examples/operators/galaxy/job-fasta.yaml
101```
102
103```text
104seq1	12	sequence-0
105seq3	20	sequence-1
106```
107
108每个目录条目都包含 `documentation`:所有输入、输出及参数说明、符合 schema 的示例值,以及完整 Job。发布脚本随源码提交这些字段,仓库接收前会校验。`catalog.json` 同时提供 15 个算子定义的本地参考。固定运行时和测试结果见[验证结果](verification.json)。
109
110## SAM 与表格序列示例
111
112`job-sam.yaml` 读取 `data/alignments.sam`,保留正确配对且已映射的 reads,计算基因组区间。使用与其他示例相同的引擎配置运行:
113
114```bash
115xstream-engine/target/universal/stage/bin/xstream-runner \
116  examples/operators/galaxy/engine.yaml examples/operators/galaxy/job-sam.yaml
117xstream-engine/target/universal/stage/bin/xstream-runner \
118  examples/operators/galaxy/engine.yaml examples/operators/galaxy/job-tabular-to-fasta.yaml
119```
120
121预期区间输出:
122
123```text
124#chrom	start	end	strand	read_name
125chr1	9	13	+	read1
126chr1	19	27	-	read2
127```
128
129`galaxy_tabular_to_fasta` 的列号从 1 开始,使用 `1,2` 这样的整数列表,不采用文本列工具的 `c1,c2` 语法。其示例读取 `data/sequence-table.tsv`。第一个标题字段开头的 `>` 会被去掉;缺少选定列时跳过该行,与上游一致。它不检查序列字符是否属于特定字母表。
130
131SAM 工具要求至少 11 个字段和 16 位标志值。与上游筛选工具一致,省略注释和 SAM 头部,因此输出为比对数据行,不是保留完整头部的 SAM 文档。要求置位和排除的掩码不得重叠。区间工具跳过未映射标志以及 `*` 参考序列,要求正数位置和完整有效的 CIGAR,并检查坐标溢出。`M`、`D`、`N`、`=`、`X` 消耗参考序列位置,`I`、`S`、`H`、`P` 不消耗;这修正了上游脚本计入 `P`、遗漏 `=`/`X` 的问题。两个原始区间预期按此修正规则调整,独立边界测试覆盖扩展 CIGAR 与 padding。`print_all: true` 在染色体、起点、终点和链方向之后附加原始 SAM 行。输入行最多 1 MiB 字符,输出行最多 2 MiB 字符;逐行流式处理,并响应取消。