Results and configuration

Result methods

Interface	Behavior
result.to_dict()	Strict-JSON-compatible evidence
Foundation to_dict(resolve_references=True)	Readable labels alongside compact IDs
Discovery result.to_frame(section="findings")	Tabular projection of a list section
Discovery result.inspect(df, finding, exceptions=False, all_matches=False)	Saved representative source rows by finding ID or index
InvestigationResult.from_dict(data)	Restore schema 1.0 saved discovery evidence
paths.best.dimensions	Recommended census order; best may be None
Scope.from_positions(df, positions, name=...)	Source-bound population selection
scope.refine(df, positions, name=...)	Subset selection with parent lineage
Recipe(operation, parameters={}, notes="")	Versioned strict JSON operation arguments
recipe.save(path), Recipe.load(path), recipe.run(df, **overrides)	Persist and reapply an investigation

Foundation results use schema 0.3; discovery results use schema 1.0. These are evidence schema versions, distinct from package version 0.1.0; the package remains alpha. Nested payload dictionaries are mutable. Native nonfinite scalar values use typed encodings so strict JSON stays valid.

Saved individual discovery results can recover more evidence with result.recompute(df, example_limit=len(df)). This restores the original parameters, missing conventions and scope, validates the source identity, and reruns the analysis. Call inspect on the new result to retrieve its saved rows. Overview and comparison results are compositions; recompute an individual section instead.

Common discovery arguments

• features: selected unique string column names; default all.
• scope: a reusable source-bound Scope; default all rows.
• missing: column-to-sentinel-list mapping; native missing is always recognized.
• table_id: nonempty table identity, default "table".
• example_limit: saved rows per example/exception selection, default 5.
• by: joint context columns for availability, dependencies or populated patterns.

Search limits are in coverage; display omissions are in the relevant result or renderer. They never mean an unevaluated candidate failed. See measurements for each denominator and search order.

Foundation-specific controls

KeySpec(name, columns) declares composite grain candidates. Census top_n_mode="post" computes over the input population and limits output; "pre" selects a cohort. top_n_per_parent controls whether preselection is within each prefix. Omitted branch mass remains reported.

explore(df, dimensions, ...) accepts the foundation composition options, including candidate_keys, features, pair contexts, declared domains, and output limits. explore(df) instead accepts a discovery dictionary for path search; common scope, missing, features and table identity apply to the overview sections. Do not pass the foundation keyword collection to implicit exploration.

Pair absence uses observed domains unless reference_domains declares alternatives. max_absence_cells bounds absent cells, separate from pair/context budgets. infer_schema produces role suggestions with evidence; it does not silently transform data.

Errors and boundaries

Unknown columns raise KeyError; invalid limits, incompatible constraints, changed inspection sources and duplicate columns raise ValueError. Discovery requires string names. Foundation supports additional typed labels. Recipes permit only allowlisted operations and JSON-compatible parameters; Python objects such as KeySpec cannot be saved directly. Automatic multi-table discovery and branch-adaptive path orders are not implemented.

Complete selections and connected evidence

result.select(df, finding, *, exceptions=False, name="finding selection") returns a source-bound Scope with every matching source row and parent lineage. inspect(..., all_matches=True) returns those rows directly. Both verify source identity and replay saved analysis settings; overview findings route to their owning section. Signatures, contexts and entity patterns are selectable, including after saving and restoring evidence.

overview.relationships(feature=None, *, kinds=None) returns typed feature connections and supporting evidence references. Connections retain their own counting units and populations. Connected components express reachability, not equivalence or a composed functional dependency.

paths.path(i).census(df) and paths.best.census(df) retain source scope and missing conventions. The source must match; context overrides are rejected.

Availability units and common context

missingness accepts unit="rows" (default) or unit="entities", with entity_presence="any" (default) or "all" for entity units. Entity units require entity keys. analysis_unit records the denominator, eligible rows, and missing-key exclusions. Entity summaries classify raw-row any/all/one/some/none presence.

Automatic explore accepts by, entity, unit, and entity_presence in discovery. Availability can count entities while path, dependency, and value-pattern evidence count rows. Top-level common context overrides apply across sections.

Foundation census and explicit-dimension explore also accept scope, missing, and table_id. Derived scopes retain original input counts and distinguish restrictions from missing exclusions. Typed integer and tuple column labels remain supported through this context adapter. Explicit-dimension explore accepts common context in discovery but rejects search-only options and duplicate settings.