FreeSASA  2.0.1
Open source SASA calculations
View on GitHub
Data Structures | Typedefs | Enumerations | Functions
Node

Represent results as a tree. More...

Data Structures

struct  freesasa_nodearea
 Struct to store integrated SASA values for either a full structure or a subset thereof. More...
 

Typedefs

typedef struct freesasa_node freesasa_node
 A node representing calculation results for a structure, chain, residue or atom in a structure (see Node).
 

Enumerations

enum  freesasa_output_options {
  FREESASA_OUTPUT_ATOM =1, FREESASA_OUTPUT_RESIDUE =1<<2, FREESASA_OUTPUT_CHAIN =1<<3, FREESASA_OUTPUT_STRUCTURE =1<<4,
  FREESASA_LOG =1<<5, FREESASA_RSA =1<<6, FREESASA_JSON =1<<7, FREESASA_XML =1<<8,
  FREESASA_PDB =1<<9, FREESASA_RES =1<<10, FREESASA_SEQ =1<<11, FREESASA_OUTPUT_SKIP_REL =1<<12
}
 Controls output format, can be combined in options bitfield in freesasa_tree_export() More...
 
enum  freesasa_nodetype {
  FREESASA_NODE_ATOM, FREESASA_NODE_RESIDUE, FREESASA_NODE_CHAIN, FREESASA_NODE_STRUCTURE,
  FREESASA_NODE_RESULT, FREESASA_NODE_ROOT, FREESASA_NODE_NONE
}
 Node types. More...
 

Functions

freesasa_nodefreesasa_tree_new (void)
 Generates empty freesasa_node of type FREESASA_NODE_ROOT. More...
 
freesasa_nodefreesasa_tree_init (const freesasa_result *result, const freesasa_structure *structure, const char *name)
 Init tree based on result and structure. More...
 
int freesasa_tree_add_result (freesasa_node *tree, const freesasa_result *result, const freesasa_structure *structure, const char *name)
 Add a new set of results to a tree. More...
 
int freesasa_tree_join (freesasa_node *tree1, freesasa_node **tree2)
 Join two trees. More...
 
int freesasa_tree_export (FILE *output, freesasa_node *root, int options)
 Outputs result in format specified by options. More...
 
int freesasa_node_free (freesasa_node *root)
 Free tree. More...
 
const freesasa_nodeareafreesasa_node_area (const freesasa_node *node)
 The freesasa_nodearea of all atoms belonging to a node. More...
 
freesasa_nodefreesasa_node_children (freesasa_node *node)
 The children of a node. More...
 
freesasa_nodefreesasa_node_next (freesasa_node *node)
 Next sibling of a node. More...
 
freesasa_nodefreesasa_node_parent (freesasa_node *node)
 The parent of a node. More...
 
freesasa_nodetype freesasa_node_type (const freesasa_node *node)
 The type of a node. More...
 
const char * freesasa_node_name (const freesasa_node *node)
 The name of a node. More...
 
const char * freesasa_node_classified_by (const freesasa_node *node)
 The name of the classifier used to generate the node. More...
 
int freesasa_node_atom_is_polar (const freesasa_node *node)
 Is atom polar. More...
 
int freesasa_node_atom_is_mainchain (const freesasa_node *node)
 Does atom belong to the main chain/backbone. More...
 
double freesasa_node_atom_radius (const freesasa_node *node)
 Atom radius. More...
 
const char * freesasa_node_atom_pdb_line (const freesasa_node *node)
 Line in PDB atom was generated from. More...
 
const char * freesasa_node_residue_number (const freesasa_node *node)
 Residue number. More...
 
int freesasa_node_residue_n_atoms (const freesasa_node *node)
 Number of atoms in a residue. More...
 
const freesasa_nodeareafreesasa_node_residue_reference (const freesasa_node *node)
 The reference area for a node from the classifier used to generate the tree. More...
 
int freesasa_node_chain_n_residues (const freesasa_node *node)
 The number of residues in a chain. More...
 
int freesasa_node_structure_n_chains (const freesasa_node *node)
 The number of chains in a structure. More...
 
int freesasa_node_structure_n_atoms (const freesasa_node *node)
 The number of atoms in a structure. More...
 
const char * freesasa_node_structure_chain_labels (const freesasa_node *node)
 All chain labels in a structure. More...
 
int freesasa_node_structure_model (const freesasa_node *node)
 Model number of a structure (from input PDB) More...
 
const freesasa_resultfreesasa_node_structure_result (const freesasa_node *node)
 Raw results for a structure. More...
 
const freesasa_selection ** freesasa_node_structure_selections (const freesasa_node *node)
 Selection results for a structure. More...
 
int freesasa_node_structure_add_selection (freesasa_node *node, const freesasa_selection *selection)
 Add a selection result to a structure node. More...
 
const freesasa_parametersfreesasa_node_result_parameters (const freesasa_node *node)
 Parameter values used to calculate result. More...
 

Detailed Description

Represent results as a tree.

Results are represented hierarchically as a tree with the following levels (see also freesasa_node_type)

