FreeSASA: An open source C library for solvent accessible surface area calculations

Implementation

Calculations. Both S&R and L&R are pretty straightforward to implement, and both require first determining which atoms are in contact, and then calculating the overlap between each atom and its neighbors. Finding contacts is done using cell lists, which means the contact calculation is an O(N) operation. Both algorithms then treat each atom independently, making also the second part of the calculation O(N). In addition, this second part is trivially parallelizable.

For L&R, instead of slicing the whole protein in one go, each atom is sliced individually. The L&R calculation is thus parameterized by the number of slices per atom, i.e. small atoms have thinner slices than large atoms.

The Fibonacci spiral gives a good approximation to an even distribution of points on the sphere (Swinbank & Purser, 2006), allowing efficient generation of an arbitrary number of S&R test points. The cell lists provide the first of the two lattices in the double cubic lattice optimization for this algorithm (Eisenhaber et al., 1995), the second lattice (for the test points) is not implemented in FreeSASA, for now.

The correctness of the implementations was tested by first inspecting the surfaces visually. In the two atom case, results were verified against analytical calculations. Another verification came from comparing the results of high precision SASA calculations using the two independent algorithms. In addition, using the L&R algorithm gives identical results to NACCESS when the same resolution and atomic radii are used.

Radius assignment. An important step of the calculation is assigning a radius to each atom. The default in FreeSASA is to use the ProtOr radii by Tsai et al. (1999). The library recognizes the 20 standard amino acids (plus Sec and Pyl), and the standard nucleotides (plus a few nonstandard ones). Tsai et al. do not mention phosphorus and selenium; these atoms are assigned a radius of 1.8 and 1.9 Å respectively.

By default, hydrogen atoms and HETATM records are ignored in Protein Data Bank (PDB) files. If included, the library recognizes three common HETATM entries: the acetyl and NH₂ capping groups, and water, and assigns ProtOr radii to these. Otherwise the van der Waals radius of the element is used, taken from the paper by Mantina et al. (2009). For elements outside of the 44 main group elements treated by Mantina et al., or if completely different radii are desired, users can provide their own configuration.

Users can specify their own atomic radii either through the API or by providing a configuration file. The library ships with a few sample configuration files, including one that provides a subset of the NACCESS parameterization, and one with the default ProtOr parameters. In addition, scripts are provided to automatically generate ProtOr configurations from PDB CONECT entries, such as those in the Chemical Component Dictionary (Westbrook et al., 2015). These can then be appended to the default configuration.

Operation

Building the FreeSASA library and command-line interface only requires standard C and GNU libraries and a C99-compliant compiler, and should be straightforward on any UNIX system (has been tested in Mac OS X 10.8 and Debian 8), and not too difficult in Windows (not tested). Building the Python bindings requires Cython (tested with version 0.21). The library ships with an Autotools build configuration, but the source itself is simple enough to be possible to compile “manually”, if necessary.

Command-line interface. Building FreeSASA creates the binary freesasa. The simplest program call, with default parameters, is

   $ freesasa 3wbm.pdb

using the structure with PDB code 3wbm as an example (a protein-RNA complex). The above produces the following output

   ## freesasa 1.0.1 ##

   PARAMETERS
   algorithm    : Lee & Richards
   probe-radius : 1.400
   threads      : 2
   slices       : 20

   INPUT
   source  : 3wbm.pdb
   chains  : ABCDXY
   atoms   : 3714

   RESULTS (A^2)
   Total   : 25190.77
   Apolar  : 11552.38
   Polar   : 13638.39
   CHAIN A :  3785.49
   CHAIN B :  4342.33
   CHAIN C :  3961.12
   CHAIN D :  4904.30
   CHAIN X :  4156.46
   CHAIN Y :  4041.08

The numbers in the results section are the SASA values (in Ų) for the respective groups of atoms.

As an illustration of a few of the other configuration options, and how to use the program as a PDB file filter, the command

   $ freesasa -n 100 --print-as-B-values --no-log < 3wbm.pdb > 3wbm.sasa

calculates the SASA of a PDB-file passed via stdin, using 100 slices per atom. The flag --no-log suppresses the regular output. The output will instead, because of the flag --print-as-B-values, be the provided PDB-file with the SASA of each atom replacing the temperature factors, and the atomic radii stored in the occupancy factor field.

By calling with the option --chain-groups,

   $ freesasa --chain-groups=ABCD+XY 3wbm.pdb

two calculations are appended to the original output, one where only the four chains A, B, C and D have been included, and one with only X and Y.

The option --select can be used to select a set of atoms using a subset of the selection syntax used in the program Pymol (DeLano, 2002). For example, the command

   $ freesasa --select="RNA, resn A+U+G+C"

will produce the following output (after the regular output shown above)

   SELECTIONS
   RNA :    8197.53

where RNA is simply the user-defined name of the selection, and the number the contribution to the total SASA from the bases A, U, G and C (which we in this particular case could have got by simply adding the areas for the chains X and Y in the sample output above).

The command

   $ freesasa -h

prints a help message listing all available options, including other ways to redirect output and how to change different calculation parameters (the most detailed information can be found online at http://freesasa.github.io/doxygen/CLI.html).

C API. The C code below illustrates how to perform a SASA-calculation on the same PDB-file as above, using the C API, with default parameters. The functions and types used are all defined in the header freesasa.h.

   FILE *fp = fopen("3wbm.pdb","r");
   freesasa_structure *structure = freesasa_structure_from_pdb(fp, NULL, 0);
   freesasa_result *result = freesasa_calc_structure(structure, NULL);
   printf("Total area : %f A2\n", result->total);

The two points where null pointers are passed as arguments are places where atom classifiers and calculation parameters could have been provided. A more elaborate example that includes error handling and freeing of allocated resources can be seen in Figure 1.

Figure 1. C API.

Illustration of how to use the C API including rudimentary error handling.

The API also allows the user to calculate the SASA of a set of coordinates with associated radii. The code below puts two atoms at positions ${\overrightarrow{x}}_1=(1,1,1)$ and ${\overrightarrow{x}}_2=(2,2,2)$ with radii r₁ = 2 and r₂ = 3, respectively, and outputs the SASA of the individual atoms.

   double coord[] = {1.0, 1.0, 1.0, 2.0, 2.0, 2.0};
   double radius[] = {2.0, 3.0};
   freesasa_result *result = freesasa_calc_coord(coord, radius, 2, NULL);
   printf("A1 = %f, A2 = %f\n", result->sasa[0], result->sasa[1]);

Python API. The library includes Python bindings that export most of the C API to Python. The Python code below gives the same output as the example in Figure 1. Error handling is excluded for brevity.

   import freesasa

   structure = freesasa.Structure("3wbm.pdb")
   result = freesasa.calc(structure)
   classArea = freesasa.classifyResults(result,structure)

   print "Total : %.2f A2" % result.totalArea()
   for key in classArea:
       print key, ": %.2f A2" % classArea[key]

Data

F1000Research: Dataset 1. List of PDB codes used for the performance analysis, 10.5256/f1000research.7931.d112977 (Mitternacht, 2016a).

F1000Research: Dataset 2. Zip-archive with raw data for the performance analysis in Figure 2 and Figure 3, 10.5256/f1000research.7931.d112978 (Mitternacht, 2016b).

Software

Latest source code and software available from http://freesasa.github.io/

Archived source code as at the time of publication http://dx.doi.org/10.5281/zenodo.45239 (Mitternacht, 2016c).

License GNU GPL v3 (http://www.gnu.org/licenses/gpl-3.0.en.html).