Choose a census path

A census path is the order in which you group rows. Site followed by exam lets you browse exams within each site; exam followed by site starts with individual exams. Use df and fw from Getting started for this example.

Ask for a useful order

paths = fw.suggest_paths(df, features=["site", "exam"])
print(paths)

Fieldwork · paths
Population: 6 rows
Search coverage (untested work is unknown)
  paths: 1/1 pairs evaluated
  paths: 2/2 features evaluated
[f0] site → exam
  Analysis: rows; presence=per_row
  Observed prefix groups: site: 2 → exam: 3
  Supported coarse-to-fine nesting: site → exam
  Availability nonmodal fractions: 0, 0
  Unit: rows; score=0.125, prefix_cost=0.125, overflow=0.0, nesting_inversions=0, redundant_steps...
  Examples: 3/6 saved source positions [0, 1, 2]
  Exceptions: 0/0 saved source positions []

The recommendation puts site before exam because sites contain exams in this table. Read its explanation to understand the choice, then use the recommended path to build a census:

recommended_path = paths.best
if recommended_path is None:
    print("No path was found. Choose the grouping columns yourself.")
else:
    tree = recommended_path.census(df)
    print(fw.render_plaintext(tree))

Fieldwork · census
Census (computed)
  Input population · 6 evaluated / 6 input rows · 0 missing, 0 restricted exclusions
  path: site > exam
  total: 6 rows
    site=North: 4 rows
      exam=1: 2 rows
      exam=2: 2 rows
    site=South: 2 rows
      exam=3: 2 rows

A search can return no path when its limits or constraints leave no valid choice. You can always choose an order directly, as in fw.census(df, ["site", "exam"]).

Start with a particular column

If you know that readers will begin by choosing a site, make that starting point explicit:

site_first = fw.suggest_paths(
    df,
    features=["site", "exam", "image_2"],
    start_with=["site"],
)
print(site_first)

Fieldwork · paths
Population: 6 rows
Search coverage (untested work is unknown)
  paths: 3/3 pairs evaluated
  paths: 3/3 features evaluated
[f0] site → exam → image_2
  Analysis: rows; presence=per_row
  Observed prefix groups: site: 2 → exam: 3 → image_2: 6
  Supported coarse-to-fine nesting: exam → image_2, site → exam, site → image_2
  Availability nonmodal fractions: 0.167, 0.167, 0
  Unit: rows; score=0.275, prefix_cost=0.275, overflow=0.0, nesting_inversions=0, redundant_steps...
  Examples: 3/6 saved source positions [0, 1, 2]
  Exceptions: 0/0 saved source positions []

For a different question, choose an objective:

Objective	Use it to
structure (default)	Browse from broader groups to finer groups.
availability	Separate patterns of filled and missing fields.
compact	Keep the intermediate groups manageable.
target	Separate values of a chosen target="column".
context	Compare groups within a fixed start_with=[...] prefix.

exclude removes columns from consideration. before=[("site", "exam")] requires both columns and puts site earlier, without necessarily making it the first column.

Read a recommendation in context

Reordering the same columns changes the intermediate groups, but not their final joint counts. Recommendations balance those intermediate groups and the observed nesting; they are not proof of a permanent hierarchy.

Search limits, passed as limits={...}, control how many choices Fieldwork considers. Its display_budget influences the preferred tree size and its saved preview. Read paths["coverage"] when you need to know what was examined or skipped; see the full reference.

recommended_path.census(df) carries forward the original row selection and missing-value conventions. Pass the unchanged source dataframe. For a different dataset or selection, run suggest_paths again. Copying only recommended_path.dimensions into a new census does not carry those settings forward.

Once you have chosen an order, fw.profile counts each dimension, builds the census, and relates pairs of dimensions in one result.