Image structure Image document-open


Reading structures from PDB files.


structure.read_pdb(file=None, dir=None, read_mol=None, set_mol_name=None, read_model=None, set_model_num=None, alt_loc=None, verbosity=1, merge=False)

Keyword arguments

file: The name of the PDB file.

dir: The directory where the file is located.

read_mol: If set, only the given molecule(s) will be read. The molecules are numbered consecutively from 1. If unset, then all molecules will be loaded. By providing a list of numbers such as [1, 2], multiple molecules will be read.

set_mol_name: Set the names of the read molecules. If unset, then the molecules will be automatically labelled based on the file name or other information. This can either be a single name or a list of names.

read_model: If set, only the given model number(s) from the PDB file will be read. Otherwise all models will be read. This can be a single number or list of numbers.

set_model_num: Set the model numbers of the loaded molecules. If unset, then the PDB model numbers will be preserved if they exist. This can be a single number or list of numbers.

alt_loc: The PDB ATOM record `Alternate location indicator' field value.

verbosity: The amount of information to print out. Set to zero to silence the user function, or one to see all messages.

merge: A flag which if set to True will try to merge the PDB structure into the currently loaded structures.


The reading of PDB files into relax is quite a flexible procedure allowing for both models, defined as an ensemble of the same molecule but with different atomic positions, and different molecules within the same model. One of more molecules can exist in one or more models. The flexibility allows PDB models to be converted into different molecules and different PDB files loaded as the same molecule but as different models.

In a PDB file, the models are specified by the MODEL PDB record. All the supported PDB readers in relax recognise this. The internal reader defines molecules using the TER PDB record. In both cases, the molecules will be numbered consecutively from 1.

Setting the molecule name allows the molecule within the PDB (within one model) to have a custom name. If not set, then the molecules will be named after the file name, with the molecule number appended if more than one exists.

Note that relax will complain if it cannot work out what to do.

This is able to handle uncompressed, bzip2 compressed files, or gzip compressed files automatically. The full file name including extension can be supplied, however, if the file cannot be found, this function will search for the file name with `.bz2' appended followed by the file name with `.gz' appended.

If a PDB file contains alternative atomic locations, then the alternate location indicator must be specified to allow one of the multiple coordinate sets to be selected.

Prompt examples

To load all structures from the PDB file `test.pdb' in the directory `~/pdb', including all models and all molecules, type one of:

relax> structure.read_pdb('test.pdb', '~/pdb')

relax> structure.read_pdb(file='test.pdb', dir='pdb')

To load the 10 th model from the file `test.pdb' and naming it `CaM', use one of:

relax> structure.read_pdb('test.pdb', read_model=10, set_mol_name='CaM')

relax> structure.read_pdb(file='test.pdb', read_model=10, set_mol_name='CaM')

To load models 1 and 5 from the file `test.pdb' as two different structures of the same model, type one of:

relax> structure.read_pdb('test.pdb', read_model=[1, 5], set_model_num=[1, 1])

relax> structure.read_pdb('test.pdb', set_mol_name=['CaM_1', 'CaM_2'], read_model=[1, 5], set_model_num=[1, 1])

To load the files `lactose_MCMM4_S1_1.pdb', `lactose_MCMM4_S1_2.pdb', `lactose_MCMM4_S1_3.pdb' and `lactose_MCMM4_S1_4.pdb' as models, type the following sequence of commands:

relax> structure.read_pdb('lactose_MCMM4_S1_1.pdb', set_mol_name='lactose_MCMM4_S1', set_model_num=1)

relax> structure.read_pdb('lactose_MCMM4_S1_2.pdb', set_mol_name='lactose_MCMM4_S1', set_model_num=2)

relax> structure.read_pdb('lactose_MCMM4_S1_3.pdb', set_mol_name='lactose_MCMM4_S1', set_model_num=3)

relax> structure.read_pdb('lactose_MCMM4_S1_4.pdb', set_mol_name='lactose_MCMM4_S1', set_model_num=4)

The relax user manual (PDF), created 2020-08-26.