FreeSASA  2.0.2
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

## FreeSASA 2.0 ##

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 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 the option --format=pdb (see PDB) to write generate a PDB file with the radii used in the calculation, modify the radii of individual atoms in that file, and then recalculate the SASA with these modified radii.

Output formats

In addition to the standard output format above FreeSASA can export the results as JSON, XML, PDB, RSA, SASA of each residue type and SASA of each residue using the option --format. The level of detail of JSON and XML output can be controlled with the option --output-depth=<depth> which takes the values atom, residue, chain and structure. If atom is chosen, SASA values are shown for all levels of the structure, including individual atoms. With chain, only structure and chain SASA values are printed (this is the default).

The output can include relative SASA values for each residues. To calculate these 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 relative SASA will be excluded (in RSA output 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.

JSON

The command

$ freesasa --format=xml --output-depth=residue 3wbm.pdb

generates the following

1 {
2  "source":"FreeSASA 2.0",
3  "length-unit":"Ångström",
4  "results":[
5  {
6  "input":"3wbm.pdb",
7  "classifier":"ProtOr",
8  "parameters":{
9  "algorithm":"Lee & Richards",
10  "probe-radius":1.3999999999999999,
11  "resolution":20
12  },
13  "structures":[
14  {
15  "chain-labels":"ABCDXY",
16  "area":{
17  "total":25190.768387067546,
18  "polar":13638.391677017404,
19  "apolar":11552.376710050148,
20  "main-chain":3337.1622502425053,
21  "side-chain":21853.606136825045
22  },
23  "chains":[
24  {
25  "label":"A",
26  "n-residues":86,
27  "area":{
28  "total":3785.4864049452635,
29  "polar":1733.8560208488598,
30  "apolar":2051.6303840964056,
31  "main-chain":723.34358684348558,
32  "side-chain":3062.1428181017791
33  }
34  "residues":[
35  {
36  "name":"THR",
37  "number":"5",
38  "area":{
39  "total":138.48216994006549,
40  "polar":56.887951514571867,
41  "apolar":81.594218425493622,
42  "main-chain":38.898190013033592,
43  "side-chain":99.583979927031905
44  },
45  "relative-area":{
46  "total":104.05152148175331,
47  "polar":113.98106895325961,
48  "apolar":98.093554250413092,
49  "main-chain":96.330336832673567,
50  "side-chain":107.414496739329
51  },
52  "n-atoms":7
53  },
54 
55  ...
56 
57  },
58 
59  ...
60 
61  ]
62  }
63  ]
64  }
65  ]
66 }

Where ellipsis indicates the remaining residues and chains.

XML

The command

$ freesasa --format=xml 3wbm.pdb

Generates the following

1 <?xml version="1.0" encoding="UTF-8"?>
2 <results xmlns="http://freesasa.github.io/" source="FreeSASA 2.0" lengthUnit="&#xC5;ngstr&#xF6;m">
3  <result classifier="ProtOr" input="3wbm.pdb">
4  <parameters algorithm="Lee &amp; Richards" probeRadius="1.400000" resolution="20"/>
5  <structure chains="ABCDXY">
6  <area total="25190.768" polar="13638.392" apolar="11552.377" mainChain="3337.162" sideChain="21853.606"/>
7  <chain label="A" nResidues="86">
8  <area total="3785.486" polar="1733.856" apolar="2051.630" mainChain="723.344" sideChain="3062.143"/>
9  </chain>
10  <chain label="B" nResidues="84">
11  <area total="4342.334" polar="1957.114" apolar="2385.220" mainChain="853.707" sideChain="3488.627"/>
12  </chain>
13  <chain label="C" nResidues="86">
14  <area total="3961.119" polar="1838.724" apolar="2122.395" mainChain="782.652" sideChain="3178.468"/>
15  </chain>
16  <chain label="D" nResidues="89">
17  <area total="4904.298" polar="2332.306" apolar="2571.991" mainChain="977.459" sideChain="3926.838"/>
18  </chain>
19  <chain label="X" nResidues="25">
20  <area total="4156.455" polar="2919.576" apolar="1236.879" mainChain="0.000" sideChain="4156.455"/>
21  </chain>
22  <chain label="Y" nResidues="25">
23  <area total="4041.076" polar="2856.815" apolar="1184.261" mainChain="0.000" sideChain="4041.076"/>
24  </chain>
25  </structure>
26  </result>
27 </results>

PDB

The command-line interface can also be used as a PDB filter:

$ cat 3wbm.pdb | freesasa --format=pdb
REMARK 999 This PDB file was generated by FreeSASA 2.0.
REMARK 999 In the ATOM records temperature factors have been
REMARK 999 replaced by the SASA of the atom, and the occupancy
REMARK 999 by the radius used in the calculation.
MODEL        1
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).

SASA of each residue type

Calculate the SASA of each residue type:

$ freesasa --format=res 3wbm.pdb
# Residue types in 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 of each residue

Calculate the SASA of each residue in the sequence:

$ freesasa --format=seq 3wbm.pdb
# Residues in 3wbm.pdb
SEQ A    5 THR :  138.48
SEQ A    6 PRO :   25.53
SEQ A    7 THR :   99.42
...

RSA

The CLI can also produce output similar to the RSA format from NACCESS. This format includes both absolute SASA values (ABS) and relative ones (REL) compared to a precalculated reference max value. The main difference between FreeSASA's RSA output format and that of NACCESS, is that FreeSASA will print the value "N/A" where NACCESS prints "-99.9", when the a reference value for REL is missing.

$ freesasa --format=rsa 3wbm.pdb
REM  FreeSASA 2.0
REM  Absolute and relative SASAs for 3wbm.pdb
REM  Atomic radii and reference values for relative SASA: ProtOr
REM  Chains: ABCDXY
REM  Algorithm: Lee & Richards
REM  Probe-radius: 1.40
REM  Slices: 20
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.

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 using the same Ala-X-Ala tripeptides (kindly donated by the creators of NACCESS). By default NACCESS defines amino acid CA atoms as side-chain, whereas FreeSASA defines them as main-chain. The flag -b defines CA as main-chain in NACCESS.

Calling

$ freesasa 3wbm.pdb -n 20--format=rsa --radii=naccess

will give an RSA file where the ABS columns should be identical to NACCESS with flag -b. All REL values will differ slightly because of round-off errors in the references. The difference will be large for side-/main-chain REL values, since the FreeSASA references were calculated with CA as main-chain. NACCESS also gives different results for the nucleic acid main-chain and side-chain. FreeSASA defines the (deoxy)ribose and phosphate groups as main-chain and the base as side-chain.

Future versions might allow specifying what atoms are main-chain through the configuration file, and letting the user set their own reference values.

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


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

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