FreeSASA  2.0
Open source SASA calculations
View on GitHub
Macros | Typedefs | Enumerations | Functions
Structure

Representation of macromolecular structures. More...

Macros

#define FREESASA_CONFLICTING_CLASSIFIERS   "conflicting-classifiers"
 String returned by freesasa_structure_classifier_name() when structure was initialized using several different classifiers. More...
 

Typedefs

typedef struct freesasa_structure freesasa_structure
 Struct for structure object. More...
 

Enumerations

enum  freesasa_structure_options {
  FREESASA_INCLUDE_HETATM =1, FREESASA_INCLUDE_HYDROGEN =1<<2, FREESASA_SEPARATE_MODELS =1<<3, FREESASA_SEPARATE_CHAINS =1<<4,
  FREESASA_JOIN_MODELS =1<<5, FREESASA_HALT_AT_UNKNOWN =1<<6, FREESASA_SKIP_UNKNOWN =1<<7, FREESASA_RADIUS_FROM_OCCUPANCY =1<<8
}
 Options for reading structure from PDB. More...
 

Functions

freesasa_structurefreesasa_structure_new (void)
 Allocate empty structure. More...
 
void freesasa_structure_free (freesasa_structure *structure)
 Free structure. More...
 
freesasa_structurefreesasa_structure_from_pdb (FILE *pdb, const freesasa_classifier *classifier, int options)
 Init structure with coordinates from pdb-file. More...
 
freesasa_structure ** freesasa_structure_array (FILE *pdb, int *n, const freesasa_classifier *classifier, int options)
 Init array of structures from PDB. More...
 
int freesasa_structure_add_atom (freesasa_structure *structure, const char *atom_name, const char *residue_name, const char *residue_number, char chain_label, double x, double y, double z)
 Add individual atom to structure using default behavior. More...
 
int freesasa_structure_add_atom_wopt (freesasa_structure *structure, const char *atom_name, const char *residue_name, const char *residue_number, char chain_label, double x, double y, double z, const freesasa_classifier *classifier, int options)
 Add individual atom to structure. More...
 
freesasa_structurefreesasa_structure_get_chains (const freesasa_structure *structure, const char *chains)
 Create new structure consisting of a selection chains from the provided structure. More...
 
const char * freesasa_structure_chain_labels (const freesasa_structure *structure)
 Get string listing all chains in structure. More...
 
int freesasa_structure_n (const freesasa_structure *structure)
 Get number of atoms. More...
 
int freesasa_structure_n_residues (const freesasa_structure *structure)
 Get number of residues. More...
 
int freesasa_structure_n_chains (const freesasa_structure *structure)
 Get number of chains. More...
 
const double * freesasa_structure_radius (const freesasa_structure *structure)
 Returns a pointer to an array of the radii of each atom. More...
 
void freesasa_structure_set_radius (freesasa_structure *structure, const double *radii)
 Override the radii set when the structure was initialized. More...
 
const char * freesasa_structure_atom_name (const freesasa_structure *structure, int i)
 Get atom name. More...
 
const char * freesasa_structure_atom_res_name (const freesasa_structure *structure, int i)
 Get residue name. More...
 
const char * freesasa_structure_atom_res_number (const freesasa_structure *structure, int i)
 Get residue number. More...
 
char freesasa_structure_atom_chain (const freesasa_structure *structure, int i)
 Get chain label. More...
 
const char * freesasa_structure_atom_symbol (const freesasa_structure *structure, int i)
 Get atom symbol. More...
 
double freesasa_structure_atom_radius (const freesasa_structure *structure, int i)
 Get atom radius. More...
 
void freesasa_structure_atom_set_radius (freesasa_structure *structure, int i, double radius)
 Set atom radius. More...
 
const char * freesasa_structure_residue_name (const freesasa_structure *structure, int r_i)
 Get name of residue. More...
 
const char * freesasa_structure_residue_number (const freesasa_structure *structure, int r_i)
 Get residue number. More...
 
char freesasa_structure_residue_chain (const freesasa_structure *structure, int r_i)
 Get chain residue belongs to. More...
 
int freesasa_structure_model (const freesasa_structure *structure)
 Get model number for structure. More...
 
const double * freesasa_structure_coord_array (const freesasa_structure *structure)
 Get array of coordinates. More...
 
int freesasa_structure_residue_atoms (const freesasa_structure *structure, int r_i, int *first, int *last)
 Get indices of first and last atoms of a residue. More...
 
int freesasa_structure_chain_atoms (const freesasa_structure *structure, char chain, int *first, int *last)
 Get indices of first and last atoms of a chain. More...
 
