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 import Database
>>>
>>> db = Database.Database()
>>> db.construct_database()
>>>

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 import Database
>>>
>>> #Load the database
>>> db = Database.load()
>>>
>>> db.add_structure(id='0000', allele_type=['HLA-A*02:01'],
                      peptide = 'AAALLLAAA', MHC_class = 'I',
                      anchors = [],
                      pdb_path = './PDBs/pMHCI/0000.pdb', pdb = False)

Database

class PANDORA.Database.Database.Database[source]

Bases: object

set_reverse(reverse)[source]
download_data(self, data_dir=PANDORA.PANDORA_data + '/database', download=True)[source]

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

clean_MHCI_file(pdb_id, data_dir, remove_biopython_object)[source]

Clean all MHCI structures

clean_MHCII_file(pdb_id, data_dir, remove_biopython_object)[source]

Clean all MHCII structures. Returns a list of bad PDBs

update_ref_sequences()[source]

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=PANDORA.PANDORA_data + '/database/PANDORA_database.pkl', data_dir=PANDORA.PANDORA_data, MHCI=True, MHCII=True, download=True, update_ref_sequences=True, remove_biopython_objects=True, n_jobs=1)[source]

Construct the database. Download, clean and add all structures

Parameters:

  • save (str/bool) – Filename of database pkl object. If False, does not save the database pkl. If a path is provided, saved the database .pkl to that path. Defaults to PANDORA.PANDORA_data + ‘/default/PANDORA_database.pkl’.

  • 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

  • remove_biopython_objects (bool) – If True, removes the biopython pdb objects from the template objects to make the database considerably lighter. Switch to False only if the biopython objects are necessary. Defaults to True.

  • n_jobs (int) – number of parallel processes to use. Set to -1 to use all the available cores. Defaults to 1.

Returns: Database object

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

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

write_db_into_fasta(outfile)[source]

Writes structure db into a fasta file (to be later used to build a blast database)

Parameters:

outfile (str) – output file path.

Returns:

None.

construct_blast_db(infile, outpath, db_name)[source]

Construc blast database for seq based template selection

Parameters:

  • outpath (str, optional) – Data dir folder. Defaults to PANDORA.PANDORA_data.

  • db_name (str, optional) – Name of the db folder and fasta file. Defaults to ‘MHC_blast_db’.

Returns:

None.

construct_both_blast_db(data_dir=PANDORA.PANDORA_data)[source]
remove_structure(id='')[source]

Removes a structure (by id) from the database

Parameters:

id – (str) PDB ID

save(fn=PANDORA.PANDORA_data + '/database/PANDORA_database.pkl')[source]

Save the database as a pickle file

Parameters:

fn – (str) pathname of file

PANDORA.Database.Database.load(file_name=PANDORA.PANDORA_data + '/database/PANDORA_database.pkl')[source]

Loads a pre-generated database

Parameters:

file_name (str) – Dabase file name/path. Defaults to PANDORA.PANDORA_data + ‘/database/PANDORA_database.pkl’.

Returns:

Database object.

Return type:

Database.Database

Example

>>> db = Database.load()
PANDORA.Database.Database.create_db_folders(db_path=None)[source]

Generates the database folders AND the config.json file if absent

Parameters:

db_path (str, optional) – Path to the database to generate. If None, it will look for a path provided in the config.json file. Otherwise it will write or overrite the config.json file with the provided path. Defaults to None.

Raises:

Exception – _description_

PANDORA.Database.Database.fetch_database(db_out_path, db_url='https://zenodo.org/records/6373630')[source]

Downloads the pre-generated database from zenodo.

Parameters:

  • db_out_path (str) – Path to the database to be downloaded, should be pointing at a “PANDORA_databases” folder.

  • db_url (str, optional) – URL to the zenodo database. Defaults to ‘https://zenodo.org/records/6373630’.

Raises:

Exception – If the PANDORA_database.pkl file is not found in the destination folder, it raises an exception.

