API Reference

Inferface

airr.read_rearrangement(filename, validate=False, debug=False)

Open an iterator to read an AIRR rearrangements file

Parameters:
  • file (str) – path to the input file.
  • validate (bool) – whether to validate data as it is read, raising a ValidationError exception in the event of an error.
  • debug (bool) – debug flag. If True print debugging information to standard error.
Returns:

iterable reader class.
Return type:

airr.io.RearrangementReader
airr.create_rearrangement(filename, fields=None, debug=False)

Create an empty AIRR rearrangements file writer

Parameters:
  • filename (str) – output file path.
  • fields (list) – additional non-required fields to add to the output.
  • debug (bool) – debug flag. If True print debugging information to standard error.
Returns:

open writer class.
Return type:

airr.io.RearrangementWriter
airr.derive_rearrangement(out_filename, in_filename, fields=None, debug=False)

Create an empty AIRR rearrangements file with fields derived from an existing file

Parameters:
  • out_filename (str) – output file path.
  • in_filename (str) – existing file to derive fields from.
  • fields (list) – additional non-required fields to add to the output.
  • debug (bool) – debug flag. If True print debugging information to standard error.
Returns:

open writer class.
Return type:

airr.io.RearrangementWriter
airr.load_rearrangement(filename, validate=False, debug=False)

Load the contents of an AIRR rearrangements file into a data frame

Parameters:
  • filename (str) – input file path.
  • validate (bool) – whether to validate data as it is read, raising a ValidationError exception in the event of an error.
  • debug (bool) – debug flag. If True print debugging information to standard error.
Returns:

Rearrangement records as rows of a data frame.
Return type:

pandas.DataFrame
airr.dump_rearrangement(dataframe, filename, debug=False)

Write the contents of a data frame to an AIRR rearrangements file

Parameters:
  • dataframe (pandas.DataFrame) – data frame of rearrangement data.
  • filename (str) – output file path.
  • debug (bool) – debug flag. If True print debugging information to standard error.
Returns:

True if the file is written without error.
Return type:

bool
airr.merge_rearrangement(out_filename, in_filenames, drop=False, debug=False)

Merge one or more AIRR rearrangements files

Parameters:
  • out_filename (str) – output file path.
  • in_filenames (list) – list of input files to merge.
  • drop (bool) – drop flag. If True then drop fields that do not exist in all input files, otherwise combine fields from all input files.
  • debug (bool) – debug flag. If True print debugging information to standard error.
Returns:

True if files were successfully merged, otherwise False.
Return type:

bool
airr.validate_rearrangement(filename, debug=False)

Validates one or more AIRR rearrangements files

Parameters:
  • filename (str) – path of the file to validate.
  • debug (bool) – debug flag. If True print debugging information to standard error.
Returns:

True if files passed validation, otherwise False.
Return type:

bool

Classes

class airr.io.RearrangementReader(handle, base=1, validate=False, debug=False)

Iterator for reading Rearrangement objects in TSV format

fields

field names in the input Rearrangement file.

Type:list
external_fields

list of fields in the input file that are not part of the Rearrangement definition.

Type:list
__init__(handle, base=1, validate=False, debug=False)

Initialization

Parameters:
  • handle (file) – file handle of the open Rearrangement file.
  • base (int) – one of 0 or 1 specifying the coordinate schema in the input file. If 1, then the file is assumed to contain 1-based closed intervals that will be converted to python style 0-based half-open intervals for known fields. If 0, then values will be unchanged.
  • validate (bool) – perform validation. If True then basic validation will be performed will reading the data. A ValidationError exception will be raised if an error is found.
  • debug (bool) – debug state. If True prints debug information.
Returns:

reader object.
Return type:

airr.io.RearrangementReader
__iter__()

Iterator initializer

Returns:airr.io.RearrangementReader
__next__()

Next method

Returns:parsed Rearrangement data.
Return type:dict
close()

Closes the Rearrangement file

next()

Next method

class airr.io.RearrangementWriter(handle, fields=None, base=1, debug=False)

Writer class for Rearrangement objects in TSV format

fields

field names in the output Rearrangement file.

Type:list
external_fields