int freesasa_structure_chain_residues (const freesasa_structure *structure, char chain, int *first, int *last)
 Get indices of first and last residues of a chain. More...
 
const char * freesasa_structure_classifier_name (const freesasa_structure *structure)
 Name of classifier used to generate structure. More...
 

Detailed Description

Representation of macromolecular structures.

Interface for macromolecule structures, either instantiated directly from a PDB file (freesasa_structure_from_pdb()) or atom by atom (freesasa_structure_add_atom()).

Macro Definition Documentation

#define FREESASA_CONFLICTING_CLASSIFIERS   "conflicting-classifiers"

String returned by freesasa_structure_classifier_name() when structure was initialized using several different classifiers.

Definition at line 114 of file freesasa.h.

Typedef Documentation

Struct for structure object.

The struct includes the coordinates and radius of each atom, and its name, residue-name, etc. If it was initiated from a PDB file enough info will be stored so that a PDB-file can be printed using the original one as template.

Definition at line 199 of file freesasa.h.

Enumeration Type Documentation

Options for reading structure from PDB.

To be combined in options bitfield in freesasa_structure_from_pdb(), freesasa_structure_array() and freesasa_structure_add_atom_wopt(). See documentation for each function for which options are applicable.

Enumerator
FREESASA_INCLUDE_HETATM 

Include HETATM entries.

FREESASA_INCLUDE_HYDROGEN 

Include hydrogen atoms.

FREESASA_SEPARATE_MODELS 

Read MODELs as separate structures.

FREESASA_SEPARATE_CHAINS 

Read separate chains as separate structures.

FREESASA_JOIN_MODELS 

Read MODELs as part of one big structure.

FREESASA_HALT_AT_UNKNOWN 

Halt reading when unknown atom is encountered.

FREESASA_SKIP_UNKNOWN 

Skip atom when unknown atom is encountered.

FREESASA_RADIUS_FROM_OCCUPANCY 

Read atom radius from occupancy field.

Definition at line 144 of file freesasa.h.

Function Documentation

freesasa_structure* freesasa_structure_new ( void  )

Allocate empty structure.

Return value is dynamically allocated, should be freed with freesasa_structure_free().

Returns
Empty structure. NULL if memory allocation failure.
void freesasa_structure_free ( freesasa_structure structure)

Free structure.

Parameters
structureThe structure to free.
freesasa_structure* freesasa_structure_from_pdb ( FILE *  pdb,
const freesasa_classifier classifier,
int  options 
)

Init structure with coordinates from pdb-file.

Reads in a PDB-file and generates a structure object. Automatically skips hydrogens and HETATM. If an atom has alternative coordinates, only the first alternative is used. If a file has more than one MODEL (as in NMR structures) only the first model is used. The provided classifier is used to determine the radius of each atom, if the atom is not recognized the element of the atom is guessed, and that element's VdW radius used. If this fails its radius is set 0, which means that it won't contribute to SASA, but a radius from another source can be set through freesasa_structure_set_radius(). All these behaviors can be modified through the options bitfield argument:

If a more fine-grained control over which atoms to include is needed, the PDB-file needs to be modified before calling this function, or atoms can be added manually one by one using freesasa_structure_add_atom() or freesasa_structure_add_atom_wopt().

Return value is dynamically allocated, should be freed with freesasa_structure_free().

Parameters
pdbA PDB file
classifierA freesasa_classifier to determine radius of atom. If NULL default classifier is used.
optionsA bitfield to determine what atoms to include and what to do when atoms are not recognized by classifier.
Returns
The generated structure. Returns NULL and prints error if input is invalid or memory allocation failure.
freesasa_structure** freesasa_structure_array ( FILE *  pdb,
int *  n,
const freesasa_classifier classifier,
int  options 
)

Init array of structures from PDB.

Either iniatilize one structure per model in multimodel PDB, or one per chain, or both. Otherwise equivalent to freesasa_structure_from_pdb().

Returns dynamically allocated array of size n. Its members should be freed using freesasa_structure_free() and the array itself with free().

Parameters
pdbInput PDB-file.
nNumber of structures found are written to this integer.
classifierA classifier to calculate atomic radii.
optionsBitfield. Either or both of FREESASA_SEPARATE_MODELS and FREESASA_SEPARATE_CHAINS can be used to generate one structure per model and one structure per chain, respectively (will return NULL if neither is specified). See freesasa_structure_from_pdb() for documentation on options for deciding what atoms to include (FREESASA_JOIN_MODELS is not supported here).
Returns
Array of structures. Prints error message(s) and returns NULL if there were problems reading input, if invalid value of options, or upon a memory allocation failure.
int freesasa_structure_add_atom ( freesasa_structure structure,
const char *  atom_name,
const char *  residue_name,
const char *  residue_number,
char  chain_label,
double  x,
double  y,
double  z 
)

