Functions and datatypes for performing and analyzing SASA calculations. More...

#include <stdio.h>

Data Structures
struct	freesasa_parameters
	Struct to store parameters for SASA calculation. More...

struct	freesasa_result
	Struct to store results of SASA calculation. More...

struct	freesasa_residue_sasa
	Struct to store SASA values for a named residue. More...

struct	freesasa_strvp
	Struct used to store n string-value-pairs (strvp) in arrays of doubles and strings. More...

struct	freesasa_classifier
	Struct used for calculating classes and radii for atoms given their residue-names ('ALA','ARG',...) and atom-names ('CA','N',...). More...

struct	freesasa_rsa_reference
	Used as reference in generation of RSA file. More...

Macros
#define	FREESASA_DEF_ALGORITHM FREESASA_LEE_RICHARDS
	Default algorithm.

#define	FREESASA_DEF_PROBE_RADIUS 1.4
	Default probe radius (in Ångström).

#define	FREESASA_DEF_SR_N 100
	Default number of test points in S&R.

#define	FREESASA_DEF_LR_N 20
	Default number of slices per atom in L&R.

#define	freesasa_default_classifier freesasa_protor_classifier
	Default freesasa_classifier.

#define	freesasa_default_rsa freesasa_protor_rsa
	Default freesasa_rsa_reference.

#define	FREESASA_MAX_SELECTION_NAME 50
	The maximum length of a selection name. More...

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

Enumerations
enum	freesasa_algorithm { FREESASA_LEE_RICHARDS, FREESASA_SHRAKE_RUPLEY }
	The FreeSASA algorithms. More...

enum	freesasa_verbosity { FREESASA_V_NORMAL, FREESASA_V_NOWARNINGS, FREESASA_V_SILENT, FREESASA_V_DEBUG }
	Verbosity levels. More...

enum	freesasa_error_codes { FREESASA_SUCCESS =0, FREESASA_FAIL =-1, FREESASA_WARN =-2 }
	Error codes. More...

enum	freesasa_structure_options { FREESASA_INCLUDE_HETATM =1, FREESASA_INCLUDE_HYDROGEN =2, FREESASA_SEPARATE_MODELS =4, FREESASA_SEPARATE_CHAINS =8, FREESASA_JOIN_MODELS =16, FREESASA_HALT_AT_UNKNOWN =32, FREESASA_SKIP_UNKNOWN =64, FREESASA_RADIUS_FROM_OCCUPANCY =128 }
	Options for reading structure from PDB. More...

Functions
freesasa_result *	freesasa_calc_structure (const freesasa_structure structure, const freesasa_parameters parameters)
	Calculates SASA based on a given structure. More...

freesasa_result *	freesasa_calc_coord (const double xyz, const double radii, int n, const freesasa_parameters *parameters)
	Calculates SASA based on a given set of coordinates and radii. More...

void	freesasa_result_free (freesasa_result *result)
	Frees a freesasa_result object. More...

freesasa_classifier *	freesasa_classifier_from_file (FILE *file)
	Generate a classifier from a config-file. More...

void	freesasa_classifier_free (freesasa_classifier *classifier)
	Frees a classifier object. More...

freesasa_strvp *	freesasa_result_classify (const freesasa_result result, const freesasa_structure structure, const freesasa_classifier *classifier)
	Sums up the SASA for groups of atoms defined by a classifier. More...

int	freesasa_select_area (const char command, char name, double area, const freesasa_structure structure, const freesasa_result *result)
	Get area of a selection. More...

void	freesasa_strvp_free (freesasa_strvp *strvp)
	Frees a freesasa_strvp object. More...

int	freesasa_write_pdb (FILE output, freesasa_result result, const freesasa_structure *structure)
	Write SASA values and atomic radii to new PDB-file. More...

int	freesasa_per_chain (FILE output, freesasa_result result, const freesasa_structure *structure)
	Print SASA for each chain. More...

int	freesasa_per_residue_type (FILE output, freesasa_result result, const freesasa_structure *structure)
	Print SASA for all residue types to file. More...

int	freesasa_per_residue (FILE output, freesasa_result result, const freesasa_structure *structure)
	Print SASA for each residue in the sequence to file. More...

int	freesasa_log (FILE log, freesasa_result result, const char name, const freesasa_parameters parameters, const freesasa_strvp *class_sasa)
	Log calculation results. More...

int	freesasa_write_result (FILE log, freesasa_result result, const char name, const char chains, const freesasa_strvp *class_sasa)
	Write results of claculation to file. More...

int	freesasa_write_parameters (FILE log, const freesasa_parameters parameters)
	Print parameters to file. More...

int	freesasa_write_rsa (FILE output, const freesasa_result result, const freesasa_structure structure, const char name, const freesasa_rsa_reference *reference)
	Print RSA-file. More...

