<commit_before>\documentclass[a4paper,11pt]{article}
\usepackage[utf8]{inputenc}
\usepackage[OT1]{fontenc}
\usepackage[english]{babel}
\usepackage[margin=1.2in]{geometry}
\usepackage{graphicx}
\usepackage{amsmath}
\usepackage{cite}
\usepackage[perpage,symbol]{footmisc}
\usepackage[hang,small]{caption}
\usepackage{parskip}
\usepackage{array}
\usepackage{pstricks}

%\usepackage{fancyvrb}

\author{<NAME>} 
\date{\today} 
\title{Sasalib: An Open Source C Library for Solvent Accesible Surface
  Calculations}

\begin{document}
\maketitle
\hrule\vspace{0.5cm}
\noindent
The program/library Sasalib, including this manual, is licensed under
GPLv3, and can be downloaded from github at: 
\begin{center}
\texttt{https://github.com/mittinatten/sasalib/}
\end{center}
NB: This document a draft and slowly approaching completeness.
\vspace{0.5cm}
\hrule
\section{Introduction}
The Solvent Accessible Surface Area (SASA) of a molecule gives a
measure of the surface of the molecule in contact with solvent. This
area can for example quantify how folded the conformation of a
macromolecule is, and can also be used to compare the exposed
hydrophobic surfaces of different conformations or different
molecules. To define the SASA, $A$, of a given molecule, let a spherical
probe roll over the surface of the molecule, including internal
cavities. $A$ is then the surface drawn by the center of the
probe.~\cite{LnR} The probe represents a solvent molecule
(i.e.\ water), and therefore cavities smaller than the solvent
molecule do not contribute to $A$.

Calculating Solvent Accessible Surface Areas (SASA) is a
run-of-the-mill calculation in protein structure studies. To the
author's knowledge there are no fully open source standalone programs
for doing this. Neither are there any libraries designed to be easily
integrated in other programs. The present library is an attempt to
resolve both these issues, and is released under the GNU General
Public License 3\footnote{See http://www.gnu.org/licenses/gpl.html}.

Sasalib is a both a standalone command line program and a C library
for protein SASA calculations. The library provides a simple interface
that takes PDB-files as input. It has default parameters to allow
straightforward calculations, but also allows the user to change most
parameters of the calculation. In addition, there is a lower level
interface where the user can treat the calculation as a purely
mathematical operation on a set of spheres, specifying only
coordinates and radii. Both <NAME>' \cite{LnR} and Shrake \&
Rupley's \cite{SnR} algorithms are available. They will be referred to
as L\&R and S\&R throughout this document. Future versions of the
library might include other algorithms as well.

In constructing the library three possible use cases were considered. 
\begin{enumerate}
\item The user has a PDB-file and wishes to calculate the total SASA of
  the structure, or the SASA for certain groups or types of atoms.
\item The user has a set of cartesian atom coordinates and radii for
  these atoms, and wants to calculate the total SASA for this object.
\item The user is simulating different conformations of a molecule and
  wants to measure the SASA at certain intervals during the simulation.
\end{enumerate}
For case 1 both the command-line interface (CLI) and the application
programming interface (API) can be used. Using the API gives more
flexibility in interpreting and analyzing the results. The other 2
cases can only be handled through the API. Both the API and the CLI
allow the user to set parameters for the calculation. 

A lot of the internals of the library are involved with classification
and categorization of atoms, which is necessary for assigning radii
and to present SASA values integrated over different atom types, amino
acid types, etc. If the user wants Sasalib to classify atoms and
assign radii, data in the PDB-format must be provided. Users can also
provide their own radii and coordinates, and get the SASA for each
individual atom.

This document is organized as follows. Section \ref{sec:howto_short}
gives a brief introduction to the library, presenting the command line
interface and a short sample program that gives a general idea of how
to use the library. The introduction is intended to cover most casual
users' needs. Section \ref{sec:alg} describes the algorithms and
compares their performance in terms of computational cost and
precision. In section \ref{sec:imp} the implementations are
described. Finally, section \ref{sec:using} gives a detailed
description of the API.

\section{Getting started}\label{sec:howto_short}

The source files \texttt{calc\_sasa.c} and \texttt{example.c} contain
a complete command-line interface and a minimal program to illustrate
how to use the library interface, respectively. 

\subsection{Installation} \label{sec:installing}

The repository can be cloned from github, either by using git directly
with the command
\begin{verbatim}
    $ git clone https://github.com/mittinatten/sasalib.git
\end{verbatim}
or by downloading the zipped archive from
\begin{verbatim}
    https://github.com/mittinatten/sasalib/archive/master.zip
\end{verbatim}
Since Sasalib only depends on regular C and GNU libraries most users
will be able to compile it by simply typing \texttt{make}\footnote{Has
  been tested in Linux and Mac OS X.}. If any compiler other than the
Gnu C Compiler is preferred the makefile will need to be changed
accordingly. The command \texttt{make example} compiles the example
program described in section \ref{sec:simple_sample}. There is no
\texttt{make install} at the moment.

\subsection{Command-line interface}

Compilation creates the binary \texttt{calc\_sasa} from
\texttt{calc\_sasa.c}, which can be used to calculate the SASA of a
PDB-file. The simplest program call, with default parameters would be
\begin{verbatim}
    $ ./calc_sasa PDB-file
\end{verbatim}
Or, from STDIN:
\begin{verbatim} 
    $ ./calc_sasa < PDB-file    
\end{verbatim}
STDIN is only read if no file is specified.  By default the Shrake \&
Rupley algorithm is used, with 100 test points. 

\subsubsection{Options}
The following options are available
\begin{itemize}
  \item[-h] Prints help message.
  \item[-S] Use Shrake \& Rupley algorithm (default).
  \item[-L] Use Lee \& Richards algorithm.
  \item[-n] Number of test points in Shrake \& Rupley algorithm.
    Default is 100, allowed values are: 20, 50, 100, 200, 500, 1000,
    2000, 5000.
  \item[-d] Grid spacing in Lee \& Richards algorithm.
  Default value is 0.25 Å.
  \item[-t] Number of threads to use in calculation (for multicore
    CPUs). See section \ref{sec:speed} for a discussion of when this
    has a significant effect on performance.
  \item[-r] Print SASA for each residue.
  \item[-B] Print PDB file where the SASA value of each atom is
    written as its B factor (the output file is provided as an
    argument to the flag).
\end{itemize}
As an illustration, the command
\begin{verbatim}
   $ ./calc_sasa -L -d 0.1 -t 2 -r PDB-file
\end{verbatim}
calculates the SASA of the supplied pdb-file using Lee \& Richards,
with a slice width of 0.1 Å, using two threads (only makes sense for
CPUs with two or more cores) and will print the total SASA of each
residue type in addition to the standard output.

Several PDB-files can be analyzed in one call as, the results will be
printed consecutively for each input file:
\begin{verbatim}
   $ ./calc_sasa 1abc.pdb 2abc.pdb ...
\end{verbatim}
The calculations will not be run in parallel if the option '-t [n]' is
used, instead each calculation is parallelized individually.

\subsubsection{Output}
Running the program using the default parameters on the PDB structure
1UBQ gives the following output
\begin{verbatim}
    name: 1ubq.pdb
    algorithm: Shrake & Rupley
    n_thread: 1
    n_testpoint: 100
    time_elapsed: 0.019065 s
    n_atoms: 602

    Total:   4756.12 Å2
    Polar:   1968.06 Å2
    Apolar:   2788.07 Å2
\end{verbatim}
The first 4 lines contain info about input and parameters. This is
followed by data over calculation time and the size of the
protein. Finally the result of the calculation is printed, with SASA
values in Å$^2$.

\subsection{Simple example (\texttt{example.c})}\label{sec:simple_sample}

The following shows the minimal program \texttt{example.c} that
performs a SASA-calculation using a PDB-file as input. This program is
basically a stripped down version of \texttt{calc\_sasa.c} without
error handling, and without any commandline options. This code is
meant to illustrate the most basic parts of the library interface.
\begin{verbatim}
#include <stdlib.h>
#include "src/sasalib.h"

int main(int argc, char **argv) { 
    //initialize sasalib-object with default parameters
    sasalib_t *s = sasalib_init();

    //do the calculation using default parameters with protein
    //structure from STDIN
    sasalib_calc_pdb(s,stdin);

    //print results
    sasalib_log(stdout,s);
    printf("Total area: %f Å2\n", sasalib_area_total(s));

    //clean up
    sasalib_free(s);

    return EXIT_SUCCESS;
}
\end{verbatim}
This program generates results similar to that in the previous
section.

\section{Algorithms}\label{sec:alg}

There are two classical approximate algorithms that can be used to
calculate SASA, by Lee \& Richards \cite{LnR} and Shrake \& Rupley
\cite{SnR} respectively. Both can be calculated to arbitrary precision
by refining the resolution. 

As will be clear from this section and the analysis in section
\ref{sec:compare}, S\&R is the simpler and faster of the
two. Therefore the casual user is recommended to use S\&R. L\&R is
mainly included for reference, and for the fact that the precision is
only limited by floating point precision. In the current
implementation S\&R can only be used with a predefined set of levels
of precision. However, it is not obvious what applications would
require very high precision SASA values.

We will use the following notation: An atom $i$ has a van der Waals
radius $r_i$, the rolling sphere (or \emph{probe}) has radius<commit_msg>Fixed minor typos and updated to correspond to latest version of code.<commit_after>\documentclass[a4paper,11pt]{article}
\usepackage[utf8]{inputenc}
\usepackage[OT1]{fontenc}
\usepackage[english]{babel}
\usepackage[margin=1.2in]{geometry}
\usepackage{graphicx}
\usepackage{amsmath}
\usepackage{cite}
\usepackage[perpage,symbol]{footmisc}
\usepackage[hang,small]{caption}
\usepackage{parskip}
\usepackage{array}
\usepackage{pstricks}

%\usepackage{fancyvrb}

\author{<NAME>} 
\date{\today} 
\title{Sasalib: An Open Source C Library for Solvent Accesible Surface
  Calculations}

\begin{document}
\maketitle
\hrule\vspace{0.5cm}
\noindent
The program/library Sasalib, including this manual, is licensed under
GPLv3, and can be downloaded from github at: 
\begin{center}
\texttt{https://github.com/mittinatten/sasalib/}
\end{center}
NB: This document is a draft slowly approaching completeness.
\vspace{0.5cm}
\hrule
\section{Introduction}
The Solvent Accessible Surface Area (SASA) of a molecule gives a
measure of the surface of the molecule in contact with solvent. This
area can for example quantify how folded the conformation of a
macromolecule is, and can also be used to compare the exposed
hydrophobic surfaces of different conformations or different
molecules. To define the SASA, $A$, of a given molecule, let a spherical
probe roll over the surface of the molecule, including internal
cavities. $A$ is then the surface drawn by the center of the
probe.~\cite{LnR} The probe represents a solvent molecule
(i.e.\ water), and therefore cavities smaller than the solvent
molecule do not contribute to $A$.

Calculating Solvent Accessible Surface Areas (SASA) is a
run-of-the-mill calculation in protein structure studies. To the
author's knowledge there are no fully open source standalone programs
for doing this. Neither are there any libraries designed to be easily
integrated in other programs. The present library is an attempt to
resolve both these issues, and is released under the GNU General
Public License 3\footnote{See http://www.gnu.org/licenses/gpl.html}.

Sasalib is a both a standalone command line program and a C library
for protein SASA calculations. The library provides a simple interface
that takes PDB-files as input. It has default parameters to allow
straightforward calculations, but also allows the user to change most
parameters of the calculation. In addition, there is a lower level
interface where the user can treat the calculation as a purely
mathematical operation on a set of spheres, specifying only
coordinates and radii. Both Lee \& Richards' \cite{LnR} and Shrake \&
Rupley's \cite{SnR} algorithms are available. They will be referred to
as L\&R and S\&R throughout this document. Future versions of the
library might include other algorithms as well.

In constructing the library three possible use cases were considered. 
\begin{enumerate}
\item The user has a PDB-file and wishes to calculate the total SASA of
  the structure, or the SASA for certain groups or types of atoms.
\item The user has a set of cartesian atom coordinates and radii for
  these atoms, and wants to calculate the total SASA for this object.
\item The user is simulating different conformations of a molecule and
  wants to measure the SASA at certain intervals during the simulation.
\end{enumerate}
For case 1 both the command-line interface (CLI) and the application
programming interface (API) can be used. Using the API gives more
flexibility in interpreting and analyzing the results. The other 2
cases can only be handled through the API. Both the API and the CLI
allow the user to set parameters for the calculation. 

A lot of the internals of the library are involved with classification
and categorization of atoms, which is necessary for assigning radii
and to present SASA values integrated over different atom types, amino
acid types, etc. If the user wants Sasalib to classify atoms and
assign radii, data must be provided in the PDB-format. Users can also
provide their own radii and coordinates, and get the SASA for each
individual atom.

This document is organized as follows. Section \ref{sec:howto_short}
gives a brief introduction to the library, presenting the command line
interface and a short sample program that gives a general idea of how
to use the library. The introduction is intended to cover most casual
users' needs. Section \ref{sec:alg} describes the algorithms and
compares their performance in terms of computational cost and
precision. In section \ref{sec:imp} the implementations are
described. Finally, section \ref{sec:using} gives a detailed
description of the API.

\section{Getting started}\label{sec:howto_short}

The source files \texttt{calc\_sasa.c} and \texttt{example.c} contain
a complete command-line interface and a minimal program to illustrate
how to use the library interface, respectively. 

\subsection{Installation} \label{sec:installing}

The repository can be cloned from github, either by using git directly
with the command
\begin{verbatim}
    $ git clone https://github.com/mittinatten/sasalib.git
\end{verbatim}
or by downloading the zipped archive from
\begin{verbatim}
    https://github.com/mittinatten/sasalib/archive/master.zip
\end{verbatim}
Since Sasalib only depends on regular C and GNU libraries most users
will be able to compile it by simply typing \texttt{make}\footnote{Has
  been tested in Linux and Mac OS X.}. If any compiler other than the
Gnu C Compiler is preferred the makefile will need to be changed
accordingly. The command \texttt{make example} compiles the example
program described in section \ref{sec:simple_sample}. There is no
\texttt{make install} at the moment.

\subsection{Command-line interface}

Compilation creates the binary \texttt{calc\_sasa} from
\texttt{calc\_sasa.c}, which can be used to calculate the SASA of a
PDB-file. The simplest program call, with default parameters would be
\begin{verbatim}
    $ ./calc_sasa PDB-file
\end{verbatim}
Or, from STDIN:
\begin{verbatim} 
    $ ./calc_sasa < PDB-file    
\end{verbatim}
STDIN is only read if no file is specified.  By default the Shrake \&
Rupley algorithm is used, with 100 test points. 

\subsubsection{Options}
The following options are available
\begin{itemize}
  \item[-h] Prints help message.
  \item[-S] Use Shrake \& Rupley algorithm (default).
  \item[-L] Use Lee \& Richards algorithm.
  \item[-n] Number of test points in Shrake \& Rupley algorithm.
    Default is 100, allowed values are: 20, 50, 100, 200, 500, 1000,
    2000, 5000.
  \item[-d] Grid spacing in Lee \& Richards algorithm.
  Default value is 0.25 Å.
  \item[-t] Number of threads to use in calculation (for multicore
    CPUs). See section \ref{sec:speed} for a discussion of when this
    has a significant effect on performance.
  \item[-r] Print SASA for each residue.
  \item[-B] Print PDB file where the SASA value of each atom is
    written as its B factor (the output file is provided as an
    argument to the flag).
\end{itemize}
As an illustration, the command
\begin{verbatim}
   $ ./calc_sasa -L -d 0.1 -t 2 -r PDB-file
\end{verbatim}
calculates the SASA of the supplied pdb-file using Lee \& Richards,
with a slice width of 0.1 Å, using two threads (only makes sense for
CPUs with two or more cores) and will print the total SASA of each
residue type in addition to the standard output.

Several PDB-files can be analyzed in one call as, the results will be
printed consecutively for each input file:
\begin{verbatim}
   $ ./calc_sasa 1abc.pdb 2abc.pdb ...
\end{verbatim}
The calculations will not be run in parallel if the option '-t [n]' is
used, instead each calculation is parallelized individually.

\subsubsection{Output}
Running the program using the default parameters on the PDB structure
1UBQ gives the following output
\begin{verbatim}
   name: stdin
   algorithm: Shrake & Rupley
   probe-radius: 1.400000 A
   n_thread: 1
   n_testpoint: 100
   time_elapsed: 0.013833 s
   n_atoms: 602
   
   Total:    4756.12 A2
   Polar:    1968.06 A2
   Apolar:   2788.07 A2
\end{verbatim}
The first 5 lines contain info about input and parameters. This is
followed by data over calculation time and the size of the
protein. Finally the result of the calculation is printed, with SASA
values in Å$^2$.

\subsection{Simple example (\texttt{example.c})}\label{sec:simple_sample}

The following shows the minimal program \texttt{example.c} that
performs a SASA-calculation using a PDB-file as input. This program is
basically a stripped down version of \texttt{calc\_sasa.c} without
error handling, and without any commandline options. This code is
meant to illustrate the most basic parts of the library interface.
\begin{verbatim}
#include <stdlib.h>
#include "src/sasalib.h"

int main(int argc, char **argv) { 
    //initialize sasalib-object with default parameters
    sasalib_t *s = sasalib_init();

    //do the calculation using default parameters with protein
    //structure from STDIN
    sasalib_calc_pdb(s,stdin);

    //print results
    sasalib_log(stdout,s);
    printf("Total area: %f A2\n", sasalib_area_total(s));

    //clean up
    sasalib_free(s);

    return EXIT_SUCCESS;
}
\end{verbatim}
This program generates results similar to that in the previous
section.

\section{Algorithms}\label{sec:alg}

There are two classical approximate algorithms that can be used to
calculate SASA, by <NAME> \cite{LnR} and <NAME>
\cite{SnR} respectively. Both can be calculated to arbitrary precision
by refining the resolution. 

As will be clear from this section and the analysis in section
\ref{sec:compare}, S\&R is the simpler and faster of the
two. Therefore the casual user is recommended to use S\&R. L\&R is
mainly included for reference, and for the fact that the precision is
only limited by floating point precision. In the current
implementation S\&R can only be used with a predefined set of levels
of precision. However, it is not obvious what applications would
require very high precision SASA values.

We will use the following notation: An atom $i$ has a van der Waals
radius $r_i$, the rolling sphere (or \emph{probe}) has radius
{'fraction_non_alphanumeric': 0.06727389733181525, 'fraction_numerical': 0.009801494975496263, 'mean_word_length': 4.3345656192236595, 'pattern_counts': {'":': 0, '<': 12, '<?xml version=': 0, '>': 10, 'https://': 6, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1146621', 'n_tokens_mistral': 6012, 'n_tokens_neox': 5608, 'n_words': 2758}