Add individual atom to structure using default behavior.

Equivalent to calling freesasa_structure_add_atom_wopt(), with classifier = NULL and options = 0.

Parameters
structureThe structure to add to.
atom_nameString of 4 characters, of the format " CA ", " OXT", etc.
residue_nameString of 3 charachters, of the format "ALA", "PHE", etc.
residue_numberString of 4 characters, of the format " 1", " 123", etc.
chain_labelAny character to label chain, typically 'A', 'B', etc.
xx-coordinate of atom.
yy-coordinate of atom.
zz-coordinate of atom.
Returns
FREESASA_SUCCESS on normal execution. FREESASA_FAIL if if memory allocation fails.
int freesasa_structure_add_atom_wopt ( freesasa_structure structure,
const char *  atom_name,
const char *  residue_name,
const char *  residue_number,
char  chain_label,
double  x,
double  y,
double  z,
const freesasa_classifier classifier,
int  options 
)

Add individual atom to structure.

A structure can be built by adding atoms one by one. Storing residue numbers as strings allows for non-numeric labels. Will include hydrogens if added (i.e. up to caller to make sure these are excluded if necessesary).

The atom name, residue name, etc are checked by the classifier, and depending on the value of options different things will happen when unknown atoms are encountered. In all cases the user will be alerted of what has happened through warnings or error messages:

See also
Because the argument list is so long, freesasa_structure_add_atom() is a shortcut to call this with defaults.
Parameters
structureThe structure to add to.
atom_nameThe atom name: " CA ","CA", " OXT", etc.
residue_nameThe residue name: "ALA", "PHE", etc.
residue_numberString of 4 characters, of the format " 1", " 123", etc.
chain_labelAny character to label chain, typically 'A', 'B', etc.
xx-coordinate of atom.
yy-coordinate of atom.
zz-coordinate of atom.
classifierA freesasa_classifier to determine radius of atom and to decide if to keep atom or not (see options).
optionsA bitfield to determine what to do with unknown atoms (see above).
Returns
FREESASA_SUCCESS on normal execution. FREESASA_FAIL if if memory allocation fails or if halting at unknown atom. FREESASA_WARN if skipping atom.
freesasa_structure* freesasa_structure_get_chains ( const freesasa_structure structure,
const char *  chains 
)

Create new structure consisting of a selection chains from the provided structure.

Simply looks for chain labels that match the characters in the provided string.

Return value is dynamically allocated, should be freed with freesasa_structure_free().

Parameters
structureInput structure.
chainsString of chain labels (e.g. "AB")
Returns
A new structure consisting only of the specified chains. Returns NULL if one or more of the requested chains don't match any in the input structure or if memory allocation fails.
const char* freesasa_structure_chain_labels ( const freesasa_structure structure)

Get string listing all chains in structure.

Parameters
structureThe structure.
Returns
String with all chain labels in structure ("A", "ABC", etc).
int freesasa_structure_n ( const freesasa_structure structure)

Get number of atoms.

Parameters
structureThe structure.
Returns
Number of atoms.
int freesasa_structure_n_residues ( const freesasa_structure structure)

Get number of residues.

Calculated crudely by determining the number of unique combinations of residue number and chain label contained in the structure. If residues are mingled i.e. atoms of the same residue are in non-contiguous regions of the file, this function might be off.

Parameters
structureA structure.
Returns
Number of residues.
int freesasa_structure_n_chains ( const freesasa_structure structure)

Get number of chains.

Parameters
structureA structure.
Returns
The number of chains in the structure.
const double* freesasa_structure_radius ( const freesasa_structure structure)

Returns a pointer to an array of the radii of each atom.

Parameters
structureThe structure.
Returns
Array of radii. If NULL structure has not been properly initialized.
void freesasa_structure_set_radius ( freesasa_structure structure,
const double *  radii 
)

Override the radii set when the structure was initialized.

Makes a copy of the provided array.

Parameters
structureThe structure.
radiiAn array of radii, should have same dimension as the number of atoms in the structure.
const char* freesasa_structure_atom_name ( const freesasa_structure structure,
int  i 
)

Get atom name.

Asserts that index i is within bounds.

Parameters
structureThe structure.
iAtom index.
Returns
Atom name in the form " CA ", " OXT", etc, if structure was initialized from a PDB file, or in whatever form it was added through freesasa_structure_add_atom() or freesasa_structure_add_atom_wopt().
const char* freesasa_structure_atom_res_name ( const freesasa_structure structure,
int  i 
)