int	freesasa_set_verbosity (freesasa_verbosity v)
	Set the global verbosity level. More...

freesasa_verbosity	freesasa_get_verbosity (void)
	Get the current verbosity level. More...

void	freesasa_set_err_out (FILE *err)
	Set where to write errors. More...

FILE *	freesasa_get_err_out ()
	Get pointer to error file. More...

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...

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. 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 *s)
	Get number of residues. More...

int	freesasa_structure_n_chains (const freesasa_structure *s)
	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...

const char *	freesasa_structure_residue_name (const freesasa_structure *s, int r_i)
	Get name of residue. More...

const char *	freesasa_structure_residue_number (const freesasa_structure *s, int r_i)
	Get residue number. More...

char	freesasa_structure_residue_chain (const freesasa_structure *s, 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 s, 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 s, char chain, int first, int *last)
	Get indices of first and last atoms of a chain. More...

Variables
const int	FREESASA_DEF_NUMBER_THREADS
	Default number of threads. More...

const freesasa_parameters	freesasa_default_parameters
	The default parameters for FreeSASA.

const freesasa_classifier	freesasa_protor_classifier
	Classifier using ProtOr radii and classes.

const freesasa_classifier	freesasa_naccess_classifier
	Classifier using NACCESS radii and classes.

const freesasa_classifier	freesasa_oons_classifier
	Classifier using OONS radii and classes.

const freesasa_rsa_reference	freesasa_protor_rsa
	An RSA-reference for the ProtOr configuration.

const freesasa_rsa_reference	freesasa_naccess_rsa
	An RSA-reference for the NACCESS configuration.

Detailed Description

Functions and datatypes for performing and analyzing SASA calculations.

Author: Simon Mitternacht

Copyright: MIT License

This header provides the functions and data types necessary to perform and analyze a SASA calculation using FreeSASA, including facilities to customize assignment of radii to, and classification of, atoms. There are also functions to access properties of a structure, to allow refined analysis of the results. The page FreeSASA API shows how to set up and perform a simple SASA calculation.

Definition in file freesasa.h.

Macro Definition Documentation

#define FREESASA_MAX_SELECTION_NAME 50

The maximum length of a selection name.

See also: freesasa_select_area()

Definition at line 84 of file freesasa.h.

Typedef Documentation

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 (see freesasa_write_pdb()).

Definition at line 123 of file freesasa.h.

Enumeration Type Documentation

enum freesasa_algorithm

The FreeSASA algorithms.

Enumerator
FREESASA_LEE_RICHARDS	Lee & Richards' algorithm.
FREESASA_SHRAKE_RUPLEY	Shrake & Rupley's algorithm.

Definition at line 28 of file freesasa.h.

enum freesasa_verbosity

Verbosity levels.

See also: freesasa_set_verbosity(); freesasa_get_verbosity()

Enumerator
FREESASA_V_NORMAL	Print all errors and warnings.
FREESASA_V_NOWARNINGS	Print only errors.
FREESASA_V_SILENT	Print no errors and warnings.
FREESASA_V_DEBUG	Print all errors, warnings and debug messages.

Definition at line 34 of file freesasa.h.

enum freesasa_error_codes

Error codes.

Can rely upon FREESASA_SUCCESS being 0 and the errors having negative numbers.

Enumerator
FREESASA_SUCCESS	All is ok (value will always be zero).
FREESASA_FAIL	Something went seriously wrong (value will always be negative).
FREESASA_WARN	Something went wrong, but results might still be meaningful (value will always be negative).

Definition at line 60 of file freesasa.h.

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

Function Documentation

freesasa_result* freesasa_calc_structure	(	const freesasa_structure *	structure,
		const freesasa_parameters *	parameters
	)

Calculates SASA based on a given structure.

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

Parameters

structure	The structure
parameters	Parameters for the calculation, if NULL defaults are used.

Returns: The result of the calculation, NULL if something went wrong.

freesasa_result* freesasa_calc_coord	(	const double *	xyz,
		const double *	radii,
		int	n,
		const freesasa_parameters *	parameters
	)

Calculates SASA based on a given set of coordinates and radii.

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

Parameters

parameters	Parameters for the calculation, if NULL defaults are used.
xyz	Array of coordinates in the form x1,y1,z1,x2,y2,z2,...,xn,yn,zn.
radii	Radii, this array should have n elements..
n	Number of coordinates (i.e. xyz has size 3*n, radii size n).

Returns: The result of the calculation, NULL if something went wrong.

void freesasa_result_free ( freesasa_result * result )

Frees a freesasa_result object.

Parameters

result the object to be freed.

freesasa_classifier* freesasa_classifier_from_file ( FILE * file )

