Representation of macromolecular structures. More...

Data Structures
struct	freesasa_cif_atom
	Struct to store data about a mmCIF atom site. 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_structure *	freesasa_structure_new (void)
	Allocate empty structure. More...

void	freesasa_structure_free (freesasa_structure *structure)
	Free structure. More...

freesasa_structure *	freesasa_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...

int	freesasa_structure_add_cif_atom (freesasa_structure structure, freesasa_cif_atom atom, const freesasa_classifier *classifier, int options)
	Add atoms from a mmCIF file to a structure. More...

freesasa_structure *	freesasa_structure_get_chains (const freesasa_structure structure, const char chains, const freesasa_classifier *classifier, int options)
	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

◆ FREESASA_CONFLICTING_CLASSIFIERS

#define FREESASA_CONFLICTING_CLASSIFIERS "conflicting-classifiers"

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

Definition at line 133 of file freesasa.h.

Typedef Documentation

◆ freesasa_structure

typedef struct freesasa_structure freesasa_structure

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 260 of file freesasa.h.

Enumeration Type Documentation

◆ freesasa_structure_options

enum freesasa_structure_options

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 182 of file freesasa.h.

Function Documentation

◆ freesasa_structure_new()

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.

◆ freesasa_structure_free()

void freesasa_structure_free ( freesasa_structure * structure )

Free structure.

Parameters

structure The structure to free.

◆ freesasa_structure_from_pdb()

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:

0: Default behavior
FREESASA_INCLUDE_HYDROGEN: Include hydrogen atoms.
FREESASA_INCLUDE_HETATM: Include HETATM.
FREESASA_JOIN_MODELS: Join models.
FREESASA_SKIP_UNKNOWN: Skip unknown atoms.
FREESASA_HALT_AT_UNKNOWN: Halt at unknown atom and return NULL. Overrides FREESASA_SKIP_UNKNOWN.
FREESASA_RADIUS_FROM_OCCUPANCY: Read atomic radii from Occupancy field in PDB file.

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

pdb	A PDB file
classifier	A freesasa_classifier to determine radius of atom. If `NULL` default classifier is used.
options	A 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_array()

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

pdb	Input PDB-file.
n	Number of structures found are written to this integer.
classifier	A classifier to calculate atomic radii.
options	Bitfield. 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.

◆ freesasa_structure_add_atom()

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

structure	The structure to add to.
atom_name	String of 4 characters, of the format `" CA "`, `" OXT"`, etc.
residue_name	String of 3 charachters, of the format `"ALA"`, `"PHE"`, etc.
residue_number	String of 4 characters, of the format `" 1"`, `" 123"`, etc.
chain_label	Any character to label chain, typically ‘'A’`,`'B'`, etc.
x	x-coordinate of atom.
y	y-coordinate of atom.
z	z-coordinate of atom.

Returns: FREESASA_SUCCESS on normal execution. FREESASA_FAIL if if memory allocation fails.

◆ freesasa_structure_add_atom_wopt()

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:

options == 0 means guess element of unknown atoms, and use that element's VdW radius. If this fails, assign radius 0. A 0 radius means this atom won't contribute to the SASA, but will still be there if we want to use freesasa_structure_set_radius() to assign a radius from another source.
options & FREESASA_SKIP_UNKNOWN == 1 skip unknown atoms, return FREESASA_WARN.
options & FREESASA_HALT_AT_UNKNOWN == 1 skip unknown atoms, return FREESASA_FAIL. Overrides FREESASA_SKIP_UNKNOWN.

See also: Because the argument list is so long, freesasa_structure_add_atom() is a shortcut to call this with defaults.

Parameters

