FreeSASA  2.1.2
Open source SASA calculations
View on GitHub
FreeSASA API

Basics

The API is found in the header freesasa.h. The other source-files and headers in the repository are for internal use, and are not presented here, but are documented in the source itself. The file example.c contains a simple program that illustrates how to use the API to read a PDB file from stdin and calculate and print the SASA.

To calculate the SASA of a structure, there are two main options:

  1. Initialize a structure from a PDB-file, using either the default classifier or a custom one to determine the radius of each atom, and then run the calculation.
  2. Provide an array of cartesian coordinates and an array containing the radii of the corresponding atoms to freesasa_calc_coord().

Calculate SASA for a PDB file

The following explains how to use FreeSASA to calculate the SASA of a fictive PDB file (1abc.pdb). At each step one or more error checks should have been done, but these are ignored here for brevity. See the documentation of each function to see what errors can occur. Default parameters are used at every step, the section Customizing behavior explains how to configure the calculations.

Open PDB file

The function freesasa_structure_from_pdb() reads the atom coordinates from a PDB file and assigns a radius to each atom. The third argument can be used to pass options for how to read the PDB file.

FILE *fp = fopen("1abc.pdb");
freesasa_structure *structure = freesasa_structure_from_pdb(fp, classifier, 0);
struct freesasa_classifier freesasa_classifier
Classifier struct.
Definition: freesasa.h:374
#define freesasa_default_classifier
Default freesasa_classifier.
Definition: freesasa.h:124
struct freesasa_structure freesasa_structure
Struct for structure object.
Definition: freesasa.h:260
freesasa_structure * freesasa_structure_from_pdb(FILE *pdb, const freesasa_classifier *classifier, int options)
Init structure with coordinates from pdb-file.

Perform calculation and get total SASA

Next we use freesasa_calc_structure() to calculate SASA using the structure we just generated, and then print the total area. The argument NULL means use default freesasa_parameters.

freesasa_result *result = freesasa_calc_structure(structure, NULL);
printf("Total area: %f A2\n",result->total);
freesasa_result * freesasa_calc_structure(const freesasa_structure *structure, const freesasa_parameters *parameters)
Calculates SASA based on a given structure.
Struct to store results of SASA calculation.
Definition: freesasa.h:267
double total
Total SASA in Ångström^2.
Definition: freesasa.h:268

Get polar and apolar area

We are commonly interested in the polar and apolar areas of a molecule, this can be calculated by freesasa_result_classes(). To get other classes of atoms we can either define our own classifier, or use freesasa_select_area() defined in the next section. The return type freesasa_nodearea is a struct contains the total area and the area of all apolar and polar atoms, and main-chain and side-chain atoms.

freesasa_nodearea area = freesasa_result_classes(structure, result);
printf("Total : %f A2\n", area.total);
printf("Apolar : %f A2\n", area.apolar);
printf("Polar : %f A2\n", area.polar);
printf("Main-chain : %f A2\n", area.main_chain);
printf("Side-chain : %f A2\n", area.side_chain);
freesasa_nodearea freesasa_result_classes(const freesasa_structure *structure, const freesasa_result *result)
Results by classes.
Struct to store integrated SASA values for either a full structure or a subset thereof.
Definition: freesasa.h:289
double side_chain
Side-chain SASA.
Definition: freesasa.h:293
double apolar
Apolar SASA.
Definition: freesasa.h:295
double main_chain
Main-chain/Backbone SASA.
Definition: freesasa.h:292
double polar
Polar SASA.
Definition: freesasa.h:294
double total
Total SASA.
Definition: freesasa.h:291
See also
Specifying atomic radii and classes

Get area of custom groups of atoms

Groups of atoms can be defined using freesasa_selection_new(), which takes a selection definition uses a subset of the Pymol select syntax

