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