The tree can be traversed using freesasa_node_children(), freesasa_node_next() and freesasa_node_parent(). The type of a node is determined by freesasa_node_type(). There are some properties that are common to all or most levels of the tree. These accessors simply have the prefix freesasa_node, like for example freesasa_node_name() and the above-mentioned functions. Other properties are specific to a special level, and then the prefix of the accessor functions will be freesasa_node_atom or freesasa_node_structure, etc. The class of an atom can for example be accessed using freesasa_node_atom_is_polar().

The nodes of a tree are to be considered read-only, and changes are made only to the root node, initialized using freesasa_tree_new() or freesasa_tree_init(), and modified using freesasa_tree_add_result(), freesasa_tree_join(). The one exception where a lower level node can be modified is freesasa_node_structure_add_selection().

Enumeration Type Documentation

Controls output format, can be combined in options bitfield in freesasa_tree_export()

Enumerator
FREESASA_OUTPUT_ATOM 

Output data for atoms, residues, chains and structure.

FREESASA_OUTPUT_RESIDUE 

Output data for residues, chains and structure.

FREESASA_OUTPUT_CHAIN 

Output data for chains and structure.

FREESASA_OUTPUT_STRUCTURE 

Output data only for the whole structure.

FREESASA_LOG 

Simple plain text results.

FREESASA_RSA 

RSA output (not affected by atom, residue, etc above)

FREESASA_JSON 

JSON output.

FREESASA_XML 

XML output.

FREESASA_PDB 

PDB output (with B-factors replaced by SASA values, and occupancy by radius)

FREESASA_RES 

A list of the integrated SASA of each residue type.

FREESASA_SEQ 

The SASA of each residue in the sequence.

FREESASA_OUTPUT_SKIP_REL 

Don't output relative areas, for example if structure has manually set radii, invalidating reference values.

Definition at line 156 of file freesasa.h.

Node types.

Enumerator
FREESASA_NODE_ATOM 

Atom node.

FREESASA_NODE_RESIDUE 

Residue node.

FREESASA_NODE_CHAIN 

Chain node.

FREESASA_NODE_STRUCTURE 

Structure node.

FREESASA_NODE_RESULT 

Result node, wraps results for one or more related structures.

FREESASA_NODE_ROOT 

Root node, wraps one or more unrelated results.

FREESASA_NODE_NONE 

for specifying not a valid node

Definition at line 231 of file freesasa.h.

Function Documentation

freesasa_node* freesasa_tree_new ( void  )

Generates empty freesasa_node of type FREESASA_NODE_ROOT.

To be populated by freesasa_tree_add_result().

The return value is dynamically allocated and should be freed using freesasa_node_free().

Returns
A freesasa_node. NULL if memory allocation fails.
freesasa_node* freesasa_tree_init ( const freesasa_result result,
const freesasa_structure structure,
const char *  name 
)

Init tree based on result and structure.

The return value is dynamically allocated and should be freed using freesasa_node_free().

Parameters
resultA result.
structureA structure.
nameName of the results (typically filename from which structure is derived)
Returns
The root node of the tree. NULL if memory allocation fails.
int freesasa_tree_add_result ( freesasa_node tree,
const freesasa_result result,
const freesasa_structure structure,
const char *  name 
)

Add a new set of results to a tree.

Tree should first be initiated with freesasa_calc_tree(), freesasa_tree_new() or freesasa_tree_init().

Parameters
treeNode of type FREESASA_NODE_ROOT. Tree to add results to.
resultSASA values for the structure
structureThe structure the results are based on
nameThe name to use for the result
Returns
FREESASA_SUCCESS upon success. FREESASA_FAIL if memory allocation fails.
int freesasa_tree_join ( freesasa_node tree1,
freesasa_node **  tree2 
)

Join two trees.

Allows joining several calculations into one output file.

Parameters
tree1Node of type FREESASA_NODE_ROOT. The joint tree will be stored here.
tree2Node of type FREESASA_NODE_ROOT. Will be added to tree1, and then changed to NULL, since ownership of its contents have been transferred to tree1.
Returns
FREESASA_SUCCESS.
int freesasa_tree_export ( FILE *  output,
freesasa_node root,
int  options 
)

Outputs result in format specified by options.

Parameters
outputOutput file.
rootStructure tree containing results. Node of type FREESASA_NODE_ROOT.
optionsBitfield specifying output format, see freesasa_output_options.
Returns
FREESASA_SUCCESS upon success. FREESASA_FAIL if there was an error (see messages).
int freesasa_node_free ( freesasa_node root)

Free tree.

Will not free anything if the node is not a root node.

Parameters
rootNode of type FREESASA_NODE_ROOT
Returns
FREESASA_SUCCESS. FREESASA_FAIL if the node has a parent.
const freesasa_nodearea* freesasa_node_area ( const freesasa_node node)

The freesasa_nodearea of all atoms belonging to a node.

Parameters
nodeThe node.
Returns
The area. NULL if no area has been attached to this node.
freesasa_node* freesasa_node_children ( freesasa_node node)

The children of a node.

