Database Generation

This module contains all the tools to compute the template structure and reference sequence databases. The main class used for the data generation is PANDORA.Database.Database. Through this class you can specify the type of structures you want to download (MHCI and/or II).

Basic building Example:

>>> from PANDORA.Database import Database
>>>
>>> db = Database.Database()
>>> db.construct_database(save='./database/full_db.pkl', download=True)
>>>

A database can be easily loaded and edited. Custom structures (i.e. not coming from IMGT) can be also added to the database by using Database.add_structure() function. To do so, you will need to read your structure into a Biopython structure object:

>>> from PANDORA.Database import Database
>>>
>>> #Load the database
>>> db = Database.load('./database/full_db.pkl')
>>>
>>> db.add_structure(id='0000', allele_type=['HLA-A*02:01'],
                      peptide = 'AAALLLAAA', MHC_class = 'I',
                      chain_seq = [], anchors = [],
                      pdb_path = './PDBs/pMHCI/0000.pdb', pdb = False)

Database

class PANDORA.Database.Database.Database

Bases: object

download_data(self, data_dir=PANDORA.PANDORA_data, download=True)

Download all MHC structures and get a two lists that contains all MHCI and MHCII IDs respectively

update_ref_sequences()

Downloads and parse HLA and other MHC sequences to compile reference fastas. Returns a dictionary that can be used to select the desired reference sequence

construct_database(self, save, data_dir=PANDORA.PANDORA_data, MHCI=True, MHCII=True, download=True, update_ref_sequences=True)

Construct the database. Download, clean and add all structures

Parameters

• save (str/bool) – Filename of database, can be False if you don’t want to save the database

• data_dir (str) – Path of data directory. Defaults to PANDORA.PANDORA_data.

• MHCI (bool) – Parse data for MHCI. Defaults to True.

• MHCII (bool) – Parse data for MHCII. Defaults to True.

• download (bool) – If True, download the structures data from IMGT. Defaults to True.

• update_ref_sequences (bool) – If True, downloads and parse reference sequence strcutres. Defaults to True

Returns: Database object

add_structure(id, allele_type, peptide='', MHC_class='I', chain_seq=[], anchors=[], pdb_path=False, pdb=False)

Add a single structure to the database

Parameters

• id – (str) PDB identifier

• allele_type – (lst) list of MHC alleles (or allele)

• peptide – (str) peptide sequence

• MHC_class – (str) either ‘I’ or ‘II’ denoting MHC class I and MHC class II respectively

• chain_seq – (lst) list of chain sequence(s) for the M and N (Alpha and Beta) chain respectively

• anchors – (lst) list of integers specifying which residue(s) of the peptide should be fixed as an anchor during the modelling. MHC class I typically has 2 anchors, while MHC class II typically has 4.

• pdb_path – (str) path to pdb file

• pdb – (Bio.PDB) Biopython PBD object

remove_structure(id='')

Removes a structure (by id) from the database

Parameters

id – (str) PDB ID

repath(new_folder_path, save)

Necessary if the absolut path to the templates structures is different from the one used while generating the database. It changes the template.pdb_path for each template object in the database and returns the modified database.

Parameters

• new_folder_path (str) – New path to the ‘PDBs’ directory contaning template structures.

• save (str/bool) – If False, doesn’t save the modified database. If str, saves the modified database to the specified file path.’

Returns

None.

Example

>>> MyDatabase.repath('/home/Users/MyUserName/PANDORA/PDBs/', './MyHome_Database.pkl')

save(fn='db.pkl')

Save the database as a pickle file

Parameters

fn – (str) pathname of file

PANDORA.Database.Database.load(file_name)

Loads a pre-generated database

Parameters

file_name (str) – Dabase file name/path.

Returns

Database object.

Return type

Database.Database

Example

>>> db = Database.load('MyDatabase.pkl')

Database_functions

PANDORA.Database.Database_functions.fresh_parse_dirs()

Removes all parsed files + log files for a fresh start. Used for development.

PANDORA.Database.Database_functions.download_unzip_imgt_structures(data_dir=PANDORA.PANDORA_data, del_inn_files=True, del_kabat_files=True)

Downloads the complete structural dataset

Parameters

• data_dir – (string) path of data directory

• del_inn_files – (bool) if True (default) deletes all inn files

• del_kabat_files – (bool) if True (default) deletes all kabat files

PANDORA.Database.Database_functions.download_ids_imgt(ReceptorType, data_dir=PANDORA.PANDORA_data, out_tsv=False)

Queries IMGT with the ReceptorType for PDBs.

