Cuts a tree at a defined node, discarding the nodes and information below it.
Option
RENUMBER = string token |
Whether or not to renumber the nodes of the tree (yes, no); default no |
|---|
Parameters
TREE = trees |
Trees to be cut |
|---|---|
NODE = scalars |
Node at which to cut each tree |
NEWTREE = trees |
New trees with the information cut; if unspecified, the new tree replaces the original tree |
CUTTREE = trees |
Tree formed from the branches cut from the original tree |
OLDNODES = variates |
Mapping from old nodes to node numbers in a renumbered new tree (as positive numbers) or to nodes in the CUTTREE (as negative numbers) |
NEWNODES = variates |
Mapping from new node numbers in a renumbered tree to the original nodes |
CUTNODES = variates |
Mapping from node numbers in the CUTTREE tree to the original nodes |
Description
BCUT provides the basic tree utility of removing an unwanted branch, which is used for example by the BPRUNE procedure. Other tree utilities are described in the description of the TREE directive (which declares and initializes a tree).
The tree to be cut is specified by the TREE parameter, and the NODE parameter indicates the node at which the cut is to be made. The NEWTREE parameter can supply the identifier for the new tree (after removing all the nodes below NODE); if this is not specified, the new tree replaces the original tree. The subtree below NODE can also be saved (as a tree in its own right, with NODE as the root) using the CUTTREE parameter.
The OLDNODES parameter can save a variate containing a mapping from the old nodes to the new nodes. If the node is a member of the new tree the variate contains the number of that node in the NEWTREE, while if it is one of the nodes that are deleted the variate contains -1 multiplied by its number in the CUTTREE. As far as OLDNODES is concerned NODE is regarded as a member of the NEWTREE.
The NEWNODES parameter can save a variate containing the converse mapping from the NEWTREE to the original tree. There is an element for each new node, containing the number of the equivalent node in the original tree. Similarly, the CUTNODES parameter can save a mapping from the CUTTREE to the original tree.
Option: RENUMBER.
Parameters: TREE, NODE, NEWTREE, CUTTREE, OLDNODES, NEWNODES, CUTNODES.
See also
Directives: BCUT, BGROW, BJOIN, TREE.
Procedures: BCONSTRUCT, BCLASSIFICATION, BGRAPH, BKEY, BPRINT, BPRUNE.
Functions: BBELOW, BBRANCHES, BDEPTH, BMAXNODE, BNBRANCHES, BNEXT, BNNODES, BPATH, BPREVIOUS, BSCAN, BTERMINAL.
Commands for: Calculations and manipulation.
Example
" Examples 1:4.12.3, 1:4.12.4 & 1:4.12.5 "
" Declare the original tree."
TREE T
" Define texts to use as labels for the nodes."
TEXT Lab[1...26]; VALUES=\
'a','b','c','d','e','f','g','h','i','j','k','l','m',\
'n','o','p','q','r','s','t','u','v','w','x','y','z'
" Define information at root to be a pointer
with a single element called 'label'."
POINTER [NVALUES=!t(label)] T[1]
" Set that element to the first value of Lab, i.e. 'a'."
TEXT T[1]['label']; VALUE=Lab[1]
" Display the tree - first with labels of nodes, then with numbers."
BPRINT [PRINT=labelleddiagram,numbereddiagram] T
" Extend the tree by forming 3 branches from node 1 (root)."
BGROW T; NODE=1; NBRANCH=3; NEWNODES=Gnew
" Define the information for the new nodes."
POINTER [NVALUES=!t(label)] T[#Gnew]
TEXT T[#Gnew]['label']; VALUE=Lab[#Gnew]
" Display the extended tree."
BPRINT [PRINT=labelleddiagram,numbereddiagram] T
" Find the node number of the first terminal node "
CALCULATE N1 = BTERMINAL(T; 0)
" and then the second terminal node."
CALCULATE N2 = BTERMINAL(T; N1)
PRINT N1,N2; DECIMALS=0
" Extend the tree by adding 2 branches at the second
and then the first terminal node."
BGROW T; NODE=N2; NBRANCH=2; NEWNODES=Gnew2
" Define the information for the new nodes."
POINTER [NVALUES=!t(label)] T[#Gnew2]
TEXT T[#Gnew2]['label']; VALUE=Lab[#Gnew2]
BGROW T; NODE=N1; NBRANCH=2; NEWNODES=Gnew1
POINTER [NVALUES=!t(label)] T[#Gnew1]
TEXT T[#Gnew1]['label']; VALUE=Lab[#Gnew1]
" Display the extended tree."
BPRINT [PRINT=labelleddiagram,numbereddiagram] T
"4.12.4 Remove the branches below N2, saving these as tree T2;
also save and print the node mapping variates."
BCUT T; NODE=N2; CUTTREE=T2; OLDNODES=Oldn;\
NEWNODES=Newn; CUTNODES=Cutn
PRINT [ORIENT=across] Oldn,Newn,Cutn; FIELD=3; DECIMALS=0
" Display the modified tree, and the cut-tree."
BPRINT [PRINT=labelleddiagram,numbereddiagram] T,T2
" Redefine the root of the cut tree so that it no
longer shares the same information pointer as the
node where the cut was made in the original tree."
POINTER [NVALUES=!t(label)] T2root
TEXT T2root['label']; VALUE='t2root'
ASSIGN T2root; T2; 1
BPRINT [PRINT=labelleddiagram] T2
" Use BCUT to form T3 as a duplicate of T
but with renumbered nodes."
BCUT [RENUMBER=yes] T; NEWTREE=T3
BPRINT [PRINT=labelleddiagram,numbereddiagram] T3
"4.12.5 Join tree T2 onto node 4 of T3; save and print the
numbers of the joined nodes in the revised tree."
BJOIN T3; NODE=4; JOINTREE=T2; NEWNODES=Jnew
BPRINT [PRINT=labelleddiagram,numbereddiagram] T3
PRINT Jnew; DECIMALS=0
" Tree functions: all nodes below node 2,"
CALCULATE Below = BBELOW(T3; 0; 0)
PRINT Below; DECIMALS=0
" all terminal nodes below node 2,"
CALCULATE Below0 = BBELOW(T3; 0; 0)
PRINT Below0; DECIMALS=0
" first three terminal nodes,"
CALCULATE N1 = BTERMINAL(T3; 0)
& N2 = BTERMINAL(T3; N1)
& N3 = BTERMINAL(T3; N2)
PRINT N1,N2,N3; DECIMALS=0
" nodes and branches on path to N3,"
CALCULATE Pn3 = BPATH(T3; N3)
& Ln3 = BBRANCHES(T3; N3)
PRINT Pn3,Ln3; DECIMALS=0
" depth and number of branches at node 2,"
CALCULATE Nn2 = BNBRANCHES(T3; 2)
& Dn2 = BDEPTH(T3; 2)
PRINT Nn2,Dn2; DECIMALS=0
" next nodes on branches 1-3 from node 1,
and branch 1 from node 2."
PRINT BNEXT(T3; 1; 1); DECIMALS=0
PRINT BNEXT(T3; 1; 2); DECIMALS=0
PRINT BNEXT(T3; 1; 3); DECIMALS=0
PRINT BNEXT(T3; 2; 1); DECIMALS=0
" Scan the tree, taking the nodes in standard order."
SCALAR Scan[0]; value=0
CALCULATE Scan[1] = BSCAN(T3; Scan[0])
& Scan[2] = BSCAN(T3; Scan[1])
& Scan[3] = BSCAN(T3; Scan[2])
& Scan[4] = BSCAN(T3; Scan[3])
& Scan[5] = BSCAN(T3; Scan[4])
& Scan[6] = BSCAN(T3; Scan[5])
& Scan[7] = BSCAN(T3; Scan[6])
& Scan[8] = BSCAN(T3; Scan[7])
& Scan[9] = BSCAN(T3; Scan[8])
PRINT Scan[1...9]; FIELD=8; DECIMALS=0