PANDORA.Database.Database.install_database(db_path='~/PANDORA_databases/default')[source]

Wrapper to create the database folders and fetch the zenodo database.

Parameters:

db_path (str, optional) – Path where to download the database. Defaults to ‘~/PANDORA_databases/default’.

Database_functions

PANDORA.Database.Database_functions.fresh_parse_dirs()[source]

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)[source]

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)[source]

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)[source]
Takes as input an IMGT preprocessed PDB file of p:MHC I.

Returns a dictionary containing alleles and relative 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)[source]
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)[source]

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)[source]

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)[source]

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)[source]

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'])[source]

Replace chain names by another chain name in a bio.pdb object Be advised: some text editors might not read the characted in intermediate_chains. This will not affect this function.

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)[source]

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)[source]

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, pdb_id, IMGT_link='https://www.imgt.org/3Dstructure-DB/cgi/details.cgi?pdbcode=XXXX&Part=File')[source]

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

Returns:

PANDORA.Database.Database_functions.unzip_pdb(ID, indir, outdir)[source]

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=7, max_len=25)[source]

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)[source]

Removes all chains that are not specified to be kept

Parameters:

  • pdb – Bio.PDB object

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

Returns: Bio.PDB object

PANDORA.Database.Database_functions.remove_duplicated_chains(pdb)[source]
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)[source]

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)[source]

Find the MHCI chains

Parameters:

pdb – Bio.PDB object

Returns: list of chains

PANDORA.Database.Database_functions.seqs_from_pdb(pdb_file, MHC_chains)[source]

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')[source]
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, mhc_class)[source]

Tests parsed pMHC structures: chain numbering, naming and length

Parameters:

  • pdb – Bio.PDB object

  • mhc_class (str) – MHC class of the complex

Returns: Bool

PANDORA.Database.Database_functions.check_non_canonical_res(chain)[source]

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, mhc_class='I')[source]
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

  • mhc_class (str) – MHC class

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

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

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)[source]
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)[source]

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)[source]

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)[source]
Checks if the peptide chain is the last chain, in the pdb, if not reoder them so the MHC 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)[source]
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)[source]

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

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)[source]

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)[source]

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', keep_bad=False, custom_map={'MSE': 'M'}, remove_biopython_object=True)[source]

Clean one MHCI pdb file downloaded from IMGT

Args: pdb_id (str): id of pdb file indir (str): path of the input dir (where the .gz files are) outdir (str): path of the output dir (where the unzipped .pdb files go) bad_dir (str): path of the output dir (where the unsuitable .pdb files go) keep_bad (str): Keep the unsuitable pdb files in the bad_dir. If False, it will remove the files instead of moving them. Defaults to False. custom_map (dict): custom map for 3-to-1 letter aa name translation.

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', keep_bad=False, custom_map={'MSE': 'M'}, remove_biopython_object=True)[source]

Clean one MHCII pdb file downloaded from IMGT

Parameters:

  • pdb_id (str) – id of pdb file

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

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

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

  • keep_bad (str) – Keep the unsuitable pdb files in the bad_dir. If False, it will remove the files instead of moving them. Defaults to False.

  • custom_map (dict) – custom map for 3-to-1 letter aa name translation.

Returns: Template object

PANDORA.Database.Database_functions.get_sequence_for_fasta(template, MHC_class, chain)[source]
PANDORA.Database.Database_functions.generate_mhcseq_database(data_dir=PANDORA.PANDORA_data, HLA_out='HLA_cleaned.fasta', nonHLA_out='MHC_cleaned.fasta')[source]

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

Parameters:

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

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

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

Returns:

None.

PANDORA.Database.Database_functions.generate_hla_database(data_dir, HLA_out='HLA_cleaned.fasta')[source]

Downloads and parse HLA sequences

Parameters:

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

Returns:

None.

PANDORA.Database.Database_functions.generate_nonhla_database(data_dir, nonHLA_out='MHC_cleaned.fasta')[source]

Downloads and parse non human MHC sequences

Parameters:

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

Returns:

None.