Generate a classifier from a config-file.

Input file format described in Classifier configuration files

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

Parameters

file	File containing configuration

Returns: The generated classifier. NULL if there were problems parsing or reading the file or memory allocation problem.

See also: Classifier configuration files

void freesasa_classifier_free ( freesasa_classifier * classifier )

Frees a classifier object.

Parameters

classifier The classifier.

freesasa_strvp* freesasa_result_classify	(	const freesasa_result *	result,
		const freesasa_structure *	structure,
		const freesasa_classifier *	classifier
	)

Sums up the SASA for groups of atoms defined by a classifier.

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

Parameters

result	The results to be analyzed.
structure	Structure to be used to determine atom types.
classifier	The classifier. If NULL, default is used.

Returns: A new set of string-value-pairs if classifications was successful. NULL if classifier was not compatible with structure or memory allocation failure.

int freesasa_select_area	(	const char *	command,
		char *	name,
		double *	area,
		const freesasa_structure *	structure,
		const freesasa_result *	result
	)

Get area of a selection.

Uses subset of the select syntax from Pymol (name, symbol, resn, resi and chain), the keyword "select" is implicit. All commands are case insensitive. Valid selections would be, for example,

selection_name, resn ala+arg 
selection_name, chain a and resi 1+3-20 and not resn gly

After selecting the atoms from the freesasa_structure pointer specified by the command the area of those atoms is summed up using the freesasa_result pointer.

See also: Selection syntax

Parameters

command	The selection
name	The name of the selection is stored here, it should be able to store a string of length FREESASA_MAX_SELECTION_NAME.
area	The area of the selection is stored here
structure	The structure to select from
result	The results to integrate

Returns: FREESASA_SUCCESS upon successful selection. FREESASA_WARN if some illegal selections that could be ignored were encountered (see printed warnings). FREESASA_FAIL if syntax error or memory failure.

void freesasa_strvp_free ( freesasa_strvp * strvp )

Frees a freesasa_strvp object.

Parameters

strvp the object to be freed

int freesasa_write_pdb	(	FILE *	output,
		freesasa_result *	result,
		const freesasa_structure *	structure
	)

Write SASA values and atomic radii to new PDB-file.

Takes PDB information from the provided structure and writes a new PDB-file to output, where the B-factors have been replaced with the atom's SASA values in the results, and the occupancy factors with the radii.

Will only work if the structure was initialized from a PDB-file, i.e. using freesasa_structure_from_pdb() or freesasa_structure_array().

Parameters

output	File to write to.
result	SASA values.
structure	Structure to use to print PDB.

Returns: FREESASA_SUCCESS if file written successfully. FREESASA_FAIL if there is no previous PDB input to base output on or if there were problems writing to the file.

int freesasa_per_chain	(	FILE *	output,
		freesasa_result *	result,
		const freesasa_structure *	structure
	)

Print SASA for each chain.

Prints the contribution of each chain to the total SASA. Each line in the output is prefixed by the string CHAIN.

Parameters

output	Output file.
result	SASA values.
structure	The structure.

Returns: FREESASA_FAIL if problems writing to output. FREESASA_SUCCESS else.

int freesasa_per_residue_type	(	FILE *	output,
		freesasa_result *	result,
		const freesasa_structure *	structure
	)

Print SASA for all residue types to file.

Prints name/value-pairs with the total SASA of each residue type. The standard 20 amino acids are always included in output, non-standard ones and nucleotides only if they were present in input. Each line in the output is prefixed by the string "`RES`".

Parameters

output	Output file.
result	SASA values.
structure	The structure.

Returns: FREESASA_FAIL if problems writing to output. FREESASA_SUCCESS else.

int freesasa_per_residue	(	FILE *	output,
		freesasa_result *	result,
		const freesasa_structure *	structure
	)

Print SASA for each residue in the sequence to file.

Each line in the output is prefixed by the string "`SEQ`".

Parameters

output	Output file.
result	SASA values.
structure	The structure.

Returns: FREESASA_FAIL if problems writing to output. FREESASA_SUCCESS else.

int freesasa_log	(	FILE *	log,
		freesasa_result *	result,
		const char *	name,
		const freesasa_parameters *	parameters,
		const freesasa_strvp *	class_sasa
	)

Log calculation results.

Prints log of calculation to specified file, equivalent of calling first freesasa_write_parameters() and then freesasa_write_result()

Parameters

log	Output-file.
result	SASA values.
parameters	Parameters to print, if NULL defaults are used
name	Name of the protein, if NULL "unknown" used.
class_sasa	The SASA values for each class, if NULL only total SASA printed

Returns: FREESASA_SUCCESS on success, FREESASA_FAIL if problems writing to file.

Deprecated:: Use freesasa_write_parameters() and freesasa_write_result() instead.

