Getting nodes

In this chapter, you will learn how to collect nodes from the data graph and from other nodes which might not even be the part of the data graph.

The main function to collect nodes is getNodes which allows you to collect nodes that belong to some node (e.g. document, molecule, residue, etc). Please, refer to the SBDDataGraphNode::getNodes function documentation to learn more about its parameters and how it works.

You can also use SAMSON::getNodes facade functions to collect nodes either based on the Node Specification Language or based on node's position in the viewport.

Node predicates

The SBDDataGraphNode class defines a series of node predicates, i.e. functors that may be used to e.g. collect nodes in the data graph. For example, the SBNode::IsType predicate may be used to collect nodes by type (each node has a type):

// Find all atoms in the active document
SBNodeIndexer nodeIndexer;
SAMSON::getActiveDocument()->getNodes(nodeIndexer,
    SBNode::IsType(SBNode::Atom));

// Find all residues in the active document
SBNodeIndexer nodeIndexer;
SAMSON::getActiveDocument()->getNodes(nodeIndexer,
    SBNode::IsType(SBNode::Residue));

Since this is a common scenario to get nodes of a certain type, there is a convenience variant of this function that gets only SBNode::Type, so the above-mentioned examples can be transformed as follows:

// Find all atoms in the active document
SBNodeIndexer nodeIndexer;
SAMSON::getActiveDocument()->getNodes(nodeIndexer,
    SBNode::Atom);

// Find all residues in the active document
SBNodeIndexer nodeIndexer;
SAMSON::getActiveDocument()->getNodes(nodeIndexer,
    SBNode::Residue);

The SBNode::IsSelected predicate may be used to collect all nodes that are selected (directly, because their selection flag is true, or because one of their ancestors is selected):

// Find all selected nodes in the active document
SBNodeIndexer nodeIndexer;
SAMSON::getActiveDocument()->getNodes(nodeIndexer,
    SBNode::IsSelected());

Predicates may be combined through logical operations.

For example, collecting selected atoms may be achieved with:

// Find all selected atoms in the active document
SBNodeIndexer nodeIndexer;
SAMSON::getActiveDocument()->getNodes(nodeIndexer,
    SBNode::IsType(SBNode::Atom) && SBNode:IsSelected());

You may collect nodes in a node indexer from different nodes or collect nodes from a node indexer. For example, let's say we have a nodeIndexer and we want to collect all atoms from it. This canbe done in the following way:

SBNodeIndexer atomIndexer;
SB_FOR(SBNode* node, nodeIndexer)
    node->getNodes(atomIndexer, SBNode::IsType(SBNode::Atom));

Node getters

The SBDDataGraphNode class also defines a series of node getters, i.e. functors that may be used to collect nodes in the data graph. Node getters may be used to construct node predicates through comparison operators, so that collecting all atoms may also be achieved with:

// Find all atoms
SBNodeIndexer nodeIndexer;
SAMSON::getActiveDocument()->getNodes(nodeIndexer,
    SBNode::GetType() == SBNode::Atom);

since the statement SBNode::GetType() == SBNode::Atom constructs a node predicate that is passed to the getNodes function.

In general, node getters have the same name as the corresponding getter function, but the first letter of their name is capitalized, since they are classes. For example, just like the SBNode::GetType getter corresponds to the SBNode::getType function, the SBAtom::GetTemperatureFactor getter corresponds to the SBAtom::getTemperatureFactor function.

Node predicates and node getters may be used to collect nodes from potentially complex rules:

// Find all selected atoms with a large enough temperature factor
SBNodeIndexer nodeIndexer;
SAMSON::getActiveDocument()->getNodes(nodeIndexer, 
    SBNode::IsSelected() &&
    SBNode::IsType(SBNode::Atom) &&
    (SBAtom::GetTemperatureFactor() > 2.0));

// Find all atoms which have a partial charge larger than 0.4f
SBNodeIndexer nodeIndexer;
SAMSON::getActiveDocument()->getNodes(nodeIndexer,
    SBNode::IsType(SBNode::Atom) &&
    SBAtom::HasPartialCharge() &&
    (SBAtom::GetPartialCharge() >= 0.4f));

Node predicates and node getters constitute the foundation of SAMSON's Node Specification Language.

Selection strings

SAMSON provides a powerful Node Specification Language which can be used both by users and by developers to select and collect nodes. Please refer to Node Specification Language for more information on how to use it.

SAMSON provides the SAMSON::makeNodePredicate function which make a node predicate based on an Node Specification Language selection string. Please, refer to the SAMSON::makeNodePredicate function documentation.

Examples:

// A predicate that is true if and only if the node is an atom
SBNodePredicate* nodePredicate = SAMSON::makeNodePredicate("node.type atom");
 
SBNodeIndexer nodeIndexer;
SAMSON::getActiveDocument()->getNodes(nodeIndexer, *nodePredicate);

// A predicate that is true if and only if the node a residue in alpha helix
SBNodePredicate* nodePredicate = SAMSON::makeNodePredicate("residue.secondaryStructure helix");

// A predicate that is true if and only if the node is a sidechain that has at least one Sulfur atom
SBNodePredicate* nodePredicate = SAMSON::makeNodePredicate("node.type sidechain having S");

// A predicate that is true if and only if the node is a hydrogen atom bonded to an oxygen atom
SBNodePredicate* nodePredicate = SAMSON::makeNodePredicate("H linking O");

Or you can use an NSL string directly to get the nodes from the active document:

// Select from the active document all hydrogen atoms bonded to oxygen atoms
 
SBNodeIndexer nodeIndexer;
SAMSON::getNodes(nodeIndexer, "H linking O");

Please refer to Node Specification Language for more information.