# Classes

## Classifier

class freesasa.Classifier

  Assigns class and radius to atom by residue and atom name.

  Subclasses derived from `Classifier` can be used to define custom atomic radii and/or classes. Can also be initialized from config-files with a custom classifier.

  If initialized without arguments the default classifier is used.

  Derived classifiers must set the member `purePython` to `True`

  Residue names should be of the format `"ALA"`, `"ARG"`, etc. Atom names should be of the format `"CA"`, `"N"`, etc.

  __init__()

    Constructor.

    If no file is provided the default classifier is used.

    Parameters:

      fileName (str) – Name of file with classifier configuration.

    Raises:

      - IOError – Problem opening/reading file

      - Exception – Problem parsing provided configuration or initializing defaults

  __new__(**kwargs)
  __reduce__()

    Helper for pickle.

  classify(residueName, atomName)

    Class of atom.

    Depending on the configuration these classes can be anything, but typically they will be `"Polar"` and `"Apolar"`. Unrecognized atoms will get the class `"Unknown"`.

    Parameters:

      - residueName (str) – Residue name (“ALA”, “ARG”,…).

      - atomName (str) – Atom name (“CA”, “C”,…).

    Returns:

      Class name

    Return type:

      str

  static getStandardClassifier(type)

    Get a standard classifier (ProtOr, OONS or NACCESS)

    Parameters:

      type (str) – The type, can have values `'protor'`, `'oons'` or `'naccess'`

    Returns:

      The requested classifier

    Return type:

      `Classifier`

    Raises:

      Exception – If type not recognized

  radius(residueName, atomName)

    Radius of atom.

    This allows the classifier to be used to calculate the atomic radii used in calculations. Unknown atoms will get a negative radius.

    Parameters:

      - residueName (str) – Residue name (“ALA”, “ARG”, …).

      - atomName (str) – Atom name (“CA”, “C”, …).

    Returns:

      The radius in Å.

    Return type:

      float

## Parameters

class freesasa.Parameters

  Stores parameter values to be used by calculation.

  Default parameters are

      Parameters.defaultParameters = {
          'algorithm'    : LeeRichards,
          'probe-radius' : freesasa_default_parameters.probe_radius,
          'n-points'     : freesasa_default_parameters.shrake_rupley_n_points,
          'n-slices'     : freesasa_default_parameters.lee_richards_n_slices,
          'n-threads'    : freesasa_default_parameters.n_threads
      }

  Variables:

    defaultParamers (dict) – The default parameters

  __init__()

    Initializes Parameters object.

    Parameters:

      param (dict) – optional argument to specify parameter-values, see `Parameters.defaultParameters`.

    Raises:

      AssertionError – Invalid parameter values supplied

  __new__(**kwargs)
  __reduce__()

    Helper for pickle.

  algorithm()

    Get algorithm.

    Returns:

      Name of algorithm

    Return type:

      str

  nPoints()

    Get number of test points in Shrake & Rupley algorithm.

    Returns:

      Number of points.

    Return type:

      int

  nSlices()

    Get the number of slices per atom in Lee & Richards algorithm.

    Returns:

      Number of slices.

    Return type:

      int

  nThreads()

    Get the number of threads to use in calculations.

    Returns:

      Number of threads.

    Return type:

      int

  probeRadius()

    Get probe radius.

    Returns:

      Probe radius in Å

    Return type:

      float

  setAlgorithm(alg)

    Set algorithm.

    Parameters:

      - alg (str) – algorithm name, only allowed values are

      - :py:data:`freesasa.ShrakeRupley` and :py:data:`freesasa.LeeRichards`

    Raises:

      AssertionError – unknown algorithm specified

  setNPoints(n)

    Set number of test points in Shrake & Rupley algorithm.

    Parameters:

      n (int) – Number of points (> 0).

    Raises:

      AssertionError – n <= 0.

  setNSlices(n)

    Set the number of slices per atom in Lee & Richards algorithm.

    Parameters:

      n (int) – Number of slices (> 0)

    Raises:

      AssertionError – n <= 0

  setNThreads(n)

    Set the number of threads to use in calculations.

    Parameters:

      n (int) – Number of points (> 0)

    Raises:

      AssertionError – n <= 0

  setProbeRadius(r)

    Set probe radius.

    Parameters:

      r (float) – probe radius in Å (>= 0)

    Raises:

      AssertionError – r < 0

