Choose a census path

Path search ranks observed intermediate prefixes, branching, redundant steps and supported nesting. It returns alternatives with different feature sets, collapsing equivalent alias substitutions. Each path stores measured reasons and an explanation naming actual features, prefix groups, nesting, redundancy, and availability or target separation.

paths = fw.suggest_paths(
    df, objective="structure", start_with=["site"],
    before=[("site", "exam")], max_dimensions=3,
)
if paths.best is not None:
    tree = paths.best.census(df)

Objective	Use it to
structure	Put supported coarse groupings before finer ones
availability	Bring record availability signatures into view
compact	Reduce intermediate branching and redundant steps
target	Distinguish a selected target’s values; supply target="column"
context	Compare from a fixed context; supply start_with=[...]

exclude removes features; before enforces precedence and requires its referenced features in the path. Contradictory constraints raise ValueError. A target is excluded from candidate browsing dimensions unless explicitly required. Constants are omitted unless required, and equivalent fields remain recorded as aliases.

max_features, max_pairs, max_candidates, and beam_width limit search work. display_budget shapes ranking and preview size. coverage records omissions and returned depth; a tight search budget may return a shorter path or no valid path. Handle paths.best is None or supply dimensions directly.

Reordering the same dimensions changes intermediate prefixes, not their complete joint distribution. See measurement definitions for the scoring formula.

paths.best.census(df) and paths.path(i).census(df) preserve the recommendation’s original scope, sentinel conventions and table identity, including after JSON restoration. They validate the source dataframe and reject context overrides. Rerun discovery to change populations or deliveries. path.dimensions is only an ordered tuple; passing it to a separate fw.census call does not transfer context.