FreeSASA  1.1 Open source SASA calculations View on GitHub
Command-line Interface

Building FreeSASA creates the binary freesasa, which is installed by make install. Calling

$freesasa -h  displays a help message listing all options. The following text explains how to use most of them. # Run using defaults In the following we will use the RNA/protein complex PDB structure 3WBM as an example. It has four protein chains A, B, C and D, and two RNA strands X and Y. To run a simple SASA calculation using default parameters, simply type: $ freesasa 3wbm.pdb


This generates the following output

PARAMETERS
algorithm    : Lee & Richards
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 results are all in the unit Ångström-squared.

# Changing parameters

If higher precision is needed, the command

$freesasa -n 100 3wbm.pdb  specifies that the calculation should use 100 slices per atom instead of the default 20. The command $ freesasa --shrake-rupley -n 200 --probe-radius 1.2 --n-threads 4 3wbm.pdb


instead calculates the SASA using Shrake & Rupley's algorithm with 200 test points, a probe radius of 1.2 Å, using 4 parallel threads to speed things up.

If the user wants to use their own atomic radii the command

$freesasa --config-file <file> 3wbm.pdb  Reads a configuration from a file and uses it to assign atomic radii. The program will halt if it encounters atoms in the PDB input that are not present in the configuration. See Classifier configuration files for instructions how to write a configuration. To use the atomic radii from NACCESS call $ freesasa --radii=naccess 3wbm.pdb


Another way to specify a custom set of atomic radii is to store them as occupancies in the input PDB file

$freesasa --radius-from-occupancy 3wbm.pdb  This option allows the user to first use either of the options --print-as-B-values or --B-value-file to write generate a PDB file with the radii used in the calculation, modify the radii of individual atoms in that file, and the recalculate the SASA with these modified radii. # Other output types ## SASA for each residue(-type) To calculate the SASA of each residue in the sequence, or each residue type, use the following commands (--no-log suppresses the standard output shown above): $ freesasa --foreach-residue --no-log 3wbm.pdb
SEQ A    5 THR :  138.48
SEQ A    6 PRO :   25.53
SEQ A    7 THR :   99.42
...


and

$freesasa --foreach-residue-type --no-log 3wbm.pdb RES ALA : 251.57 RES ARG : 2868.98 RES ASN : 1218.87 ... RES A : 1581.57 RES C : 2967.12 RES G : 1955.16 RES U : 1693.68  ## SASA for each atom The command-line interface can also be used as a PDB filter: $ cat 3wbm.pdb | freesasa --no-log --print-as-B-values
ATOM      1  N   THR A   5     -19.727  29.259  13.573  1.64  9.44
ATOM      2  CA  THR A   5     -19.209  28.356  14.602  1.88  5.01
ATOM      3  C   THR A   5     -18.747  26.968  14.116  1.61  0.40
...


The output is a PDB-file where the temperature factors have been replaced by SASA values (last column), and occupancy numbers by the radius of each atom (second to last column).

Only the atoms and models used in the calculation will be present in the output (see PDB input for how to modify this).

## Several types of output at once

To generate all three results at the same time and write them to separate files, run

$freesasa --residue-file=3wbm.seq --residue-type-file=3wbm.res --B-value-file=3wbm.b 3wbm.pdb  ## Relative SASA values The CLI can also produce output similar to the RSA format from NACCESS using the options --rsa and --rsa-file. This format includes both absolute SASA values (ABS) and relative ones (REL) compared to a precalculated reference max value. The only significant difference between FreeSASA's RSA output format and that of NACCESS (except differences in areas due to different atomic radii), is that FreeSASA will print the value "N/A" where NACCESS prints "-99.9". $ freesasa 3wbm.pdb --rsa --no-log
REM RES _ NUM      All-atoms   Total-Side   Main-Chain    Non-polar    All polar
REM                ABS   REL    ABS   REL    ABS   REL    ABS   REL    ABS   REL
RES THR A   5   138.48 104.1  99.58 107.4  38.90  96.3  81.59  98.1  56.89 114.0
RES PRO A   6    25.53  19.3  11.31  11.0  14.23  47.7  21.67  18.7   3.86  23.9
...
RES GLY A  15     0.64   0.9   0.00   N/A   0.64   0.9   0.00   0.0   0.64   2.0
...
RES   U Y  23   165.16   N/A 165.16   N/A   0.00   N/A  52.01   N/A 113.15   N/A
RES   C Y  24   165.01   N/A 165.01   N/A   0.00   N/A  46.24   N/A 118.77   N/A
RES   C Y  25   262.46   N/A 262.46   N/A   0.00   N/A  85.93   N/A 176.52   N/A
END  Absolute sums over single chains surface
CHAIN  1 A     3785.5       3062.1        723.3       2051.6       1733.9
CHAIN  2 B     4342.3       3488.6        853.7       2385.2       1957.1
CHAIN  3 C     3961.1       3178.5        782.7       2122.4       1838.7
CHAIN  4 D     4904.3       3926.8        977.5       2572.0       2332.3
CHAIN  5 X     4156.5       4156.5          0.0       1236.9       2919.6
CHAIN  6 Y     4041.1       4041.1          0.0       1184.3       2856.8
END  Absolute sums over all chains
TOTAL         25190.8      21853.6       3337.2      11552.4      13638.4


