FreeSASA API

Basics

The API is found in the header freesasa.h and this is the only header installed by make install. The other source-files and headers in the repository are for internal use, and are not present 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 second and third arguments can be changed to use a custom freesasa_classifier to define radii and to specify options for what to include in the PDB file, respectively.

FILE *fp = fopen("1abc.pdb");
freesasa_structure *structure = freesasa_structure_from_pdb(fp, NULL, 0);

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

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_classify(). Again, passing a NULL freesasa_classifier uses the default. 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_strvp contains arrays of strings and values describing the different classes, as illustrated below.

freesasa_strvp *class_area = freesasa_result_classify(result, structure, NULL);
for (int i = 0; i < class_area->n; ++i)
    printf("%s: %f A2\n", class_area->string[i], class_area->value[i]);

See also

Specifying atomic radii and classes

Get area of custom groups of atoms

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

double area;
char name[FREESASA_MAX_SELECTION_NAME+1];
freesasa_select_area("aromatic, resn phe+tyr+trp+his+pro",
                     name, &area, structure, result);
printf("Area of selection '%s': %f A2\n", name, area);

See also

Selection syntax.

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

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. If memory allocation fails as much memory as possible is released. To the extent that it's possible to emulate system failures like this, they have been verified to not cause aborts or seg-faults (see the tests/ directory) in any part of the code.

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 passing a freesasa_parameters struct with freesasa_parameters.n_threads set to a value > 1 (default is 2) to freesasa_calc_structure() or freesasa_calc_coord(). 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

Changing parameters is done by passing a freesasa_parameters object with the desired values. It can be initialized to default by

freesasa_parameters param = freesasa_default_parameters;

To allow the user to only change the parameters that are non-default.

The following call would run a high precision Shrake & Rupley calculation with 10000 test points

param.alg = FREESASA_SHRAKE_RUPLEY;
param.shrake_rupley_n_points = 10000;
freesasa_result *result = freesasa_calc_structure(structure,radii,param);

Specifying atomic radii and classes

The type freesasa_classifier has function pointers to functions that take residue and atom names as argument (pairs such as "ALA","CA"), and returns a radius or a class (polar, apolar, etc). The classifier can be passed to freesasa_structure_from_pdb(), freesasa_structure_array() or freesasa_structure_add_atom_wopt() to customize the radii assigned to atoms, which can then be used to calculate the SASA of the structure. It can also be used in freesasa_result_classify() to get the SASA integrated over the different classes of atoms, i.e. the SASA of all polar atoms, etc.

Users of the API can provide their own classification by writing their own functions and providing them via a freesasa_classifier object. A classifier-configuration can also be read from a file using freesasa_classifier_from_file() (see Classifier configuration files).

The default classifier is available through the const variable freesasa_default_classifier. This uses the 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 nucleic acids. If the element can't be determined or is unknown, a negative radius is returned. 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, this classifier is still available through freesasa_classifier_oons().

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 default 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](http://www.ncbi.nlm.nih.gov/pmc/articles/PMC3658832/)).

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