Parameters

• ReceptorType – (string) Receptor query for IMGT: ‘MH1’ or ‘MH2’

• data_dir – (bool/string) if not False, produces a tsv file names as out_tsv

• out_tsv – (bool/string) if not False, produces a tsv file names as out_tsv

Returns: (list) Returns the list of IDs provided by IMGT.

PANDORA.Database.Database_functions.get_chainid_alleles_MHCI(pdbf)

Takes as input an IMGT preprocessed PDB file of p:MHC I.

Returns a dictionary containing alleles andrelative identity scores for each G-domain in the given pdb from the REMARK.

Parameters

pdbf – (string) path to IMGT pdb file

Returns: (dict) MHCI alleles

PANDORA.Database.Database_functions.get_chainid_alleles_MHCII(pdbf)

Takes as input an IMGT preprocessed PDB file of p:MHC II.

Returns a dictionary containing alleles andrelative identity scores for each G-domain in the given pdb from the REMARK.

Parameters

pdbf – (string) path to IMGT pdb file

Returns: (dict) MHCI alleles

PANDORA.Database.Database_functions.format_alleles_MHCI(alleles, MHC_chains)

Format alleles to a list

Parameters

alleles – (dict): output from get_chainid_alleles_MHCI()

Returns: (lst): list of allele types

PANDORA.Database.Database_functions.format_alleles_MHCII(alleles, MHC_chains)

Format alleles to a list

Parameters

alleles – (dict): output from get_chainid_alleles_MHCI()

Returns: (lst, lst): tuple of lists of allele types for the alpha and beta chain respectively

PANDORA.Database.Database_functions.get_resolution(pdbf)

Returns the resolution in Angstrom from the given pdb

Parameters

pdbf (str) – path to the pdb file

Returns

resolution of the model, in Angstrom

Return type

resolution (float)

PANDORA.Database.Database_functions.change_modified_res(pdb_file, change_SEP=True, change_F2F=True, change_CSO=True, change_CIR=True)

Change modified residues into regular residues

Parameters

pdb_file – (str): Path to pdb file

Returns: (bool/str): If nothing was changed, return False, else, resturn a message with the changes.

PANDORA.Database.Database_functions.replace_chain_names(chains, pdb, replacement_chains=['M', 'N', 'P'])

Replace chain names by another chain name in a bio.pdb object

Parameters

• chains – (list) chains to replace

• pdb – bio.pdb object

• replacement_chains – (list) replacement names (in order of chains to replace)

Returns: bio.pdb object with changed chain names

PANDORA.Database.Database_functions.remember_IMGT_numbering(pdb_obj, forget=False)

Puts the IMGT numbering in the pdb residue id (’ ‘, 1045, ‘A’) –> (’ ‘, 1045, ‘1045A’)

Parameters

• pdb – (Bio.PDB): Bio.PDB object

• forget – (bool): if True, the IMGT numbering will be cleared. This is needed for writing a pdb file

Returns: (Bio.PDB): Bio.PDB object with IMGT numbering in the residiue id.

PANDORA.Database.Database_functions.renumber(pdb)

Renumbers the pdb. Each chain starts at 1

Parameters

pdb – Bio.PDb object

Returns: Bio.PDb object with renumbered residues

PANDORA.Database.Database_functions.write_pdb(pdb, out_path, get_header_from=False)

Write bio.pdb object to file, can use the header of the original pdb (bio.pdb cant remember file headers)

Parameters

• pdb – bio.pdb object

• out_path – (string) output path of pdb file

• get_header_from – (string) get the header from another pdb file

Returns:

PANDORA.Database.Database_functions.unzip_pdb(ID, indir, outdir)

Unzips a pdb, move it to another directory and return the filepath

Parameters

• ID – (string) pdb id

• indir – (string) location of pdb.gz files

• outdir – (string) output location

Returns: (string) path to unzipped pdb file

PANDORA.Database.Database_functions.find_peptide_chain(pdb, min_len=6, max_len=26)

Find the pdb chain that is most likely the peptide based on its size

Parameters

• pdb – (Bio.PDB): Bio.PDB object

• min_len – (int): minimal peptide length to consider

• max_len – (int): maximal peptide length to consider

Returns: (str): Most likely chain that is the peptide

PANDORA.Database.Database_functions.remove_irregular_chains(pdb, chains_to_keep)

Removes all chains that you don’t specify to keep

Parameters

• pdb – Bio.PDB object

• chains_to_keep – list of strings: [‘A’, ‘C’]

Returns: Bio.PDB object