Note that each RES is a single residue, not a residue type as above (i.e. has the same meaning as SEQ above). This unfortunate confusion of labels is due to RSA support being added much later than the other options. Fixing it now would break the interface, and will thus earliest be dealt with in the next major release.

To calculate the REL values a reference SASA value is needed, calculated using the same atomic radii. At the moment such values are only available for the ProtOr and NACCESS radii (selected using the option --radii), if other radii are used all REL columns will have the value 'N/A'.

The reference SASA values for residue X are calculated from Ala-X-Ala peptides in a stretched out configuration. The reference configurations are supplied for reference in the directory rsa. Since these are not always the most exposed possible configuration, and because bond lengths and bond angles vary, the relative SASA values will sometimes be larger than 100 %. At the moment there is no interface to supply user-defined reference values.

### Using the NACCESS configuration

The reference values for the NACCESS configuration in FreeSASA are not exactly the same as those that ship with NACCESS, but have been calculated from scratch using the tripeptides that ship with FreeSASA. Calling

$freesasa 3wbm.pdb --rsa-file=3wbm.rsa --radii=naccess --no-log  will give an RSA file where the ABS columns are identical to NACCESS (run with the flag -b) for the amino acids, and for nucleic acids the definition of backbone differs (no nucleic acid backbone has been defined in FreeSASA). REL values will differ slightly, due to the differences in reference values above. # Selecting groups of atoms The option --select can be used to define groups of atoms whose integrated SASA we are interested in. It uses a subset of the Pymol select command syntax, see Selection syntax for full documentation. The following example shows how to calculate the sum of exposed surface areas of all aromatic residues and of the four chains A, B, C and D (just the sum of the areas above). $ freesasa --select "aromatic, resn phe+tyr+trp+his+pro" --select "abcd, chain A+B+C+D" 3wbm.pdb
...
SELECTIONS
freesasa: warning: Found no matches to resn 'TRP', typo?
freesasa: warning: Found no matches to resn 'HIS', typo?
aromatic :    1196.45
abcd :   16993.24


The lines shown above are appended to the regular output. This particular protein did not have any TRP or HIS residues, hence the warnings (written to stderr). The warnings can be supressed with the flag -w.

# Analyzing groups of chains

Calculating the SASA of a given chain or group of chains separately from the rest of the structure, can be useful for measuring how buried a chain is in a given structure. The option --chain-groups can be used to do such a separate calculation, calling

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


produces the regular output for the structure 3WBM, but in addition it runs a separate calculation for the chains A, B, C and D as though X and Y aren't in the structure, and vice versa:

PARAMETERS
algorithm    : Lee & Richards
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

####################

INPUT
source  : 3wbm.pdb
chains  : ABCD
atoms   : 2664

RESULTS (A^2)
Total   :   18202.78
Apolar  :    9799.46
Polar   :    8403.32
CHAIN A :    4243.12
CHAIN B :    4595.18
CHAIN C :    4427.11
CHAIN D :    4937.38

####################

INPUT
source  : 3wbm.pdb
chains  : XY
atoms   : 1050

RESULTS (A^2)
Total   :    9396.28
Apolar  :    2743.09
Polar   :    6653.19
CHAIN X :    4714.45
CHAIN Y :    4681.83


# PDB input

## Including extra atoms

The user can ask to include hydrogen atoms and HETATM entries in the calculation using the options --hydrogen and --hetatm. In both cases adding unknown atoms will emit a warning for each atom. This can either be amended by using the flag '-w' to suppress warnings, or by using a custom classifier so that they are recognized (see Classifier configuration files).

## Skipping unknown atoms

By default FreeSASA guesses the element of an unknown atom and uses that elements VdW radius. If this fails the radius is set to 0 (and hence the atom will not contribute to the calculated area). Users can request to either skip unknown atoms completely (i.e. no guessing) or to halt when unknown atoms are found and exit with an error. This is done with the option --unknown which takes one of the three arguments skip, halt or guess (default). Whenever an unknown atom is skipped or its radius is guessed a warning is printed to stderr.

## Separating and joining chains and models

If a PDB file has several chains and/or models, by default all chains of the first model are used, and the rest of the file is ignored. This behavior can be modified using the following options

• --join-models: Joins all models in the input into one large structure. Useful for biological assembly files were different locations of the same chain in the oligomer are represented by different MODEL entries.
• --separate-models: Calculate SASA separately for each model in the input. Useful when the same file contains several conformations of the same molecule.
• --separate-chains: Calculate SASA separately for each chain in the input. Can be joined with --separate-models to calculate SASA of each chain in each model.
• --chain-groups: see Analyzing groups of chains