freesasa_selection *selection =
freesasa_selection_new("aromatic, resn phe+tyr+trp+his+pro",
structure, result);
printf("Area of selection '%s': %f A2\n",
freesasa_selection * freesasa_selection_new(const char *command, const freesasa_structure *structure, const freesasa_result *result)
Get area of a selection.
struct freesasa_selection freesasa_selection
Selection struct.
Definition: freesasa.h:361
const char * freesasa_selection_name(const freesasa_selection *selection)
Name of the selection.
double freesasa_selection_area(const freesasa_selection *selection)
Area of the selection.
See also
Selection syntax

Navigating the results as a tree

In addition to the flat array of results in freesasa_result, and the global values returned by freesasa_result_classes(), FreeSASA has an interface for navigating the results as a tree. The leaf nodes are individual atoms, and there are parent nodes at the residue, chain, and structure levels. The function freesasa_calc_tree() does a SASA calculation and returns the root node of such a tree. (If one already has a freesasa_result the function freesasa_tree_init() can be used instead). Each node stores a freesasa_nodearea for the sum of all atoms belonging to the node. The tree can be traversed with freesasa_node_children(), freesasa_node_parent() and freesasa_node_next(), and the area, type and name using freesasa_node_area(), freesasa_node_type() and freesasa_node_name(). Additionally there are special properties for each level of the tree.

See also
Node

Exporting to RSA, JSON and XML

The tree structure can also be exported to an RSA, JSON or XML file using freesasa_tree_export(). The RSA format is fixed, but the user can select which levels of the tree to include in JSON and XML. The following illustrates how one would generate a tree and export it to XML, including nodes for the whole structure, chains and residues (but excluding individual atoms).

FILE *file = fopen("output.xml", "w");
fclose(file);
freesasa_node * freesasa_calc_tree(const freesasa_structure *structure, const freesasa_parameters *parameters, const char *name)
Calculates SASA for a structure and returns as a tree of freesasa_node.
const freesasa_parameters freesasa_default_parameters
The default parameters for FreeSASA.
int freesasa_node_free(freesasa_node *root)
Free tree.
struct freesasa_node freesasa_node
Result node.
Definition: freesasa.h:352
int freesasa_tree_export(FILE *output, freesasa_node *root, int options)
Outputs result in format specified by options.
@ FREESASA_XML
XML output.
Definition: freesasa.h:208
@ FREESASA_OUTPUT_RESIDUE
Output data for residues, chains and structure.
Definition: freesasa.h:202

Coordinates

If users wish to supply their own coordinates and radii, these are accepted as arrays of doubles passed to the function freesasa_calc_coord(). The coordinate-array should have size 3*n with coordinates in the order x1,y1,z1,x2,y2,z2,...,xn,yn,zn.

double coord[] = {1.0, /* x */
2.0, /* y */
3.0 /* z */ };
double radius[] = {2.0};
int n_atoms = 1;
freesasa_result *result = freesasa_calc_coord(coord, radius, n_atoms, NULL);
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.

Error-handling

The principle for error handling is that unpredictable errors should not cause a crash, but rather allow the user to exit gracefully or make another attempt. Therefore, errors due to user or system failures, such as faulty parameters, malformatted config-files, I/O errors or out of memory errors, are reported through return values, either FREESASA_FAIL or FREESASA_WARN, or by NULL pointers, depending on the context (see the documentation for the individual functions).

Errors that are attributable to programmers using the library, such as passing null pointers where not allowed, are checked by asserts.

Thread-safety

The only global state the library stores is the verbosity level (set by freesasa_set_verbosity()) and the pointer to the error-log (defaults to stderr, can be changed by freesasa_set_err_out()).

It should be clear from the documentation when the other functions have side effects such as memory allocation and I/O, and thread-safety should generally not be an issue (to the extent that your C library has threadsafe I/O and dynamic memory allocation). The SASA calculation itself can be parallelized by using a freesasa_parameters struct with freesasa_parameters.n_threads > 1 (default is 2) where appropriate. This only gives a significant effect on performance for large proteins or at high precision, and because not all steps are parallelized it is usually not worth it to go beyond 2 threads.

Customizing behavior

The types freesasa_parameters and freesasa_classifier can be used to change the parameters of the calculations. Users who wish to use the defaults can pass NULL wherever pointers to these are requested.

Parameters

Calculation parameters can be stored in a freesasa_parameters object. It can be initialized to default by

Struct to store parameters for SASA calculation.
Definition: freesasa.h:232

The following code would run a high precision Shrake & Rupley calculation with 10000 test points on the provided structure.

param.shrake_rupley_n_points = 10000;
freesasa_result *result = freesasa_calc_structure(structure, param);
@ FREESASA_SHRAKE_RUPLEY
Shrake & Rupley's algorithm.
Definition: freesasa.h:91
freesasa_algorithm alg
Algorithm.
Definition: freesasa.h:233
int shrake_rupley_n_points
Number of test points in S&R calculation.
Definition: freesasa.h:235

Specifying atomic radii and classes

Classifiers are used to determine which atoms are polar or apolar, and to specify atomic radii. In addition the three standard classifiers (see below) have reference values for the maximum areas of the 20 standard amino acids which can be used to calculate relative areas of residues, as in the RSA output.

The default classifier is available through the const variable ::freesasa*default_classifier. This uses the _ProtOr* radii, defined in the paper by Tsai et al. (JMB 1999, 290: 253) for the standard amino acids (20 regular plus SEC, PYL, ASX and GLX), for some capping groups (ACE/NH2) and the standard nucleic acids. If the element can't be determined or is unknown, a zero radius is assigned. It classes all carbons as apolar and all other known atoms as polar.

Early versions of FreeSASA used the atomic radii by Ooi et al. (PNAS 1987, 84: 3086-3090), this classifier is still available through freesasa_oons_classifier.

Users can provide their own classifiers through Classifier configuration files. At the moment these do not allow the user to specify reference values to calculate relative SASA values for RSA output.

The default behavior of freesasa_structure_from_pdb(), freesasa_structure_array(), freesasa_structure_add_atom() and freesasa_structure_add_atom_wopt() is to first try the provided classifier and then guess the radius if necessary (emitting warnings if this is done, uses VdW radii defined by Mantina et al. J Phys Chem 2009, 113:5806).

See the documentation for these functions for what parameters to use to change the default behavior.