changeo.IO

File I/O and parsers

class changeo.IO.AIRRReader(handle)

Bases: changeo.IO.TSVReader

An iterator to read and parse AIRR formatted data.

class changeo.IO.AIRRWriter(handle, fields=['sequence_id', 'sequence', 'sequence_alignment', 'germline_alignment', 'rev_comp', 'productive', 'stop_codon', 'vj_in_frame', 'locus', 'v_call', 'd_call', 'j_call', 'junction', 'junction_length', 'junction_aa', 'np1_length', 'np2_length', 'v_sequence_start', 'v_sequence_end', 'v_germline_start', 'v_germline_end', 'd_sequence_start', 'd_sequence_end', 'd_germline_start', 'd_germline_end', 'j_sequence_start', 'j_sequence_end', 'j_germline_start', 'j_germline_end'])

Bases: changeo.IO.TSVWriter

Writes AIRR formatted data.

writeReceptor(records)

Writes a row from a Receptor object

Parameters

records – a changeo.Receptor object to write or iterable of such objects.

Returns

None

class changeo.IO.ChangeoReader(handle)

Bases: changeo.IO.TSVReader

An iterator to read and parse Change-O formatted data.

class changeo.IO.ChangeoWriter(handle, fields=['SEQUENCE_ID', 'SEQUENCE_INPUT', 'FUNCTIONAL', 'IN_FRAME', 'STOP', 'MUTATED_INVARIANT', 'INDELS', 'LOCUS', 'V_CALL', 'D_CALL', 'J_CALL', 'SEQUENCE_VDJ', 'SEQUENCE_IMGT', 'V_SEQ_START', 'V_SEQ_LENGTH', 'V_GERM_START_VDJ', 'V_GERM_LENGTH_VDJ', 'V_GERM_START_IMGT', 'V_GERM_LENGTH_IMGT', 'NP1_LENGTH', 'D_SEQ_START', 'D_SEQ_LENGTH', 'D_GERM_START', 'D_GERM_LENGTH', 'NP2_LENGTH', 'J_SEQ_START', 'J_SEQ_LENGTH', 'J_GERM_START', 'J_GERM_LENGTH', 'JUNCTION', 'JUNCTION_LENGTH', 'GERMLINE_IMGT'], header=True)

Bases: changeo.IO.TSVWriter

Writes Change-O formatted data.

writeReceptor(records)

Writes a row from a Receptor object

Parameters

records – a changeo.Receptor.Receptor object to write or an iterable of such objects.

Returns

None

class changeo.IO.IHMMuneReader(ihmmune, sequences, references, receptor=True)

Bases: object

An iterator to read and parse iHMMune-Align output files.

__iter__()

Iterator initializer.

Returns

changeo.IO.IHMMuneReader

__next__()

Next method.

Returns

parsed IMGT/HighV-QUEST result as an Receptor (receptor=True) or dictionary (receptor=False).

Return type

changeo.Receptor.Receptor

static customFields(scores=False, regions=False, cell=False, schema=None)

Returns non-standard Receptor attributes defined by the parser

Parameters
  • scores – if True include alignment scoring fields.

  • regions – if True include IMGT-gapped CDR and FWR region fields.

  • schema – schema class to pass field through for conversion. If None, return changeo.Receptor.Receptor attribute names.

Returns

list of field names.

Return type

list

ihmmune_fields = ['SEQUENCE_ID', 'V_CALL', 'D_CALL', 'J_CALL', 'V_SEQ', 'NP1_SEQ', 'D_SEQ', 'NP2_SEQ', 'J_SEQ', 'V_MUT', 'D_MUT', 'J_MUT', 'NX_COUNT', 'J_INFRAME', 'V_SEQ_START', 'STOP_COUNT', 'D_PROB', 'HMM_SCORE', 'RC', 'COMMON_MUT', 'COMMON_NX_COUNT', 'V_SEQ_START', 'V_SEQ_LENGTH', 'A_SCORE']
parseRecord(record)

Parses a single row from each IMTG file.

Parameters

record – dictionary containing one row of iHMMune-Align file.

Returns

database entry for the row.

Return type

dict

class changeo.IO.IMGTReader(summary, gapped, ntseq, junction, receptor=True)

Bases: object

An iterator to read and parse IMGT output files.

__iter__()

Iterator initializer.

Returns

changeo.IO.IMGTReader

__next__()

Next method.

Returns

parsed IMGT/HighV-QUEST result as an Receptor (receptor=True) or dictionary (receptor=False).

Return type

changeo.Receptor.Receptor

static customFields(scores=False, regions=False, junction=False, schema=None)

Returns non-standard fields defined by the parser

Parameters
  • scores – if True include alignment scoring fields.

  • regions – if True include IMGT-gapped CDR and FWR region fields.

  • junction – if True include detailed junction annotation fields.

  • schema – schema class to pass field through for conversion. If None, return changeo.Receptor.Receptor attribute names.

Returns

list of field names.

Return type

list

parseRecord(summary, gapped, ntseq, junction)

Parses a single row from each IMTG file.

Parameters
  • summary – dictionary containing one row of the ‘1_Summary’ file.

  • gapped – dictionary containing one row of the ‘2_IMGT-gapped-nt-sequences’ file.

  • ntseq – dictionary containing one row of the ‘3_Nt-sequences’ file.

  • junction – dictionary containing one row of the ‘6_Junction’ file.

Returns

database entry for the row.

Return type

dict

class changeo.IO.IgBLASTReader(igblast, sequences, references, asis_calls=False, regions='default', receptor=True)

Bases: object

An iterator to read and parse IgBLAST output files

