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
	Result node. More...

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_CIF = 1 << 12 , FREESASA_OUTPUT_SKIP_REL = 1 << 13 }
	Output options. 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_node *	freesasa_tree_new (void)
	Generates empty freesasa_node of type FREESASA_NODE_ROOT. More...

freesasa_node *	freesasa_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_nodearea *	freesasa_node_area (const freesasa_node *node)
	The freesasa_nodearea of all atoms belonging to a node. More...

freesasa_node *	freesasa_node_children (freesasa_node *node)
	The children of a node. More...

freesasa_node *	freesasa_node_next (freesasa_node *node)
	Next sibling of a node. More...

freesasa_node *	freesasa_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_atom_residue_number (const freesasa_node *node)
	Atom residue number. More...

const char *	freesasa_node_atom_residue_name (const freesasa_node *node)
	Atom residue name. More...

char	freesasa_node_atom_chain (const freesasa_node *node)
	Atom chain. 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_nodearea *	freesasa_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_result *	freesasa_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_parameters *	freesasa_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)

Root: wrapper, to allow joining results of several calculations.
Result: wrapper for an individual result, contains information about calculation parameters, the classifier used and the input.
Structure: an individual molecule, the highest level where actual SASA values are stored.
Chain: an individual chain.
Residue: typically an amino acid or nucleic acid.
Atom: lowest level.

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().

Typedef Documentation

◆ freesasa_node

typedef struct freesasa_node freesasa_node

Result node.

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

Definition at line 352 of file freesasa.h.

Enumeration Type Documentation

◆ freesasa_output_options

enum freesasa_output_options

Output options.

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_CIF	CIF output with SASA values and SASA radius appended.
FREESASA_OUTPUT_SKIP_REL	Don't output relative areas, for example if structure has manually set radii, invalidating reference values.

Definition at line 200 of file freesasa.h.

◆ freesasa_nodetype

enum freesasa_nodetype

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 307 of file freesasa.h.

Function Documentation

◆ freesasa_tree_new()

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_tree_init()

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

result	A result.
structure	A structure.
name	Name of the results (typically filename from which structure is derived)

Returns: The root node of the tree. NULL if memory allocation fails.

◆ freesasa_tree_add_result()

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

tree	Node of type FREESASA_NODE_ROOT. Tree to add results to.
result	SASA values for the structure
structure	The structure the results are based on
name	The name to use for the result

Returns: FREESASA_SUCCESS upon success. FREESASA_FAIL if memory allocation fails.

◆ freesasa_tree_join()

int freesasa_tree_join	(	freesasa_node *	tree1,
		freesasa_node **	tree2
	)

Join two trees.

Allows joining several calculations into one output file.

Parameters

tree1	Node of type FREESASA_NODE_ROOT. The joint tree will be stored here.
tree2	Node 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.

◆ freesasa_tree_export()

int freesasa_tree_export	(	FILE *	output,
		freesasa_node *	root,
		int	options
	)

Outputs result in format specified by options.

Parameters

output	Output file.
root	Structure tree containing results. Node of type FREESASA_NODE_ROOT.
options	Bitfield specifying output format, see freesasa_output_options.

Returns: FREESASA_SUCCESS upon success. FREESASA_FAIL if there was an error (see messages).

◆ freesasa_node_free()

int freesasa_node_free ( freesasa_node * root )

Free tree.

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

Parameters

root	Node of type FREESASA_NODE_ROOT

Returns: FREESASA_SUCCESS. FREESASA_FAIL if the node has a parent.

◆ freesasa_node_area()

const freesasa_nodearea * freesasa_node_area ( const freesasa_node * node )

The freesasa_nodearea of all atoms belonging to a node.

Parameters

node The node.

Returns: The area. NULL if no area has been attached to this node.

◆ freesasa_node_children()

freesasa_node * freesasa_node_children ( freesasa_node * node )

The children of a node.

Use freesasa_node_next() to access next sibling.

Parameters

node The node.

Returns: Pointer to the first child of a node. NULL if the node has no children.

◆ freesasa_node_next()

freesasa_node * freesasa_node_next ( freesasa_node * node )

Next sibling of a node.

Parameters

node The node.

Returns: The next node, NULL if this is the last node.

◆ freesasa_node_parent()

freesasa_node * freesasa_node_parent ( freesasa_node * node )

The parent of a node.

Parameters

node The node.

Returns: The parent node. NULL if the node has no parent.

◆ freesasa_node_type()

freesasa_nodetype freesasa_node_type ( const freesasa_node * node )

The type of a node.

Parameters

node The node.

Returns: The type.

◆ freesasa_node_name()

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

node The node.

Returns: The name. NULL if the node has no name.

◆ freesasa_node_classified_by()

const char * freesasa_node_classified_by ( const freesasa_node * node )

The name of the classifier used to generate the node.

Parameters

node	A node of type FREESASA_NODE_RESULT.

Returns: The name of the classifier

◆ freesasa_node_atom_is_polar()

int freesasa_node_atom_is_polar ( const freesasa_node * node )

Is atom polar.

Parameters

node	A node of type FREESASA_NODE_ATOM.

Returns: 1 if polar, 0 else.

◆ freesasa_node_atom_is_mainchain()

int freesasa_node_atom_is_mainchain ( const freesasa_node * node )

Does atom belong to the main chain/backbone.

Parameters

node	A node of type FREESASA_NODE_ATOM.

Returns: 1 if mainchain, 0 else.

◆ freesasa_node_atom_radius()

double freesasa_node_atom_radius ( const freesasa_node * node )

Atom radius.

Parameters

