% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/graph_helpers.R
\name{kary_tree_weighted_graph_helpers}
\alias{kary_tree_weighted_graph_helpers}
\alias{kary.tree.weighted.graph}
\title{Intrinsically weighted k-ary tree helpers}
\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{
\item{k}{Branching factor. Must be at least \code{1}.}

\item{depth}{Number of levels below the root. May be \code{0}.}

\item{base_length}{Positive global edge-length multiplier before
normalization.}

\item{depth_rule}{Rule used to build the per-depth multipliers. One of
\code{"geometric"}, \code{"constant"}, or \code{"custom"}.}

\item{depth_decay}{Positive decay factor used when
\code{depth_rule = "geometric"}.}

\item{depth_factors}{Positive custom depth multipliers. Used only when
\code{depth_rule = "custom"}. Must have length \code{1} or \code{depth}.}

\item{branch_rule}{Rule used to build the per-child-slot multipliers. One of
\code{"linear"}, \code{"uniform"}, or \code{"custom"}.}

\item{branch_spread}{Non-negative spread used when
\code{branch_rule = "linear"}.}

\item{branch_factors}{Positive custom branch multipliers. Used only when
\code{branch_rule = "custom"}. Must have length \code{1} or \code{k}.}

\item{normalize}{Normalization applied to the raw intrinsic edge lengths.
One of \code{"median"}, \code{"mean"}, or \code{"none"}.}
}
\value{
A list with components:
\itemize{
  \item \code{edges}: the \code{k}-ary tree edges,
  \item \code{n}: number of vertices,
  \item \code{edge_weights}: normalized positive intrinsic edge lengths,
  \item \code{weight_scale}: normalization constant applied to the raw edge
    lengths,
  \item \code{vertex_depth}: depth of each vertex, with the root at depth
    \code{0},
  \item \code{parent}: parent vertex index for each vertex, with the root
    parent recorded as \code{0},
  \item \code{edge_table}: data frame containing \code{parent},
    \code{child}, \code{parent_depth}, \code{child_depth},
    \code{branch_index}, \code{raw_weight}, and normalized
    \code{edge_weight},
  \item \code{depth_factors}: the applied per-depth multipliers,
  \item \code{branch_factors}: the applied per-child-slot multipliers,
  \item \code{family}: always \code{"kary.tree.weighted"},
  \item \code{k}: the branching factor,
  \item \code{depth}: the requested tree depth,
  \item \code{label}: a human-readable family label.
}
}
\description{
Convenience helpers that keep the exact \code{\link{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
\deqn{\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.
}
\details{
The returned object is intended as an intrinsic weighted-tree benchmark
family. It exposes the same edge matrix as \code{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.
}