## Result

class freesasa.Result

  Stores results from SASA calculation.

  The type of object returned by `freesasa.calc()`, not intended to be used outside of that context.

  atomArea(i)

    SASA for a given atom.

    Parameters:

      i (int) – index of atom.

    Returns:

      SASA of atom i in Å^2.

    Return type:

      float

    Raises:

      AssertionError – If no results have been associated with the object or if index is out of bounds

  nAtoms()

    Number of atoms in the results.

    Returns:

      Number of atoms.

    Return type:

      int

  residueAreas()

    Get SASA for all residues including relative areas if available for the classifier used.

    Returns dictionary of results where first dimension is chain label and the second dimension residue number. I.e. `result["A"]["5"]` gives the `ResidueArea` of residue number 5 in chain A.

    Relative areas are normalized to 1, but can be > 1 for residues in unusual conformations or at the ends of chains.

    Returns:

      dictionary

    Raises:

      AssertionError – If no results or structure has been associated with the object.

  totalArea()

    Total SASA.

    Returns:

      The total area in Å^2.

    Raises:

      AssertionError – If no results have been associated with the object.

## ResidueArea

class freesasa.ResidueArea

  Stores absolute and relative areas for a residue

  Variables:

    - residueType (str) – Type of Residue

    - residueNumber (str) – Residue number

    - hasRelativeAreas (bool) – False if there was noe reference area to calculate relative areas from

    - total (float) – Total SASA of residue

    - polar (float) – Polar SASA

    - apolar (float) – Apolar SASA

    - mainChain (float) – Main chain SASA

    - sideChain (float) – Side chain SASA

    - relativeTotal (float) – Relative total SASA

    - relativePolar (float) – Relative polar SASA

    - relativeApolar (float) – Relative Apolar SASA

    - relativeMainChain (float) – Relative main chain SASA

    - relativeSideChain (float) – Relative side chain SASA

## Structure

class freesasa.Structure

  Represents a protein structure, including its atomic radii.

  Initialized from PDB-file. Calculates atomic radii using default classifier, or custom one provided as argument to initalizer.

  Default options are

      Structure.defaultOptions = {
          'hetatm' : False,          # False: skip HETATM
                                     # True: include HETATM

          'hydrogen' : False,        # False: ignore hydrogens
                                     # True: include hydrogens

          'join-models' : False,     # False: Only use the first MODEL
                                     # True: Include all MODELs

          'skip-unknown' : False,    # False: Guess radius for unknown atoms
                                     #     based on element
                                     # True: Skip unknown atoms

          'halt-at-unknown' : False  # False: set radius for unknown atoms,
                                     #    that can not be guessed to 0.
                                     # True: Throw exception on unknown atoms.
      }

  Variables:

    defaultOptions – Default options for reading structure from PDB.

  __init__()

    Constructor

    If a PDB file is provided, the structure will be constructed based on the file. If not, this simply initializes an empty structure with the given classifier and options. Atoms will then have to be added manually using :py:meth:.Structure.addAtom()`.

    Parameters:

      - fileName (str) – PDB file (if None empty structure generated).

      - classifier – An optional `Classifier` to calculate atomic radii, uses default if none provided. This classifier will also be used in calls to `Structure.addAtom()` but only if it’s the default classifier, one of the standard classifiers from `Classifier.getStandardClassifier()`, or defined by a config-file (i.e. if it uses the underlying C API).

      - options (dict) – specify which atoms and models to include, default is `Structure.defaultOptions`

    Raises:

      - IOError – Problem opening/reading file.

      - Exception – Problem parsing PDB file or calculating atomic radii.

      - Exception – If option ‘halt-at-unknown’ selected and unknown atom encountered.

  __new__(**kwargs)
  __reduce__()

    Helper for pickle.

  addAtom(atomName, residueName, residueNumber, chainLabel, x, y, z)

    Add atom to structure.

    This function is meant to be used if the structure was not initialized from a PDB. The options and classifier passed to the constructor for the `Structure` will be used (see the documentation of the constructor for restrictions). The radii set by the classifier can be overriden by calling `Structure.setRadiiWithClassifier()` afterwards.

    There are no restraints on string lengths for the arguments, but the atom won’t be added if the classifier doesn’t recognize the atom and also cannot deduce its element from the atom name.

    Parameters:

      - atomName (str) – atom name (e.g. “CA”)

      - residueName (str) – residue name (e.g. “ALA”)

      - residueNumber (str or int) – residue number (e.g. ‘12’) or integer. Some PDBs have residue-numbers that aren’t regular numbers. Therefore treated as a string primarily.

      - chainLabel (str) – 1-character string with chain label (e.g. ‘A’) x,y,z (float): coordinates

    Raises:

      - Exception – Residue-number invalid

      - AssertionError –

  atomName(i)

    Get atom name

    Parameters:

      i (int) – Atom index.

    Returns:

      Atom name as 4-character string.

    Return type:

      str

    Raises:

      AssertionError – if index out of range or Structure not properly initialized.

  chainLabel(i)

    Get chain label for given atom.

    Parameters:

      i (int) – Atom index.

    Returns:

      Chain label as 1-character string.

    Return type:

      str

    Raises:

      AssertionError – if index out of range or Structure not properly initialized

  coord(i)

    Get coordinates of given atom.

    Parameters:

      i (int) – Atom index.

    Returns:

      array of x, y, and z coordinates

    Return type:

      list

    Raises:

      AssertionError – if index out of range or Structure not properly initialized

  nAtoms()

    Number of atoms.

    Returns:

      Number of atoms

    Return type:

      int

    Raises:

      AssertionError – if not properly initialized

  radius(i)

    Radius of atom.

    Parameters:

      i (int) – Index of atom.

    Returns:

      Radius in Å.

    Return type:

      float

    Raises:

      AssertionError – if index out of bounds, object not properly initalized.

  residueName(i)

    Get residue name of given atom.

    Parameters:

      i (int) – Atom index.

    Returns:

      Residue name as 3-character string.

    Return type:

      str

    Raises:

      AssertionError – if index out of range or Structure not properly initialized

  residueNumber(i)

    Get residue number for given atom.

    Residue number will include the insertion code if there is one.

    Parameters:

      i (int) – Atom index.

    Returns:

      Residue number as 5-character string (last character is either whitespace or insertion code)

    Return type:

      str

    Raises:

      AssertionError – if index out of range or Structure not properly initialized

  setRadii(radiusArray)

    Set atomic radii from an array

    Parameters:

      radiusArray (list) – Array of atomic radii in Ångström, should have nAtoms() elements.

    Raises:

      AssertionError – if radiusArray has wrong dimension, structure not properly initialized, or if the array contains negative radii (not properly classified?)

  setRadiiWithClassifier(classifier)

    Assign radii to atoms in structure using a classifier.

    Parameters:

      classifier – A `Classifier` to use to calculate radii.

    Raises:

      AssertionError – if structure not properly initialized

  setRadius(atomIndex, radius)

    Set radius for a given atom

    Parameters:

      - atomIndex (int) – Index of atom

      - radius (float) – Value of radius

    Raises:

      AssertionError – if index out of bounds, radius negative, or structure not properly initialized