Use freesasa_node_next() to access next sibling.

Parameters
nodeThe node.
Returns
Pointer to the first child of a node. NULL if the node has no children.
freesasa_node* freesasa_node_next ( freesasa_node node)

Next sibling of a node.

Parameters
nodeThe node.
Returns
The next node, NULL if this is the last node.
freesasa_node* freesasa_node_parent ( freesasa_node node)

The parent of a node.

Parameters
nodeThe node.
Returns
The parent node. NULL if the node has no parent.
freesasa_nodetype freesasa_node_type ( const freesasa_node node)

The type of a node.

Parameters
nodeThe node.
Returns
The type.
const char* freesasa_node_name ( const freesasa_node node)

The name of a node.

The node types will have the following names:

  • Atom: atom name, i.e. " CA ", " OXT", etc.
  • Residue: residue name, i.e. "ALA", "ARG", etc.
  • Chain: chain label, i.e. "A", "B", etc.
  • Structure: string of all chain labels in the molecule, i.e. "A", "ABC", etc
  • Result: name of input (most often input filename or "stdin")
  • Root: NULL
Parameters
nodeThe node.
Returns
The name. NULL if the node has no name.
const char* freesasa_node_classified_by ( const freesasa_node node)

The name of the classifier used to generate the node.

Parameters
nodeA node of type FREESASA_NODE_RESULT.
Returns
The name of the classifier
int freesasa_node_atom_is_polar ( const freesasa_node node)

Is atom polar.

Parameters
nodeA node of type FREESASA_NODE_ATOM.
Returns
1 if polar, 0 else.
int freesasa_node_atom_is_mainchain ( const freesasa_node node)

Does atom belong to the main chain/backbone.

Parameters
nodeA node of type FREESASA_NODE_ATOM.
Returns
1 if mainchain, 0 else.
double freesasa_node_atom_radius ( const freesasa_node node)

Atom radius.

Parameters
nodeA node of type FREESASA_NODE_ATOM.
Returns
The radius.
const char* freesasa_node_atom_pdb_line ( const freesasa_node node)

Line in PDB atom was generated from.

Parameters
nodeA node of type FREESASA_NODE_ATOM.
Returns
The line. NULL if atom wasn't taken from PDB file.
const char* freesasa_node_residue_number ( const freesasa_node node)

Residue number.

Parameters
nodeA node of type FREESASA_NODE_RESIDUE.
Returns
String with residue number.
int freesasa_node_residue_n_atoms ( const freesasa_node node)

Number of atoms in a residue.

Parameters
nodeA node of type FREESASA_NODE_RESIDUE.
Returns
Number of atoms.
const freesasa_nodearea* freesasa_node_residue_reference ( const freesasa_node node)

The reference area for a node from the classifier used to generate the tree.

Parameters
nodeA node of type FREESASA_NODE_RESIDUE.
Returns
The reference area. NULL if area not available.
int freesasa_node_chain_n_residues ( const freesasa_node node)

The number of residues in a chain.

Parameters
nodeA node of type FREESASA_NODE_CHAIN.
Returns
Number of residues.
int freesasa_node_structure_n_chains ( const freesasa_node node)

The number of chains in a structure.

Parameters
nodeA node of type FREESASA_NODE_STRUCTURE.
Returns
Number of chains.
int freesasa_node_structure_n_atoms ( const freesasa_node node)

The number of atoms in a structure.

Parameters
nodeA node of type FREESASA_NODE_STRUCTURE.
Returns
Number of atoms.
const char* freesasa_node_structure_chain_labels ( const freesasa_node node)

All chain labels in a structure.

Parameters
nodeA node of type FREESASA_NODE_STRUCTURE.
Returns
Chain labels as null-terminated string.
int freesasa_node_structure_model ( const freesasa_node node)

Model number of a structure (from input PDB)

Parameters
nodeA node of type FREESASA_NODE_STRUCTURE.
Returns
Model number.
const freesasa_result* freesasa_node_structure_result ( const freesasa_node node)

Raw results for a structure.

Parameters
nodeA node of type FREESASA_NODE_STRUCTURE.
Returns
The results.
const freesasa_selection** freesasa_node_structure_selections ( const freesasa_node node)

Selection results for a structure.

Generated using freesasa_node_structure_add_selection().

Parameters
nodeA node of type FREESASA_NODE_STRUCTURE.
Returns
A null-terminated array of pointers to selections. NULL if no selections were associated with structure.
int freesasa_node_structure_add_selection ( freesasa_node node,
const freesasa_selection selection 
)

Add a selection result to a structure node.

The selection is cloned, so the user can call freesasa_selection_free() on the provided selection at the time of their chosing.

Parameters
nodeA node of type FREESASA_NODE_STRUCTURE.
selectionA selection.
Returns
FREESASA_SUCCESS. FREESASA_FAIL if cloning fails (i.e. memory allocation failure).
const freesasa_parameters* freesasa_node_result_parameters ( const freesasa_node node)

Parameter values used to calculate result.

Parameters
nodeA node of type FREESASA_NODE_RESULT
Returns
The parameters.