structure	The structure to add to.
atom_name	The atom name: `" CA "`,`"CA"`, `" OXT"`, etc.
residue_name	The residue name: `"ALA"`, `"PHE"`, etc.
residue_number	String of 4 characters, of the format `" 1"`, `" 123"`, etc.
chain_label	Any character to label chain, typically ‘'A’`,`'B'`, etc.
x	x-coordinate of atom.
y	y-coordinate of atom.
z	z-coordinate of atom.
classifier	A freesasa_classifier to determine radius of atom and to decide if to keep atom or not (see options).
options	A 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_add_cif_atom()

int freesasa_structure_add_cif_atom	(	freesasa_structure *	structure,
		freesasa_cif_atom *	atom,
		const freesasa_classifier *	classifier,
		int	options
	)

Add atoms from a mmCIF file to a structure.

Parameters

structure	The structure to add to.
atom	An atom site from a mmCIF file
classifier	A freesasa_classifier to determine radius of atom and to decide if to keep atom or not (see options).
options	Structure options as in freesasa_structure_add_atom_wopt()

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_get_chains()

freesasa_structure * freesasa_structure_get_chains	(	const freesasa_structure *	structure,
		const char *	chains,
		const freesasa_classifier *	classifier,
		int	options
	)

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

structure	Input structure.
chains	String of chain labels (e.g. `"AB"`)
classifier	A classifier to use to build the new structure
options	Structure options as in freesasa_structure_add_atom_wopt()

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.

◆ freesasa_structure_chain_labels()

const char * freesasa_structure_chain_labels ( const freesasa_structure * structure )

Get string listing all chains in structure.

Parameters

structure The structure.

Returns: String with all chain labels in structure ("A", "ABC", etc).

◆ freesasa_structure_n()

int freesasa_structure_n ( const freesasa_structure * structure )

Get number of atoms.

Parameters

structure The structure.

Returns: Number of atoms.

◆ freesasa_structure_n_residues()

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

structure A structure.

Returns: Number of residues.

◆ freesasa_structure_n_chains()

int freesasa_structure_n_chains ( const freesasa_structure * structure )

Get number of chains.

Parameters

structure A structure.

Returns: The number of chains in the structure.

◆ freesasa_structure_radius()

const double * freesasa_structure_radius ( const freesasa_structure * structure )

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

Parameters

structure The structure.

Returns: Array of radii. If NULL structure has not been properly initialized.

◆ freesasa_structure_set_radius()

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

structure	The structure.
radii	An array of radii, should have same dimension as the number of atoms in the structure.

◆ freesasa_structure_atom_name()

const char * freesasa_structure_atom_name	(	const freesasa_structure *	structure,
		int	i
	)

Get atom name.

Asserts that index i is within bounds.

Parameters

structure	The structure.
i	Atom 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().

◆ freesasa_structure_atom_res_name()

const char * freesasa_structure_atom_res_name	(	const freesasa_structure *	structure,
		int	i
	)

Get residue name.

Asserts that index i is within bounds.

Parameters

structure	The structure.
i	Atom 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().

◆ freesasa_structure_atom_res_number()

const char * freesasa_structure_atom_res_number	(	const freesasa_structure *	structure,
		int	i
	)

Get residue number.

Asserts that index i is within bounds.

Parameters

structure	The structure.
i	Atom 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().

◆ freesasa_structure_atom_chain()

char freesasa_structure_atom_chain	(	const freesasa_structure *	structure,
		int	i
	)

Get chain label.

Asserts that index i is within bounds.

Parameters

structure	The structure.
i	Atom index.