int freesasa_write_result	(	FILE *	log,
		freesasa_result *	result,
		const char *	name,
		const char *	chains,
		const freesasa_strvp *	class_sasa
	)

Write results of claculation to file.

Parameters

log	Output-file.
result	SASA values.
name	Name of the protein, if NULL "unknown" used.
chains	The chains used in the calculation, can be NULL
class_sasa	The SASA values for each class, if NULL only total SASA printed

Returns: FREESASA_SUCCESS on success, FREESASA_FAIL if problems writing to file.

int freesasa_write_parameters	(	FILE *	log,
		const freesasa_parameters *	parameters
	)

Print parameters to file.

Parameters

log	Output-file
parameters	Parameters to print, if NULL defaults are used

Returns: FREESASA_SUCCESS on success, FREESASA_FAIL if problems writing to file.

int freesasa_write_rsa	(	FILE *	output,
		const freesasa_result *	result,
		const freesasa_structure *	structure,
		const char *	name,
		const freesasa_rsa_reference *	reference
	)

Print RSA-file.

Uses reference SASA values calculated using the default configuration (ProtOr radii; Carbon is apolar, all other elements polar; probe radius = 1.4 Å). The Ala-X-Ala configurations supplied in the directory rsa were used as input (the reference values themselves are stored statically in the code). At the moment there is no support for outputting RSA files for other configurations.

Remarks: This is still an experimental feature, and the interface may still be subject to change without warning.

Parameters

output	Output-file
result	SASA values
structure	The structure
name	Name of the protein
reference	Reference to calculate RSA from, if NULL defaults are used.

Returns: FREESASA_SUCCESS on success, FREESASA_FAIL if problems writing to file, or if structure is inconsistent.

int freesasa_set_verbosity ( freesasa_verbosity v )

Set the global verbosity level.

Parameters

v	the verbosity level

Returns: FREESASA_SUCCESS. If v is invalid FREESASA_FAIL.

See also: freesasa_verbosity

freesasa_verbosity freesasa_get_verbosity ( void )

Get the current verbosity level.

Returns: the verbosity level.

void freesasa_set_err_out ( FILE * err )

Set where to write errors.

By default stderr is used, this function can be called to redirect error output elsewhere.

Parameters

err	The file to write to. If NULL stderr will be used.

FILE* freesasa_get_err_out ( )

Get pointer to error file.

NULL means stderr is used.

Returns: The error file.

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

structure The 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:

options == 0: Default behavior
options & FREESASA_INCLUDE_HYDROGEN == 1: Include hydrogens.
options & FREESASA_INCLUDE_HETATM == 1: Include HETATM.
options & FREESASA_JOIN_MODELS == 1: Join models.
options & FREESASA_SKIP_UNKNOWN == 1: Skip unknown atoms.
options & FREESASA_HALT_AT_UNKNOWN == 1: Halt at unknown atom and return NULL. Overrides FREESASA_SKIP_UNKNOWN.
options & FREESASA_RADIUS_FROM_OCCUPANCY == 1: 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** 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.

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.

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* 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

structure	Input structure.
chains	String of chain labels (e.g. "AB")

Returns: A new structure consisting only of the specified chains. Returns NULL if the input structure doesn't have any matching chains or if memory allocation fails.

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).

int freesasa_structure_n ( const freesasa_structure * structure )

Get number of atoms.

Parameters

structure The structure.

Returns: Number of atoms.

int freesasa_structure_n_residues ( const freesasa_structure * s )

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

s	A structure.

Returns: Number of residues.

int freesasa_structure_n_chains ( const freesasa_structure * s )

Get number of chains.

Parameters

s	A 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

structure The 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

structure	The structure.
radii	An 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

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

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", 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

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

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.)

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);

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

Get name of residue.

Parameters

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

Returns: Name of residue

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

Get residue number.

Parameters

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

Returns: Residue number as string.

char freesasa_structure_residue_chain	(	const freesasa_structure *	s,
		int	r_i
	)

Get chain residue belongs to.

Parameters

s	The structure.
r_i	Residue 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

structure The structure.

Returns: The model number. 0 means no model number has been read.

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).

int freesasa_structure_residue_atoms	(	const freesasa_structure *	s,
		int	r_i,
		int *	first,
		int *	last
	)

Get indices of first and last atoms of a residue.

Parameters

s	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.

int freesasa_structure_chain_atoms	(	const freesasa_structure *	s,
		char	chain,
		int *	first,
		int *	last
	)

Get indices of first and last atoms of a chain.

Parameters

s	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.

Variable Documentation

const int FREESASA_DEF_NUMBER_THREADS

Default number of threads.

Value will depend on if library was compiled with or without thread support. (2 with threads, 1 without)

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation