fw.visualization_data

Use fw.visualization_data when you need the data behind Fieldwork’s visuals for a custom presentation. It returns a dictionary of display labels and the values needed to draw the selected result.

Choose result.to_dict() for the analytical archive. Choose this function for the presentation layer: its structure and disclosure level are designed around visual explanation.

Jump to the worked example or the argument reference.

Function reference

fw.visualization_data(
    result,
    *,
    section=None,
    detail='full',
    shading=None,
)

This page describes Fieldwork 0.3.2. Import the package with import fieldwork as fw. View the documented source.

Arguments

Argument	Type / default	Effect
result	Result or mapping; required	A fw.Result or its to_dict() export. Projection uses saved evidence and never reruns analysis or accesses the original dataframe.
section	str or None; None	Select a section of a composed result. Overview sections are missingness, dependencies, paths and value_patterns; profile sections are levels, census, grain and pairs. None projects the whole result.
detail	“full” or “topology”; 'full'	"full" includes quantitative evidence. "topology" suppresses quantitative support and selectors in the presentation, while keeping structural labels. It is not anonymization: labels can still identify people or records.
shading	mapping or None; None	Shading ranges for association and joint-count cells, typed as fieldwork.typing.Shading: {"association": rule, "counts": rule} with rule "equal", "log", "quantile" or three increasing cut-offs. None uses "equal" for association and "log" for counts. See shading ranges.

Returns and output choices

Returns a fresh dictionary for every result kind: the same projection the text, SVG and HTML renderers draw. kind and detail identify the projection; other fields depend on the result (for example, grain nodes and edges, overview findings, or schema proposals). A whole profile projects every section under sections. It does not mutate the input. Serialize the returned dictionary with json.dumps(data, allow_nan=False) when you need a JSON presentation artifact. Full-detail pairs and joint-count projections record the shading cut-offs and rule used under shading, for example {"counts": [1.0, 2.0, 3.0], "counts_rule": "log"}; topology projections carry no cut-offs.

Full dependency presentations include candidate summaries and every completed per-target test within display limits, including tests below the finding threshold. They distinguish observed target coverage from consistency on evaluated rows and repeat-only consistency. Missing-category tests are labeled. Candidate and test lists have separate display bounds; SVG shows at most five candidate summaries. The overview summary stays compact; render its dependencies section for detail. These numerical qualifications are absent from topology.

Interpretation and boundaries

detail="topology" removes quantities and source-row selectors. Where the full view orders items by frequency, the topology view uses a consistent order based on their values instead. It retains labels and qualitative structure: for example, whether a relationship is exact or approximate, whether a column, availability family or context is populated in all, some or none of its units, whether an exact rule has repeated support, candidate and key roles, reported string formats, and whether small cells were omitted. Do not treat it as anonymization, or as an archive from which missing quantitative evidence can be recovered.

The projected dictionary is not a result export: do not pass it to fw.Result.from_dict. Keep the original result if later inspection or selection matters. Unknown or uncomputed sections, invalid detail and invalid shading rules raise ValueError.

Full overview projections include section_coverage keyed by analytical section. These are search and retention bounds, independent of HTML/SVG display limits. Coverage is removed from topology projections along with quantitative evidence.

Walkthrough: an astronomy log, two presentation audiences

An astronomy club wants a small table for its observing-night report and a quantity-free target list for a planning board. Both should come from the same saved analysis. The table needs counts and an honest denominator; the planning board needs labels without the quantitative evidence.

fw.visualization_data creates a dictionary for drawing the result. Keep the analytical export separately: even detail="full" describes a presentation, not a complete archive of the analysis.

This example is verified against Fieldwork v0.3.2. The complete runnable script follows the same steps and saves the planning data as JSON.

Save the analysis before choosing a presentation

There are twelve observation entries: five for the Moon, three for Jupiter, two for Saturn, and two with no recorded target. Repeated observations count separately. These are entries, not distinct observers or observing nights.

import json

import pandas as pd
import fieldwork as fw

