kary_tree_weighted_graph_helpers: Intrinsically weighted k-ary tree helpers

Description

Convenience helpers that keep the exact edges.kary.tree() topology but assign edge lengths directly from combinatorial tree metadata rather than from an ambient Euclidean embedding. Each edge weight is constructed as $$\mathrm{base\_length} \times \mathrm{depth\_factor(child\ depth)} \times \mathrm{branch\_factor(child\ slot)}$$ so the user can control tapering with depth separately from child-slot asymmetry.

Usage

kary.tree.weighted.graph(
  k = 2,
  depth = 2,
  base_length = 1,
  depth_rule = c("geometric", "constant", "custom"),
  depth_decay = 0.85,
  depth_factors = NULL,
  branch_rule = c("linear", "uniform", "custom"),
  branch_spread = 0.3,
  branch_factors = NULL,
  normalize = c("median", "mean", "none")
)

Value

A list with components:

edges: the k-ary tree edges,
n: number of vertices,
edge_weights: normalized positive intrinsic edge lengths,
weight_scale: normalization constant applied to the raw edge lengths,
vertex_depth: depth of each vertex, with the root at depth 0,
parent: parent vertex index for each vertex, with the root parent recorded as 0,
edge_table: data frame containing parent, child, parent_depth, child_depth, branch_index, raw_weight, and normalized edge_weight,
depth_factors: the applied per-depth multipliers,
branch_factors: the applied per-child-slot multipliers,
family: always "kary.tree.weighted",
k: the branching factor,
depth: the requested tree depth,
label: a human-readable family label.

Arguments

k: Branching factor. Must be at least 1.
depth: Number of levels below the root. May be 0.
base_length: Positive global edge-length multiplier before normalization.
depth_rule: Rule used to build the per-depth multipliers. One of "geometric", "constant", or "custom".
depth_decay: Positive decay factor used when depth_rule = "geometric".
depth_factors: Positive custom depth multipliers. Used only when depth_rule = "custom". Must have length 1 or depth.
branch_rule: Rule used to build the per-child-slot multipliers. One of "linear", "uniform", or "custom".
branch_spread: Non-negative spread used when branch_rule = "linear".
branch_factors: Positive custom branch multipliers. Used only when branch_rule = "custom". Must have length 1 or k.
normalize: Normalization applied to the raw intrinsic edge lengths. One of "median", "mean", or "none".

Details

The returned object is intended as an intrinsic weighted-tree benchmark family. It exposes the same edge matrix as edges.kary.tree() together with edge weights, vertex depths, parent indices, and an edge table that records the depth and branch slot associated with each tree edge.