CSV 合并工具 (habit merge-csv)

概述

habit merge-csv 工具用于横向合并多个 CSV 或 Excel 文件，基于公共索引列进行连接。

主要用途：

• 合并不同来源的特征数据

• 整合多个时间点的测量结果

• 合并不同模态的数据

与纵向分析工具的区别：

• merge-csv: 横向合并（增加列），用于整合不同来源的数据

• test-retest: 评估重测一致性，用于质量控制

使用方法

基本用法

habit merge-csv file1.csv file2.csv file3.csv -o merged.csv

指定索引列

habit merge-csv file1.csv file2.csv -o merged.csv --index-cols PatientID

指定不同索引列

habit merge-csv file1.csv file2.csv -o merged.csv --index-cols ID1 ID2

使用 Excel 文件

habit merge-csv file1.xlsx file2.xlsx -o merged.csv

指定分隔符

habit merge-csv file1.csv file2.csv -o merged.csv --separator ";"

参数说明

• input_files: 要合并的输入文件 (至少2个)

• -o, --output: 输出文件路径 (必需)

• --index-cols: 索引列名 - 不指定：使用第一个文件的第一个列 - 单个列名：所有文件使用相同列名 - 多个列名：按顺序匹配到每个文件

• --separator: CSV 分隔符 (默认逗号)

• --encoding: 文件编码 (默认 UTF-8)

• --join-type: 连接类型 - inner: 只保留所有文件中都有索引的行 - outer: 保留所有索引 (默认)

使用场景示例

场景1：合并两个扫描的特征

habit merge-csv ./data/scan1_features.csv ./data/scan2_features.csv -o ./data/merged_features.csv --index-cols PatientID

场景2：合并临床数据和影像特征

habit merge-csv ./data/clinical.csv ./data/radiomics.csv -o ./data/combined.csv --index-cols SubjectID

场景3：合并多个时间点数据

habit merge-csv baseline.csv month3.csv month6.csv month12.csv -o longitudinal.csv --index-cols PatientID

场景4：处理不同列名的情况

habit merge-csv file1.csv file2.csv -o merged.csv --index-cols ID ID_number

输出文件说明

合并后的文件包含：

• 索引列 (PatientID 或指定的列名)

• 第一个文件的所有其他列 (加上前缀区分来源)

• 第二个文件的所有其他列 (加上前缀区分来源)

• ...

输入文件1 (scan1.csv):

PatientID	Feature_A	Feature_B
sub-001	12.5	0.45
sub-002	14.2	0.67

输入文件2 (scan2.csv):

PatientID	Feature_C	Feature_D
sub-001	102.3	0.85
sub-002	98.1	0.92

输出文件 (merged.csv):

PatientID	scan1_Feature_A	scan1_Feature_B	scan2_Feature_C	scan2_Feature_D
sub-001	12.5	0.45	102.3	0.85
sub-002	14.2	0.67	98.1	0.92

注意事项

1. 索引列必须唯一: 每个文件中索引列不能有重复值

2. 索引列数据类型: 确保所有文件的索引列数据类型一致

3. 内存限制: 大文件可能需要较长时间合并

4. 列名冲突: 同名列会自动添加前缀区分

5. 编码问题: 确保所有文件使用相同编码

常见问题

Q: 合并后某些行丢失？

A: 默认使用 inner join，只有所有文件中都存在的索引才会保留。使用 --join-type outer 保留所有行。

Q: 合并后列名重复？

A: 工具会自动为不同来源的同名列添加前缀区分。

Q: 可以合并多少个文件？

A: 没有硬性限制，但建议不超过 20 个文件，以免内存不足。