Common Classes & Functions — immunedb.common

Configuration — immunedb.common.config

The immunedb.common.config module provides methods to initialize a connection to a new or existing database.

Most programs using ImmuneDB will start with code similar to:

import immunedb.common.config as config
parser = config.get_base_arg_parser('Some description of the program')
# ... add any additional arguments to the parser ...
args = parser.parse_args()

session = config.init_db(args.db_config)

This takes the first two command line arguments as the master and data configuration file paths and initializes the database. Of course one can also manually specify the paths with simply:

import immunedb.common.config as config
session = config.init_db('path/to/config')

To avoid using a configuration file, the from_dict argument can be set to True, and the configurations will be read from dictionaries:

import immunedb.common.config as config
session = config.init_db({
    'host': '...',
    'database': '...',
    'username': '...',
    'password': '...',

All will return a Session object which can be used to interact with the database.

immunedb.common.config.get_base_arg_parser(desc='', multiproc=True, **kwargs)

Gets a base argument parser which requires database configuration.

Parameters:desc (str) – The description provided by the argument parser
Returns:The argument parser object
Return type:ArgumentParser
immunedb.common.config.init_db(database_config, drop_all=False, as_maker=False, create=True)

Initializes a session with the specified database.

  • database_config (str) – If from_dict is False, the path to data database config file, otherwise a database config dictionary
  • as_maker (bool) – If True, the returned object will be a session maker rather than an session

A session or, if as_maker is set, a session_maker

Mutations — immunedb.common.mutations

Mutation statistics are calculated with the Mutations class. This is generally done for clones only but can be done with any set of equal-length sequences for which a base (germline) sequence can be specified.

class immunedb.common.mutations.ContextualMutations(regions)

Calculates the mutations of a set of sequences within a given context.

Parameters:regions (list) – The gene region positions relative to the input sequence gapping.
add_mutation(seq, cdr3_num_nts, mutation, from_aa, intermediate_seq_aa, final_seq_aa, copy_number)

Adds a mutation to the the aggregate mutation list.

  • seq (str) – The sequence with the mutation
  • cdr3_num_nts (int) – The number of bases in the CDR3
  • mutation (tuple) – The mutation in (position, from_nt, to_nt, type) form.
  • from_aa (char) – The germline amino acid
  • intermediate_seq_aa (char) – The amino acid in the sequence if only the point mutation occurred
  • final_seq_aa (char) – The final mutated amino acid
  • copy_number (int) – The number of times this sequence appeared
immunedb.common.mutations.threshold_mutations(all_muts, min_required_seqs)

Removes mutations that occur in less than min_required_seqs

  • all_muts (dict) – A mutation dictionary as generated by ContextualMutations
  • min_required_seqs (int) – The minimum number of sequences in which a mutation must occur to be in the thresholded mutations
Returns dict:

A new mutation dictionary with infrequent mutations removed