PANDORA.Database.Database_functions.remove_duplicated_chains(pdb)

In very rare cases, PDBParser duplicates the same chain multiple times. If that happens, this function removes

all duplicates

Parameters

pdb – Bio.PDB object

Returns: Bio.PDB object

PANDORA.Database.Database_functions.find_chains_MHCI(pdb, pept_chain, all_MHC_chains)

Find the MHCI chains

Parameters

• pdb (Bio.PDB.PDBParser) – Bio.PDB object of a peptide-MHCI structure

• pept_chain (str) – chain ID of the peptide

• all_MHC_chains (list) – list of all MHC alpha chains in the pdb file

Returns: list of chains

PANDORA.Database.Database_functions.find_chains_MHCII(pdb, pept_chain)

Find the MHCI chains

Parameters

pdb – Bio.PDB object

Returns: list of chains

PANDORA.Database.Database_functions.seqs_from_pdb(pdb_file, MHC_chains)

Use SeqIO to get the amino acid sequences from a PDB file.

Parameters

• pdb_file – (string) path to PDB file

• MHC_chains – (list) names of the M (, N) and P chains

Returns: (list) AA sequence for the M (, N) and P chain respectively

PANDORA.Database.Database_functions.check_missing_pept_residues(pdb, chain='P')

Checks for missing residues in a chain by calculating N_{res_i-1}-Ca_{res_i} distance. This distance never

exceeds ~2.5, so if the N_{res_i-1}-Ca_{res_i} distance > 3 –> residues are missing.

Parameters

• pdb – Bio.PDB object.

• chain – (string) name of the chain that is tested for missing residues.

Returns: bool. True if residues are missing from the chain

PANDORA.Database.Database_functions.check_pMHC(pdb)

Tests parsed pMHC structures: chain numbering, naming and length

Parameters

pdb – Bio.PDB object

Returns: Bool

PANDORA.Database.Database_functions.check_non_canonical_res(chain)

Check if there are non-canonical residues in the chain of a Bio.PDB chain object

Parameters

chain – Bio.PDB chain object

Returns: bool, true if there are non canonical residues in the chain

PANDORA.Database.Database_functions.check_hetatoms_in_binding_groove(pdb, MHC_chains)

Checks if there are heteroatoms in the binding groove between MHC and the peptide. Heteroatoms near the

peptide on the outside of the binding groove are allowed. This takes ~ 0.008 seconds.

Parameters

• pdb – Bio.PDB object

• MHC_chains – (list) list of MHC chains for the M and P chains respectively

Returns: bool, true if there are problematic heteroatoms in the binding groove

PANDORA.Database.Database_functions.log(ID, error, logfile, verbose=True)

Keeps track of what goes wrong while parsing

Parameters

• ID – (string) PDB ID

• error – (string) error to append to log file

• logfile – (string) path to logfile

• verbose – (Bool) print error?

PANDORA.Database.Database_functions.find_merged_pept_chains(pdb_file)

Checks if the peptide is merged to another chain (have the same chain ID). If True, return a dict telling

wich chain the peptide is merged to and which residues belong to the peptide. It takes this info from the header

Parameters

pdb_file – (str): Path to pdb file

Returns: (dict): {chain_ID:(1:n)}

PANDORA.Database.Database_functions.un_merge_pept_chain(pdb, pdb_file)

Cut a peptide from a MHC chain if they are merged into the same chain

Parameters

• pdb – (Bio.PDB): Bio.PDB pdb object

• pdb_file – (str): Path to PDB file

Returns: (Bio.PDB): Bio.PDB pdb object with the peptide as a separate chain

PANDORA.Database.Database_functions.extract_residues(res_lst, chain_id, pdb)

Extract residues from a pdb and put them in a new chain in the same pdb

Parameters

• res_lst – (lst): List of Bio.PDB <residue> objects (pdb.get_residues())

• chain_id – (str): name of chain were res_lst originates from

• pdb – (Bio.PDB): Bio.PDB object

Returns: (Bio.PDB): Bio.PDB object with the residues from res_lst in a new chain

PANDORA.Database.Database_functions.ensure_order(pdb, MHC_chains)

Checks if the peptide chain is the last chain, in the pdb, if not reoder them so the MCH chains come before the

peptide chain.

Parameters

• pdb – (Bio.PDB): Bio.PDB object containing the Alpha, (Beta for MHCII) and Peptide chain

• MHC_chains – (lst): List of the names of the chains in this order: M, N (only for MHCII) and P

Returns: (Bio.PDB): Bio.PBD object with the MHC chains first and the peptide chain last

