NAME
     Psa - protein surface accessibility

SYNOPSIS
     psa file

DESCRIPTION
     Psa is a program for calculating the surface accessibility
     of all the atoms and residues from a PDB format coordinate
     file. It is recommended that you preprocess your coordinates
     with the program pdb2atm(1) to ensure they have a standard
     format. The program implements the method of Lee and
     Richards. By default HETATM groups, excluding water, are
     included in the calculations (see below as to how to control
     this).

     There are a number of data files that are read at run-time
     that control what the program does.

     The first of these is psa.dat.  This can either be in the
     current directory or in the psa library directory. The file
     in the current directory is used first. This file contains a
     list of residue/group names, atom names and atomic radii.
     Within this library the hash symbol signifies a comment.
     The format of this library is the name of the residue/hetatm
     group (A3), then the number of atoms within this group (I3),
     note that this number should include the terminal oxygen of
     the residue. There then follows a list of the atom names and
     the corresponding Van der Waal's radii (A4,F6.2). For every
     residue it is wise to add an OXT record, otherwise you will
     get spurious error messages.  Thus an example entry for
     alanine is:
     ALA  6    # alanine
      N    1.65
      CA   1.87
      C    1.76
      O    1.40
      CB   1.87
      OXT  1.40

     A number of options can be used to control psa.  These are:

     -t,  Send output to stdout.

     -pN.n,
          where N.n is a real number representing the probe
          radius, which is to be `rolled over the surface', 1.4A
          is half the inter-oxygen distance in ice, and so is
          associated with the Van der Waal's radius of water (and
          all oxygen atoms in general).

     -eN.n,
          where N.n is a real number representing the integration
          step, this is the plane spacing (in A) used to
          calculate the accessibility. The smaller this value the
          more accurate the results will be, but the slower the
          program will run. The default value seems to be a
          reasonable compromise.

     -a,  this controls whether atomic accesibilities are written
          to file, if ON then a file with a .sol extension is
          produced, containing a PDB format coordinate set but
          with the B-value column containing the absolute atom
          accessibility for each atom.  The default for this is
          false.

     -a,  this controls whether residue accesibilities are
          written to file, if ON, then a file with a .psa
          extension is produced.  Standard accesibilities were
          calculated in an A-X-A peptide (where X is the residue
          in question), in an extended conformation (o=-140,
          u=135 and w=180) with the exception of proline. Where
          applicable sidechain torsions were all trans.  An
          important point to note is that in the summing of
          accessibilities into mainchain and sidechain values,
          the Ca atom is considered to be part of the sidechain,
          and is not considered in the mainchain values; this is
          so glycine can be treated consistently with the other
          amino acids.  For further notes on this see the file
          standard.doc. The standard accessibility data was
          kindly provided by Simon Hubbard.

     Input can come from stdin if you want it to.

     An example of a .psa file is:
     # produced by psa, version 1.0a
     #
     # File of summed (Sum) and % (per.) accessibilities
     # probe radius       :   1.400
     # integration step   :    .050
     # water included     :       F
     # hetatom included   :       T
     # accessibility type : CONTACT
     #
     #       Res   Res   All atoms   Non P side  Polar Side  Total Side  Main Chain
     #       Num  type    Sum  Per.   Sum  Per.   Sum  Per.   Sum  Per.   Sum  Per.
     ACCESS   16   ILE     .56  1.0    .01   .0    .00   .0    .01   .0    .55  5.6
     ACCESS   17   VAL    4.17  8.7   4.17 11.0    .00   .0   4.17 11.0    .00   .0
     ACCESS   18   GLY   12.72 53.6   8.20 75.7    .00   .0   8.20 75.7   4.52 35.0
     ACCESS   19   GLY    9.61 40.4    .64  5.9    .00   .0    .64  5.9   8.96 69.4
     ACCESS   20   TYR   30.63 49.3  28.82 68.1   1.81 17.1  30.63 57.9    .00   .0
     ACCESS   21   THR   21.55 51.5  12.98 52.1   3.65 52.0  16.63 52.1   4.92 49.6

     The units for the SUM columns are A2 and % for the Per
     columns. It is important to note that the Ca atom is
     considered part of the sidechain. A `!' after the residue
     type means that not all atoms were found in that sidechain,
     the absolute accessibilities will be correct but the meaning
     of the relative values is questionable, joy automatically
     considers these residues to be accessible.  Joy currently
     uses a 7.0% relative total sidechain accessibility cutoff to
     define inaccessible residues. It is common for residues to
     be more than 100% accessible, this simply means that they
     are more accessible in the conformation they were found in,
     than in the reference conformation.

     The default is true.

     -w   controls whether explicit water atoms are to be
          included in the calculations, one does not usually want
          to do this, thus the default is false.

     -h   controls whether HETATM records from the input file are
          to be included in the surface are calculations. You
          must add an entry to the psa.dat file if you want to
          use a group that is not in the library and want to get
          meaningful results. (If you do not then 1.8A is
          assigned as the radius). The default is true.

     -c   makes the surface calculated represent the contact
          surface.

     -s   makes the calculated surface an accessible surface.

     In general the surface area is about three times larger than
     the contact area. Most programs deal with the CONTACT areas,
     so unless you are sure of what you are doing then leave this
     alone. The default is for a contact surface.


FILES
     /usr/local/lib/psa  -- default psa library directory


CAVEATS
     The inner workings of the program are hairy, you can run
     into trouble with different compilers/optimization, etc. It
     is almost impossible to set up a new standard amino acid
     type (for example, a residue from an inhibitor) and get
     relative % accesibilty values, it is better to do this sort
     of calculation from the .sol file.

     The psa.dat file should be replaced by a set of options.

SEE ALSO
     pdb2atm(1), joy(1)

RELEASE LEVEL
     This document describes psa version 1.0 and later.