ppforest2::viz Namespace Reference

Classes
struct	BoundarySegment
	A clipped decision boundary line segment in 2D feature space. More...
struct	BoundaryVisitor
	Visitor that collects and clips decision boundary line segments. More...
struct	HalfSpace
	A half-space constraint derived from an ancestor split. More...
struct	LayoutEdge
	An edge between two positioned nodes with a threshold label. More...
struct	LayoutNode
	A positioned tree node in the computed layout. More...
struct	LayoutParams
	Layout parameters for tree structure rendering. More...
struct	NodeData
	Per-node data collected by routing observations through the tree. More...
struct	NodeDataVisitor
	Visitor that routes observations through the tree and collects per-node projection data for histogram rendering. More...
struct	RegionPolygon
	A convex decision region polygon in 2D with its predicted group. More...
struct	RegionVisitor
	Visitor that collects convex decision region polygons. More...
struct	TreeLayout
	Complete tree layout: positioned nodes and labelled edges. More...

Typedefs
using	Polygon = std::vector<std::pair<types::Feature, types::Feature>>
	A polygon represented as an ordered list of (x, y) vertex pairs.

Functions
types::Feature	adjust_threshold (types::FeatureVector const &full_proj, types::Feature thr, std::vector< std::pair< int, types::Feature > > const &fixed_vars)
	Adjust a split threshold by subtracting contributions of fixed variables.
bool	clip_boundary_2d (types::FeatureVector const &a, types::Feature threshold, std::vector< HalfSpace > const &constraints, types::Feature x_min, types::Feature x_max, types::Feature y_min, types::Feature y_max, BoundarySegment &segment, int depth)
	Clip a 2D decision boundary line to the visible rectangle and all ancestor half-space constraints.
bool	clip_param_to_range (types::Feature origin, types::Feature direction, types::Feature range_min, types::Feature range_max, types::Feature &u_min, types::Feature &u_max)
	Clip a parametric interval [u_min, u_max] to a 1D range.
Polygon	clip_polygon_halfspace (Polygon const &polygon, types::FeatureVector const &normal, types::Feature threshold, bool is_lower)
	Clip a convex polygon against a single half-space.
TreeLayout	compute_tree_layout (TreeNode const &root, LayoutParams const &params=LayoutParams())
	Compute a left-aligned tree layout for rendering.
types::FeatureVector	project_2d (types::FeatureVector const &full_proj, int var_i, int var_j)
	Extract a 2D sub-projection from a full p-dimensional projector.

Typedef Documentation

Polygon

using ppforest2::viz::Polygon = std::vector<std::pair<types::Feature, types::Feature>>

A polygon represented as an ordered list of (x, y) vertex pairs.

Function Documentation

adjust_threshold()

types::Feature ppforest2::viz::adjust_threshold	(	types::FeatureVector const &	full_proj,
		types::Feature	thr,
		std::vector< std::pair< int, types::Feature > > const &	fixed_vars )

Adjust a split threshold by subtracting contributions of fixed variables.

When projecting from p dimensions to 2D, the remaining (p − 2) variables are held at fixed values (typically medians). The effective 2D threshold is: t' = t − Σ_{k ∈ fixed} projector_k × value_k

Parameters

full_proj	Full projector vector (p).
thr	Original p-dimensional threshold.
fixed_vars	Pairs of (variable index, fixed value) for non-displayed variables.

Returns

Adjusted 2D threshold.

clip_boundary_2d()

bool ppforest2::viz::clip_boundary_2d	(	types::FeatureVector const &	a,
		types::Feature	threshold,
		std::vector< HalfSpace > const &	constraints,
		types::Feature	x_min,
		types::Feature	x_max,
		types::Feature	y_min,
		types::Feature	y_max,
		BoundarySegment &	segment,
		int	depth )

Clip a 2D decision boundary line to the visible rectangle and all ancestor half-space constraints.

The boundary of a split with 2D projector a and threshold threshold is the line a^T x = threshold. This function parametrizes the line, clips to the bounding box [x_min, x_max] × [y_min, y_max], then clips against each ancestor constraint. If any visible portion remains, writes the endpoints into segment and returns true.

Algorithm (parametric line clipping):

1. Compute direction D = (-a1, a0) tangent to the boundary line.
2. Find a base point P0 on the line: a^T P0 = threshold.
3. Parametrize as P(u) = P0 + u·D with u ∈ (-∞, +∞).
4. Clip [u_min, u_max] to the bounding box (clip_param_to_range).
5. For each ancestor constraint a_c^T x ⋛ t_c, compute the intersection parameter and tighten the interval.
6. If u_min < u_max, the segment P(u_min)→P(u_max) is visible.