node	A node of type FREESASA_NODE_ATOM.

Returns: The radius.

◆ freesasa_node_atom_pdb_line()

const char * freesasa_node_atom_pdb_line ( const freesasa_node * node )

Line in PDB atom was generated from.

Parameters

node	A node of type FREESASA_NODE_ATOM.

Returns: The line. NULL if atom wasn't taken from PDB file.

◆ freesasa_node_atom_residue_number()

const char * freesasa_node_atom_residue_number ( const freesasa_node * node )

Atom residue number.

Parameters

node	A node of type FREESASA_NODE_ATOM.

Returns: The residue sequence number that this atom is a part of.

◆ freesasa_node_atom_residue_name()

const char * freesasa_node_atom_residue_name ( const freesasa_node * node )

Atom residue name.

Parameters

node	A node of type FREESASA_NODE_ATOM.

Returns: The residue 3-char name this atom is a part of.

◆ freesasa_node_atom_chain()

char freesasa_node_atom_chain ( const freesasa_node * node )

Atom chain.

Parameters

node	A node of type FREESASA_NODE_ATOM.

Returns: The chain this atom is a part of.

◆ freesasa_node_residue_number()

const char * freesasa_node_residue_number ( const freesasa_node * node )

Residue number.

Parameters

node	A node of type FREESASA_NODE_RESIDUE.

Returns: String with residue number.

◆ freesasa_node_residue_n_atoms()

int freesasa_node_residue_n_atoms ( const freesasa_node * node )

Number of atoms in a residue.

Parameters

node	A node of type FREESASA_NODE_RESIDUE.

Returns: Number of atoms.

◆ freesasa_node_residue_reference()

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

node	A node of type FREESASA_NODE_RESIDUE.

Returns: The reference area. NULL if area not available.

◆ freesasa_node_chain_n_residues()

int freesasa_node_chain_n_residues ( const freesasa_node * node )

The number of residues in a chain.

Parameters

node	A node of type FREESASA_NODE_CHAIN.

Returns: Number of residues.

◆ freesasa_node_structure_n_chains()

int freesasa_node_structure_n_chains ( const freesasa_node * node )

The number of chains in a structure.

Parameters

node	A node of type FREESASA_NODE_STRUCTURE.

Returns: Number of chains.

◆ freesasa_node_structure_n_atoms()

int freesasa_node_structure_n_atoms ( const freesasa_node * node )

The number of atoms in a structure.

Parameters

node	A node of type FREESASA_NODE_STRUCTURE.

Returns: Number of atoms.

◆ freesasa_node_structure_chain_labels()

const char * freesasa_node_structure_chain_labels ( const freesasa_node * node )

All chain labels in a structure.

Parameters

node	A node of type FREESASA_NODE_STRUCTURE.

Returns: Chain labels as null-terminated string.

◆ freesasa_node_structure_model()

int freesasa_node_structure_model ( const freesasa_node * node )

Model number of a structure (from input PDB)

Parameters

node	A node of type FREESASA_NODE_STRUCTURE.

Returns: Model number.

◆ freesasa_node_structure_result()

const freesasa_result * freesasa_node_structure_result ( const freesasa_node * node )

Raw results for a structure.

Parameters

node	A node of type FREESASA_NODE_STRUCTURE.

Returns: The results.

◆ freesasa_node_structure_selections()

const freesasa_selection ** freesasa_node_structure_selections ( const freesasa_node * node )

Selection results for a structure.

Generated using freesasa_node_structure_add_selection().

Parameters

node	A node of type FREESASA_NODE_STRUCTURE.

Returns: A null-terminated array of pointers to selections. NULL if no selections were associated with structure.

◆ freesasa_node_structure_add_selection()

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

node	A node of type FREESASA_NODE_STRUCTURE.
selection	A selection.

Returns: FREESASA_SUCCESS. FREESASA_FAIL if cloning fails (i.e. memory allocation failure).

◆ freesasa_node_result_parameters()

const freesasa_parameters * freesasa_node_result_parameters ( const freesasa_node * node )

Parameter values used to calculate result.

Parameters

node	A node of type FREESASA_NODE_RESULT

Returns: The parameters.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ freesasa_node

Enumeration Type Documentation

◆ freesasa_output_options

◆ freesasa_nodetype

Function Documentation

◆ freesasa_tree_new()

◆ freesasa_tree_init()

◆ freesasa_tree_add_result()

◆ freesasa_tree_join()

◆ freesasa_tree_export()

◆ freesasa_node_free()

◆ freesasa_node_area()

◆ freesasa_node_children()

◆ freesasa_node_next()

◆ freesasa_node_parent()

◆ freesasa_node_type()

◆ freesasa_node_name()

◆ freesasa_node_classified_by()

◆ freesasa_node_atom_is_polar()

◆ freesasa_node_atom_is_mainchain()

◆ freesasa_node_atom_radius()

◆ freesasa_node_atom_pdb_line()

◆ freesasa_node_atom_residue_number()

◆ freesasa_node_atom_residue_name()

◆ freesasa_node_atom_chain()

◆ freesasa_node_residue_number()

◆ freesasa_node_residue_n_atoms()

◆ freesasa_node_residue_reference()

◆ freesasa_node_chain_n_residues()

◆ freesasa_node_structure_n_chains()

◆ freesasa_node_structure_n_atoms()

◆ freesasa_node_structure_chain_labels()

◆ freesasa_node_structure_model()

◆ freesasa_node_structure_result()

◆ freesasa_node_structure_selections()

◆ freesasa_node_structure_add_selection()

◆ freesasa_node_result_parameters()