PANDORA.Database.Database_functions.check_DM_chaperone(alleles)

Check if the DM chaperone is involved in this structure by checking the allele type.

MHC class II molecules require HLA-DM (H2‑DM in mice) to facilitate the exchange of the CLIP fragment. The involvement of this protein can influence the structure of MHCII

Parameters

alleles – (lst): list of allele types

Returns: (bool): True if there are HLA-DM (human) or H2-DM (mouse)

PANDORA.Database.Database_functions.find_pept_secondary_structure(pdb_file, pdb, pept_chain, MHC_chains)

Using the annotation in the IMGT PDB file, find secondary structures in the peptide

Parameters

• pdb_file – (str): Path to the pdb file

• pdb – (Bio.PDB): Bio.PDB object

• pept_chain – (str): Name of the peptide chain

• MHC_chains – (lst): List of the Alpha-chain(, Beta-chain) and Peptide-chain in this order.

Returns: (dct, str/bool): dictionairy with [sheet] or [helix] denoting the location of the structure in MODELLER

format, False if there are no B-sheets or A-helices, or a string with their location

PANDORA.Database.Database_functions.hardcode_cut_peptide(pdb_id, pdb)

Some structures were only cleanable by manually cutting the peptide from another chain.

Parameters

• pdb_id – (str): ID of PDB file

• pdb – (Bio.PDB): Bio.PDB object

Returns: (Bio.PDB): Bio.PDB object with the previously merged peptide in a separate chain

PANDORA.Database.Database_functions.check_clip_peptide(pdb_file)

Checks if the bound peptide is the clip peptide. If it is, this structure is not suitable for modelling.

Parameters

pdb_file – (str): path to pdb file

Returns: (bool)

PANDORA.Database.Database_functions.parse_pMHCI_pdb(pdb_id, indir=PANDORA.PANDORA_data + '/PDBs/IMGT_retrieved/IMGT3DFlatFiles', outdir=PANDORA.PANDORA_data + '/PDBs/pMHCI', bad_dir=PANDORA.PANDORA_data + '/PDBs/Bad/pMHCI')

Clean all MHCI pdb files that have been downloaded from IMGT

Parameters

• pdb_id – (string) id of pdb file

• indir – (string) path of the input dir (where the .gz files are)

• outdir – (string) path of the output dir (where the unzipped .pdb files go)

• bad_dir – (string) path of the output dir (where the unsuitable .pdb files go)

Returns: Template object

PANDORA.Database.Database_functions.parse_pMHCII_pdb(pdb_id, indir=PANDORA.PANDORA_data + '/PDBs/IMGT_retrieved/IMGT3DFlatFiles', outdir=PANDORA.PANDORA_data + '/PDBs/pMHCII', bad_dir=PANDORA.PANDORA_data + '/PDBs/Bad/pMHCII')

Clean all MHCII pdb files that have been downloaded from IMGT

Parameters

• pdb_id – (string) id of pdb file

• indir – (string) path of the input dir (where the .gz files are)

• outdir – (string) path of the output dir (where the unzipped .pdb files go)

• bad_dir – (string) path of the output dir (where the unsuitable .pdb files go)

Returns: Template object

PANDORA.Database.Database_functions.generate_mhcseq_database(data_dir=PANDORA.PANDORA_data + '/csv_pkl_files/', HLA_out='Human_MHC_data.fasta', nonHLA_out='NonHuman_MHC_data.fasta')

Downloads and parse HLA and other MHC sequences to compile reference fastas

Parameters

• data_dir (str, optional) – Data directory. Defaults to PANDORA.PANDORA_data/csv_pkl_files/.

• HLA_out (str, optional) – Output file for HLA sequences. Defaults to ‘Human_MHC_data.fasta’.

• nonHLA_out (str, optional) – Output file for non human MHCs. Defaults to ‘NonHuman_MHC_data.fasta’.

Returns

None.

PANDORA.Database.Database_functions.generate_hla_database(HLA_out='Human_MHC_data.fasta')

Downloads and parse HLA sequences

Parameters

HLA_out (str, optional) – Output file for HLA sequences. Defaults to ‘Human_MHC_data.fasta’.

Returns

None.

PANDORA.Database.Database_functions.generate_nonhla_database(nonHLA_out='NonHuman_MHC_data.fasta')

Downloads and parse non human MHC sequences

Parameters

nonHLA_out (str, optional) – Output file for non human MHCs. Defaults to ‘NonHuman_MHC_data.fasta’.

Returns

None.