airr 1.5.1

弃用通知

已经弃用了新的通用函数 load_airr_data、write_airr_data 和 validate_airr_data，以替换 load_repertoire、write_repertoire 和 validate_repertoire 函数。这些新函数与 Repertoire 元数据格式向后兼容，同时支持新的 AIRR 对象，如 GermlineSet、RepertoireGroup、GenotypeSet、Cell 和 Clone。这种新格式由 DataFile Schema 定义，它描述了一个包含 AIRR 数据模型表示的文件的标准化对象集。目前，AIRR 数据文件不完全支持 Rearrangement，因此用户应继续使用 AIRR TSV 文件及其特定函数。另外，已弃用 repertoire_template 函数，现在可以通过 Schema.template 方法在任意 AIRR Schema 上调用，以创建空白对象。

读取 AIRR 数据文件

airr 包包含用于读取和写入 AIRR 数据模型文件的函数。文件格式为 YAML 或 JSON，该包在标准解析器之上提供了一个轻量级封装。文件需要 json、yaml 或 yml 文件扩展名，以便使用正确的解析器。所有 AIRR 对象一次加载到内存中，不提供流式接口。

import airr

# Load the AIRR data
data = airr.read_airr('input.airr.json')
# loop through the repertoires
for rep in data['Repertoire']:
    print(rep)

AIRR 对象，如 Repertoire、GermlineSet 等，为什么是列表形式而不是以标识符（例如，repertoire_id）为键的字典形式？这里有两大原因。首先，标识符可能尚未分配。一些系统可能允许输入 MiAIRR 元数据，但标识符稍后由另一个过程分配。没有标识符，数据就不能存储在字典中。其次，列表允许数据具有默认的排序。如果你知道数据有一个唯一的标识符，则可以快速使用列表推导式创建字典对象。例如，对于 repertoires

rep_dict = { obj['repertoire_id'] : obj for obj in data['Repertoire'] }

另一个关于 germline sets 的示例

germline_dict = { obj['germline_set_id'] : obj for obj in data['GermlineSet'] }

写入 AIRR 数据文件

写入 AIRR 数据文件也是对标准 YAML 或 JSON 解析器的轻量级封装。可以将多个 AIRR 对象，如 Repertoire、GermlineSet 等，一起写入到同一文件中。在这个示例中，我们使用 airr 库的 template 方法创建一些空白 Repertoire 对象，并将它们写入文件。与读取函数一样，所有 repertoires 一次写入，没有流式接口。

import airr

# Create some blank repertoire objects in a list
data = { 'Repertoire': [] }
for i in range(5):
    data['Repertoire'].append(airr.schema.RepertoireSchema.template())

# Write the AIRR Data
airr.write_airr('output.airr.json', data)

读取 AIRR Rearrangement TSV 文件

airr 包包含用于以迭代器或 pandas 数据框形式读取和写入 AIRR Rearrangement TSV 文件的函数。使用方法简单，因为文件格式是典型的制表符分隔文件，但该包执行了一些额外的验证和类型转换，而不仅仅是使用标准的 CSV 读取器。

import airr

# Create an iteratable that returns a dictionary for each row
reader = airr.read_rearrangement('input.tsv')
for row in reader: print(row)

# Load the entire file into a pandas data frame
df = airr.load_rearrangement('input.tsv')

写入 AIRR Rearrangement TSV 文件

与读取操作类似，提供写函数以创建一个执行行输出或将整个 pandas 数据框内容写入文件的写入器类。再次，使用 airr 输出函数非常简单，只需执行一些类型转换和字段排序操作。

import airr

# Create a writer class for iterative row output
writer = airr.create_rearrangement('output.tsv')
for row in reader:  writer.write(row)

# Write an entire pandas data frame to a file
airr.dump_rearrangement(df, 'file.tsv')

默认情况下，create_rearrangement 只会写入输出文件中的 required 字段。可以通过提供包含附加字段名称的数组来在输出文件中包含额外的字段，使用 fields 参数。

# Specify additional fields in the output
fields = ['new_calc', 'another_field']
writer = airr.create_rearrangement('output.tsv', fields=fields)

一个常见的操作是读取一个 AIRR Rearrangement 文件，然后写入一个带有附加字段的 AIRR Rearrangement 文件，同时保留原始文件中的所有现有字段。derive_rearrangement 函数提供了这种功能。

import airr

# Read rearrangement data and write new file with additional fields
reader = airr.read_rearrangement('input.tsv')
fields = ['new_calc']
writer = airr.derive_rearrangement('output.tsv', 'input.tsv', fields=fields)
for row in reader:
    row['new_calc'] = 'a value'
    writer.write(row)

验证 AIRR 数据文件

airr包可以验证AIRR数据模型JSON/YAML文件和重排TSV文件，以确保它们包含所有必需的字段，并且字段类型与AIRR模式匹配。这可以通过使用airr-tools命令行程序或调用库中的验证函数来实现。

# Validate a rearrangement TSV file
airr-tools validate rearrangement -a input.tsv

# Validate an AIRR DataFile
airr-tools validate airr -a input.airr.json

组合库元数据和重排文件

目前，airr包没有跟踪哪些AIRR数据模型文件与哪些重排TSV文件相关联，尽管正在进行定义标准化清单的工作，因此用户需要自己处理这些关联。然而，在数据中，AIRR标识符字段，如repertoire_id，构成了AIRR数据模型中对象之间的链接。典型的用法是，一个程序将要对重排执行一些计算，并且它需要访问库元数据作为计算逻辑的一部分。此示例代码展示了执行此操作的基本框架，在这种情况下是进行性别特定的计算。

import airr

# Load AIRR data containing repertoires
data = airr.read_airr('input.airr.json')

# Put repertoires in dictionary keyed by repertoire_id
rep_dict = { obj['repertoire_id'] : obj for obj in data['Repertoire'] }

# Create an iteratable for rearrangement data
reader = airr.read_rearrangement('input.tsv')
for row in reader:
    # get repertoire metadata with this rearrangement
    rep = rep_dict[row['repertoire_id']]

    # check the gender
    if rep['subject']['sex'] == 'male':
        # do male specific computation
    elif rep['subject']['sex'] == 'female':
        # do female specific computation
    else:
        # do other specific computation