Skip to contents

Intrinsically weighted k-ary tree helpers

Source: R/export_examples.R, R/graph_helpers.R
kary_tree_weighted_graph_helpers.Rd

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")
)

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".

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.

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.

Examples

tree <- kary.tree.weighted.graph(k = 2, depth = 2)