__iter__()

Iterator initializer.

Returns

changeo.IO.IgBLASTReader

__next__()

Next method.

Returns

parsed IMGT/HighV-QUEST result as an Receptor (receptor=True) or dictionary (receptor=False).

Return type

changeo.Receptor.Receptor

static customFields(schema=None)

Returns non-standard fields defined by the parser

Parameters

schema – schema class to pass field through for conversion. If None, return changeo.Receptor.Receptor attribute names.

Returns

list of field names.

Return type

list

parseBlock(block)

Parses an IgBLAST result into separate sections

Parameters

block (iter) – an iterator from itertools.groupby containing a single IgBLAST result.

Returns

a parsed results block;

with the keys ‘query’ (sequence identifier as a string), ‘summary’ (dictionary of the alignment summary), ‘subregion’ (dictionary of IgBLAST CDR3 sequences), and ‘hits’ (VDJ hit table as a list of dictionaries). Returns None if the block has no data that can be parsed.

Return type

dict

parseSections(sections)

Parses an IgBLAST sections into a db dictionary

Parameters

sections – dictionary of parsed sections from parseBlock.

Returns

db entries.

Return type

dict

class changeo.IO.IgBLASTReaderAA(igblast, sequences, references, asis_calls=False, regions='default', receptor=True)

Bases: changeo.IO.IgBLASTReader

An iterator to read and parse IgBLAST amino acid alignment output files

static customFields(schema=None)

Returns non-standard fields defined by the parser

Parameters

schema – schema class to pass field through for conversion. If None, return changeo.Receptor.Receptor attribute names.

Returns

list of field names.

Return type

list

parseSections(sections)

Parses an IgBLAST sections into a db dictionary

Parameters

sections – dictionary of parsed sections from parseBlock.

Returns

db entries.

Return type

dict

class changeo.IO.TSVReader(handle)

Bases: object

Simple csv.DictReader wrapper to read format agnostic TSV files.

reader

reader object.

Type

iter

fields

field names.

Type

list

__iter__()

Iterator initializer

Returns

changeo.IO.TSVReader

__next__()

Next method

Returns

row as a dictionary of field:value pairs.

Return type

dist

class changeo.IO.TSVWriter(handle, fields, header=True)

Bases: object

Simple csv.DictWriter wrapper to write format agnostic TSV files.

writeDict(records)

Writes a row from a dictionary

Parameters

records – dictionary of row data or an iterable of such objects.

Returns

None

writeHeader()

Writes the header

Returns

None

changeo.IO.checkFields(attributes, header, schema=<class 'changeo.Receptor.AIRRSchema'>)

Checks that a file header contains a required set of Receptor attributes

Parameters
  • attributes (list) – list of Receptor attributes to check for.

  • header (list) – list of fields names in the file header.

  • schema (object) – schema object to convert field names to Receptor attributes.

Returns

True if all attributes mapping fields are found.

Return type

bool

Raises

LookupError

changeo.IO.countDbFile(file)

Counts the records in database files

Parameters

file – tab-delimited database file.

Returns

count of records in the database file.

Return type

int

changeo.IO.extractIMGT(imgt_output)

Extract necessary files from IMGT/HighV-QUEST results.

Parameters

imgt_output – zipped file or unzipped folder output by IMGT/HighV-QUEST.

Returns

(temporary directory handle, dictionary with names of extracted IMGT files).

Return type

tuple

changeo.IO.getDbFields(file, add=None, exclude=None, reader=<class 'changeo.IO.TSVReader'>)

Get field names from a db file

Parameters
  • file – db file to pull base fields from.

  • add – fields to append to the field set.

  • exclude – fields to exclude from the field set.

  • reader – reader class.

Returns

list of field names

Return type

list

changeo.IO.getFormatOperators(format)

Simple wrapper for fetching the set of operator classes for a data format

Parameters

format (str) – name of the data format.

Returns

a tuple with the reader class, writer class, and schema definition class.

Return type

tuple

changeo.IO.getOutputHandle(file, out_label=None, out_dir=None, out_name=None, out_type=None)

Opens an output file handle

Parameters
  • file – filename to base output file name on.

  • out_label – text to be inserted before the file extension; if None do not add a label.

  • out_type – the file extension of the output file; if None use input file extension.

  • out_dir – the output directory; if None use directory of input file

  • out_name – the short filename to use for the output file; if None use input file short name.

Returns

File handle

Return type

file

changeo.IO.getOutputName(file, out_label=None, out_dir=None, out_name=None, out_type=None)

Creates and output filename from an existing filename

Parameters
  • file – filename to base output file name on.

  • out_label – text to be inserted before the file extension; if None do not add a label.

  • out_type – the file extension of the output file; if None use input file extension.

  • out_dir – the output directory; if None use directory of input file

  • out_name – the short filename to use for the output file; if None use input file short name.

Returns

file name.

Return type

str

changeo.IO.readGermlines(references, asis=False)

Parses germline repositories

Parameters
  • references (list) – list of strings specifying directories and/or files from which to read germline records.

  • asis (bool) – if True use sequence ID as record name and do not parse headers for allele names.

Returns

Dictionary of germlines in the form {allele: sequence}.

Return type

dict

changeo.IO.splitName(file)

Extract the extension from a file name

Parameters

file (str) – file name.

Returns

tuple of the file directory, basename and extension.

Return type

tuple

changeo.IO.yamlDict(file)

Returns a dictionary from a yaml file

Parameters

file (str) – simple yaml file with rows in the form ‘argument: value’.

Returns

dictionary of key:value pairs in the file.

Return type

dict