Get residue name.

Asserts that index i is within bounds.

Parameters
structureThe structure.
iAtom index.
Returns
Residue name in the form "ALA", "PHE", " C", etc, if structure was initialized from a PDB file, or in whatever form it was added through freesasa_structure_add_atom() or freesasa_structure_add_atom_wopt().
const char* freesasa_structure_atom_res_number ( const freesasa_structure structure,
int  i 
)

Get residue number.

Asserts that index i is within bounds.

Parameters
structureThe structure.
iAtom index.
Returns
Residue name in the form " 1", " 123", etc, if structure was initialized from a PDB file, or in whatever form it was added through freesasa_structure_add_atom() or freesasa_structure_add_atom_wopt().
char freesasa_structure_atom_chain ( const freesasa_structure structure,
int  i 
)

Get chain label.

Asserts that index i is within bounds.

Parameters
structureThe structure.
iAtom index.
Returns
Chain label ('A', 'B', etc.)
const char* freesasa_structure_atom_symbol ( const freesasa_structure structure,
int  i 
)

Get atom symbol.

If the structure was initialized from a PDB file the symbol field of that file is used. Otherwise the symbol is guessed from atom and residue name.

Asserts that index i is within bounds.

Parameters
structureThe structure.
iAtom index.
Returns
Atom symbol (" C", " N", "SE",etc);
double freesasa_structure_atom_radius ( const freesasa_structure structure,
int  i 
)

Get atom radius.

Asserts that index i is within bounds.

Parameters
structureThe structure.
iAtom index.
Returns
Atom radius.
void freesasa_structure_atom_set_radius ( freesasa_structure structure,
int  i,
double  radius 
)

Set atom radius.

Asserts that index i is within bounds.

Parameters
structureThe structure.
radiusThe radius.
iAtom index.
const char* freesasa_structure_residue_name ( const freesasa_structure structure,
int  r_i 
)

Get name of residue.

Parameters
structureThe structure.
r_iResidue index (in whole structure)
Returns
Name of residue
const char* freesasa_structure_residue_number ( const freesasa_structure structure,
int  r_i 
)

Get residue number.

Parameters
structureThe structure.
r_iResidue index (in whole structure).
Returns
Residue number as string.
char freesasa_structure_residue_chain ( const freesasa_structure structure,
int  r_i 
)

Get chain residue belongs to.

Parameters
structureThe structure.
r_iResidue index (in whole structure).
Returns
Chain label.
int freesasa_structure_model ( const freesasa_structure structure)

Get model number for structure.

Useful if structure was generated with freesasa_structure_array().

Parameters
structureThe structure.
Returns
The model number. Will be 1 if MODEL not specified in PDB input.
const double* freesasa_structure_coord_array ( const freesasa_structure structure)

Get array of coordinates.

Size of array is 3*N, order of coordinates x1, y1, z1, ....

Parameters
structureThe structure.
Returns
Array of coordinates. NULL if structure empty. Size can be accessed through freesasa_structure_n() (multiply by three).
int freesasa_structure_residue_atoms ( const freesasa_structure structure,
int  r_i,
int *  first,
int *  last 
)

Get indices of first and last atoms of a residue.

Parameters
structureA structure.
r_iResidue index.
firstFirst atom of residue r_i will be stored here.
lastLast atom of residue r_i will be stored here.
Returns
FREESASA_SUCCESS. FREESASA_FAIL if index r_i is invalid.
int freesasa_structure_chain_atoms ( const freesasa_structure structure,
char  chain,
int *  first,
int *  last 
)

Get indices of first and last atoms of a chain.

Parameters
structureA structure.
chainThe chain label.
firstFirst atom of chain will be stored here.
lastLast atom of chain will be stored here.
Returns
FREESASA_SUCCESS. FREESASA_FAIL if chain not found.
int freesasa_structure_chain_residues ( const freesasa_structure structure,
char  chain,
int *  first,
int *  last 
)

Get indices of first and last residues of a chain.

Parameters
structureA structure.
chainThe chain label.
firstFirst residue of chain will be stored here.
lastLast residue of chain will be stored here.
Returns
FREESASA_SUCCESS. FREESASA_FAIL if chain not found.
const char* freesasa_structure_classifier_name ( const freesasa_structure structure)

Name of classifier used to generate structure.

Parameters
structureA structure.
Returns
Name of classifier. Name will equal FREESASA_CONFLICTING_CLASSIFIERS if several different classifiers were used.