Parameters

	a	2D projection of the split's projector.
	threshold	Adjusted 2D threshold.
	constraints	Ancestor half-space constraints (already in 2D).
	x_min,x_max,y_min,y_max	Visible bounding box.
[out]	segment	Output segment (valid only if function returns true).
	depth	Tree depth of this split (stored in the segment).

Returns

true if a visible segment remains after clipping.

See also

clip_param_to_range, BoundaryVisitor

clip_param_to_range()

bool ppforest2::viz::clip_param_to_range	(	types::Feature	origin,
		types::Feature	direction,
		types::Feature	range_min,
		types::Feature	range_max,
		types::Feature &	u_min,
		types::Feature &	u_max )

Clip a parametric interval [u_min, u_max] to a 1D range.

Given a parametric line x(u) = origin + u × direction, restricts the interval [u_min, u_max] so that x(u) ∈ [range_min, range_max].

Parameters

	origin	Starting value.
	direction	Rate of change.
	range_min	Lower bound of the range.
	range_max	Upper bound of the range.
[in,out]	u_min	Current lower parameter bound (tightened in place).
[in,out]	u_max	Current upper parameter bound (tightened in place).

Returns

true if a valid interval remains (u_min < u_max).

clip_polygon_halfspace()

Polygon ppforest2::viz::clip_polygon_halfspace	(	Polygon const &	polygon,
		types::FeatureVector const &	normal,
		types::Feature	threshold,
		bool	is_lower )

Clip a convex polygon against a single half-space.

Implements one pass of the Sutherland–Hodgman algorithm. The half-space is defined by:

• is_lower = true: normal^T x < threshold (strict)
• is_lower = false: normal^T x >= threshold

Vertices are processed in order; edges crossing the boundary are split at the intersection point. The result is a (possibly empty) polygon fully contained in the half-space.

For each edge (curr → next), exactly one of four cases applies:

• Both inside: emit next.
• Leaving (curr inside, next outside): emit intersection.
• Entering (curr outside, next inside): emit intersection + next.
• Both outside: emit nothing.

Convexity is preserved: clipping a convex polygon against a half-space always produces a convex polygon (or empty).

Complexity: O(n) where n = number of polygon vertices.

Parameters

polygon	Input polygon (ordered vertices).
normal	2D normal vector of the half-space boundary.
threshold	Offset of the half-space boundary.
is_lower	Which side of the boundary to keep.

Returns

Clipped polygon (empty if fully outside).

See also

RegionVisitor

compute_tree_layout()

TreeLayout ppforest2::viz::compute_tree_layout	(	TreeNode const &	root,
		LayoutParams const &	params = LayoutParams() )

Compute a left-aligned tree layout for rendering.

Recursively positions nodes on a 2D canvas:

• Internal nodes are centered above their left child (left-aligned).
• Leaf nodes are placed at the bottom of their subtree column.
• y decreases with depth (root at top, leaves at bottom).
• Sibling subtrees are separated by params.gap.

Edges connect each parent's bottom center to each child's top center. Each edge is labelled with the split direction and threshold value (e.g. "< 1.50" for the lower child, "≥ 1.50" for the upper child).

Nodes are accumulated in pre-order traversal (matching NodeDataVisitor's order, so indices correspond). This invariant is critical: the R layer uses the pre-order index to match layout positions with the node data from NodeDataVisitor.

Algorithm (recursive bottom-up):

1. For a leaf, place it at x_offset + leaf_w/2 and return its width.
2. For an internal node, layout left and right subtrees side-by-side (with gap), then place the parent above the left child's center.
3. Total subtree width = left_width + gap + right_width.

Parameters

root	Root node of the tree to layout.
params	Layout dimensions and spacing (default: LayoutParams()).

Returns

TreeLayout with positioned nodes and edges.

project_2d()

types::FeatureVector ppforest2::viz::project_2d	(	types::FeatureVector const &	full_proj,
		int	var_i,
		int	var_j )

Extract a 2D sub-projection from a full p-dimensional projector.

Returns a 2-vector containing the components at indices var_i and var_j. Used to reduce a p-dimensional split to the 2D plane being visualized.

Parameters

full_proj	Full projector vector (p).
var_i	Index of the x-axis variable (0-based).
var_j	Index of the y-axis variable (0-based).

Returns

2D projection vector [full_proj(var_i), full_proj(var_j)].