Returns: Chain label (‘'A’,'B'`, etc.)

◆ freesasa_structure_atom_symbol()

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

structure	The structure.
i	Atom index.

Returns: Atom symbol (" C", " N", "SE",etc);

◆ freesasa_structure_atom_radius()

double freesasa_structure_atom_radius	(	const freesasa_structure *	structure,
		int	i
	)

Get atom radius.

Asserts that index i is within bounds.

Parameters

structure	The structure.
i	Atom index.

Returns: Atom radius.

◆ freesasa_structure_atom_set_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

structure	The structure.
radius	The radius.
i	Atom index.

◆ freesasa_structure_residue_name()

const char * freesasa_structure_residue_name	(	const freesasa_structure *	structure,
		int	r_i
	)

Get name of residue.

Parameters

structure	The structure.
r_i	Residue index (in whole structure)

Returns: Name of residue

◆ freesasa_structure_residue_number()

const char * freesasa_structure_residue_number	(	const freesasa_structure *	structure,
		int	r_i
	)

Get residue number.

Parameters

structure	The structure.
r_i	Residue index (in whole structure).

Returns: Residue number as string.

◆ freesasa_structure_residue_chain()

char freesasa_structure_residue_chain	(	const freesasa_structure *	structure,
		int	r_i
	)

Get chain residue belongs to.

Parameters

structure	The structure.
r_i	Residue index (in whole structure).

Returns: Chain label.

◆ freesasa_structure_model()

int freesasa_structure_model ( const freesasa_structure * structure )

Get model number for structure.

Useful if structure was generated with freesasa_structure_array().

Parameters

structure The structure.

Returns: The model number. Will be 1 if MODEL not specified in PDB input.

◆ freesasa_structure_coord_array()

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

structure The structure.

Returns: Array of coordinates. NULL if structure empty. Size can be accessed through freesasa_structure_n() (multiply by three).

◆ freesasa_structure_residue_atoms()

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

structure	A structure.
r_i	Residue index.
first	First atom of residue `r_i` will be stored here.
last	Last atom of residue `r_i` will be stored here.

Returns: FREESASA_SUCCESS. FREESASA_FAIL if index r_i is invalid.

◆ freesasa_structure_chain_atoms()

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

structure	A structure.
chain	The chain label.
first	First atom of `chain` will be stored here.
last	Last atom of `chain` will be stored here.

Returns: FREESASA_SUCCESS. FREESASA_FAIL if chain not found.

◆ freesasa_structure_chain_residues()

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

structure	A structure.
chain	The chain label.
first	First residue of `chain` will be stored here.
last	Last residue of `chain` will be stored here.

Returns: FREESASA_SUCCESS. FREESASA_FAIL if chain not found.

◆ freesasa_structure_classifier_name()

const char * freesasa_structure_classifier_name ( const freesasa_structure * structure )

Name of classifier used to generate structure.

Parameters

structure A structure.

Returns: Name of classifier. Name will equal FREESASA_CONFLICTING_CLASSIFIERS if several different classifiers were used.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ FREESASA_CONFLICTING_CLASSIFIERS

Typedef Documentation

◆ freesasa_structure

Enumeration Type Documentation

◆ freesasa_structure_options

Function Documentation

◆ freesasa_structure_new()

◆ freesasa_structure_free()

◆ freesasa_structure_from_pdb()

◆ freesasa_structure_array()

◆ freesasa_structure_add_atom()

◆ freesasa_structure_add_atom_wopt()

◆ freesasa_structure_add_cif_atom()

◆ freesasa_structure_get_chains()

◆ freesasa_structure_chain_labels()

◆ freesasa_structure_n()

◆ freesasa_structure_n_residues()

◆ freesasa_structure_n_chains()

◆ freesasa_structure_radius()

◆ freesasa_structure_set_radius()

◆ freesasa_structure_atom_name()

◆ freesasa_structure_atom_res_name()

◆ freesasa_structure_atom_res_number()

◆ freesasa_structure_atom_chain()

◆ freesasa_structure_atom_symbol()

◆ freesasa_structure_atom_radius()

◆ freesasa_structure_atom_set_radius()

◆ freesasa_structure_residue_name()

◆ freesasa_structure_residue_number()

◆ freesasa_structure_residue_chain()

◆ freesasa_structure_model()

◆ freesasa_structure_coord_array()

◆ freesasa_structure_residue_atoms()

◆ freesasa_structure_chain_atoms()

◆ freesasa_structure_chain_residues()

◆ freesasa_structure_classifier_name()