list of fields in the output file that are not part of the Rearrangement definition.

Type:list
__init__(handle, fields=None, base=1, debug=False)

Initialization

Parameters:
  • handle (file) – file handle of the open Rearrangements file.
  • fields (list) – list of non-required fields to add. May include fields undefined by the schema.
  • base (int) – one of 0 or 1 specifying the coordinate schema in the output file. Data provided to the write is assumed to be in python style 0-based half-open intervals. If 1, then data will be converted to 1-based closed intervals for known fields before writing. If 0, then values will be unchanged.
  • debug (bool) – debug state. If True prints debug information.
Returns:

writer object.
Return type:

airr.io.RearrangementWriter
close()

Closes the Rearrangement file

write(row)

Write a row to the Rearrangement file

Parameters:row (dict) – row to write.
class airr.schema.Schema(definition)

AIRR schema definitions

properties

field definitions.

Type:collections.OrderedDict
info

schema info.

Type:collections.OrderedDict
required

list of mandatory fields.

Type:list
optional

list of non-required fields.

Type:list
false_values

accepted string values for False.

Type:list
true_values

accepted values for True.

Type:list
from_bool(value, validate=False)

Converts a boolean to a string

Parameters:
  • value (bool) – logical value.
  • validate (bool) – when True raise a ValidationError for an invalid value. Otherwise, set invalid values to None.
Returns:

conversion of True or False or ‘T’ or ‘F’.
Return type:

str
Raises:

airr.ValidationError – raised if value is invalid when validate is set True.
spec(field)

Get the properties for a field

Parameters:name (str) – field name.
Returns:definition for the field.
Return type:collections.OrderedDict
to_bool(value, validate=False)

Convert a string to a boolean

Parameters:
  • value (str) – logical value as a string.
  • validate (bool) – when True raise a ValidationError for an invalid value. Otherwise, set invalid values to None.
Returns:

conversion of the string to True or False.
Return type:

bool
Raises:

airr.ValidationError – raised if value is invalid when validate is set True.
to_float(value, validate=False)

Converts a string to a float

Parameters:
  • value (str) – float value as a string.
  • validate (bool) – when True raise a ValidationError for an invalid value. Otherwise, set invalid values to None.
Returns:

conversion of the string to a float.
Return type:

float
Raises:

airr.ValidationError – raised if value is invalid when validate is set True.
to_int(value, validate=False)

Converts a string to an integer

Parameters:
  • value (str) – integer value as a string.
  • validate (bool) – when True raise a ValidationError for an invalid value. Otherwise, set invalid values to None.
Returns:

conversion of the string to an integer.
Return type:

int
Raises:

airr.ValidationError – raised if value is invalid when validate is set True.
type(field)

Get the type for a field

Parameters:name (str) – field name.
Returns:the type definition for the field
Return type:str
validate_header(header)

Validate header against the schema

Parameters:header (list) – list of header fields.
Returns:True if a ValidationError exception is not raised.
Return type:bool
Raises:airr.ValidationError – raised if header fails validation.
validate_row(row)

Validate Rearrangements row data against schema

Parameters:row (dict) – dictionary containing a single record.
Returns:True if a ValidationError exception is not raised.
Return type:bool
Raises:airr.ValidationError – raised if row fails validation.

Schema

airr.schema.RearrangementSchema Schema object for the Rearrangement definition

AIRR schema definitions

airr.schema.properties

field definitions.

Type:collections.OrderedDict
airr.schema.info

schema info.

Type:collections.OrderedDict
airr.schema.required

list of mandatory fields.

Type:list
airr.schema.optional

list of non-required fields.

Type:list
airr.schema.false_values

accepted string values for False.

Type:list
airr.schema.true_values

accepted values for True.

Type:list
airr.schema.AlignmentSchema Schema object for the Alignment definition

AIRR schema definitions

airr.schema.properties

field definitions.

Type:collections.OrderedDict
airr.schema.info

schema info.

Type:collections.OrderedDict
airr.schema.required

list of mandatory fields.

Type:list
airr.schema.optional

list of non-required fields.

Type:list
airr.schema.false_values

accepted string values for False.

Type:list
airr.schema.true_values

accepted values for True.

Type:list