# Each row is one observation entry, including repeat observations of a target.
log = pd.DataFrame(
    {
        "entry": range(1, 13),
        "target": ["Moon"] * 5
        + ["Jupiter"] * 3
        + ["Saturn"] * 2
        + [None] * 2,
    }
)
result = fw.levels(log, ["target"], max_levels=3, dropna=False)
archive_json = json.dumps(result.to_dict(), allow_nan=False)
saved = json.loads(archive_json)
record = saved["per_feature"][0]
print("Archive: total levels, reported levels, unreported rows")
print(
    record["levels_total"],
    record["levels_reported"],
    record["unreported_rows"],
)

Archive: total levels, reported levels, unreported rows
4 3 2

The three-level cap retains ten entries across three named targets. The two missing-target entries remain in the evaluated population because dropna=False. The archive records four levels and two unreported rows; it does not retain individual level records for categories excluded by the cap.

Here, archive_json and saved are an in-memory JSON export and its decoded dictionary. The decoded dictionary can feed the presentation directly, without rerunning the analysis or reconstructing the original DataFrame.

Build a table for the report

full = fw.visualization_data(saved, detail="full")
feature = full["features"][0]
print(feature["scope"])
print("Target | Entries | Share of all entries")
for row in feature["rows"]:
    print(f"{row['label']} | {row['count']} | {row['share']:.1%}")

Input population · 12 evaluated / 12 input rows · 0 missing, 0 restricted exclusions
Target | Entries | Share of all entries
Moon | 5 | 41.7%
Jupiter | 3 | 25.0%
Saturn | 2 | 16.7%
Omitted levels | 2 | 16.7%

The scope’s “0 missing” means zero rows were excluded for missingness. It does not mean the log has no missing values. The Moon’s share is 5/12, not 5/10: the display cap does not renormalize the retained categories. The synthetic “Omitted levels” row carries the other 2/12 so their mass stays visible. Percentages rounded to one decimal place sum to 100.1% here.

Labels are already display strings. A string is quoted only when it could be read as a number, boolean or missing value. Labels are useful for a custom table, but are not a replacement for the archive’s values. The display dictionary omits source metadata. “Full” means the quantitative presentation, not every analytical field.

List targets without quantities

topology = fw.visualization_data(saved, detail="topology")
qualitative = topology["features"][0]
print("Targets for the planning board:")
for row in qualitative["rows"]:
    print(row["label"])

Targets for the planning board:
Jupiter
Moon
Saturn
Omitted levels

The display data no longer includes counts or shares, and its scope label no longer includes quantities. Named levels are ordered by value rather than by frequency. The omission marker survives so the planning board does not suggest that its list is exhaustive.

Topology is not anonymization. It still reveals the feature name, target labels, and the existence of omitted categories. Its retained categories also reflect the earlier frequency-based cap. Review whether those disclosures suit the audience; removing explicit quantities does not make a sensitive label safe.

Serialize the presentation and retain the evidence

from pathlib import Path

presentation_json = json.dumps(topology, indent=2, allow_nan=False)
Path("observing-plan.json").write_text(
    presentation_json, encoding="utf-8"
)
print(fw.render_plaintext(saved))

Fieldwork · levels
Levels (computed)
  target: 3/4 levels; 10/12 evaluated rows reported
    Moon: 5 rows
    Jupiter: 3 rows
    Saturn: 2 rows
    ... 1 level / 2 rows not reported

The header names the result kind. Pass the analytical result or saved analytical dictionary to native renderers; the presentation dictionary is for your own rendering or transport. Generating topology has left the saved count of five Moon entries inspectable.

Before planning the next session, investigate the two missing-target entries in the original log. This projection cannot recover their identities or tell whether the omissions were deliberate. If every target category must be named, rerun fw.levels with max_levels=None and project that new result: changing presentation detail cannot restore analytical records omitted earlier.

Continue exploring

fw.render_svg, fw.render_html, fw.render_plaintext. See results and configuration for serialization and result-method contracts.