fw.render_html

Use fw.render_html to give another reader a self-contained report with expandable evidence. Depending on the result kind, the report exposes findings, grain map/matrix controls, pair contexts, or a census tree.

The recipient can explore the saved report without the source dataframe or a Python kernel. The report does not run new analyses or fetch unsaved source rows.

Jump to the worked example or the argument reference.

Function reference

fw.render_html(
    result,
    *,
    section=None,
    detail='full',
    max_findings=100,
    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. Rendering 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; a profile defaults to grain.
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.
max_findings	nonnegative int; 100	Maximum items per list; default 100. Applies independently to findings, candidate summaries and completed dependency tests, including below-threshold tests. Zero omits these lists.
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 complete HTML document as a string, including its built-in styles and any controls for that result kind. Save with Path("report.html").write_text(html, encoding="utf-8") and open it in a browser. For a profile, select a computed section; the default section is grain. Every result kind has an HTML view; schema proposals render as role cards with their evidence.

Reports follow the viewer’s light or dark colour scheme and use only system fonts, so they open without a network. Figures and the grain matrix stay on white in both schemes, with the colours and shading ranges of SVG figures. Controls and focus rings are dark grey, so blue always means a result.

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.

Navigate findings and wide grain matrices

Each discovery list has its own search, visible-record count, and expand/collapse controls. Findings also have pattern and exception-row filters. Search covers only records included by max_findings. Clear filters to restore included records; render again with a larger limit to include omitted records. Evidence links open and focus their finding, even if a filter had hidden it.

The grain HTML matrix lists features as rows and candidate keys as columns. Sticky headings remain visible while the panel scrolls. Search for a feature or restrict the table to one candidate key, then select a cell and follow View selected evidence. Constant, varying, undefined, and untested remain distinct states; a * marks a different target population. Full names remain available in placement evidence when long labels are visually shortened in the matrix.

Foundation SVG views offer Actual size, Fit width, and fixed scales from 50% to 200%. The native matrix follows browser text scaling, so SVG-scale and map-only controls are disabled in that view. Narrow screens stack key/value evidence and keep wide figures and multi-column tables within local scrolling panels. Reset view restores foundation controls, matrix filters, and census branches.

Search/selection status is announced, focused controls have a visible outline, and map features support Enter/Space selection and Escape to clear. Native disclosures remain readable without JavaScript; enhanced controls require it.

Interpretation and boundaries

detail="topology" changes the exported presentation, not the underlying analytical result. Labels and structural information remain. For a full evidence archive, save result.to_dict() separately; HTML is a presentation artifact.

Invalid sections, detail or shading rules raise ValueError; uncomputed sections cannot be rendered. Controls differ by result kind: a report’s interactivity is navigation through saved evidence, not a dataframe editor.

Walkthrough: a seedling pickup report for the volunteer coordinator

A community garden has eight seedling order lines across four orders. Before pickup weekend, the coordinator needs to see which lines have a tray assignment and a pickup day. They can open an HTML file, but do not run Python.

Open the finished report or download the example.

Record the eight order lines

Each row requests one crop. A repeated tray label refers to the same physical tray; None means an assignment has not been recorded.

from pathlib import Path

import pandas as pd
import fieldwork as fw

orders = pd.DataFrame(
    [
        ("G01", "tomato", "T1", "Saturday"),
        ("G01", "basil", "T2", "Saturday"),
        ("G01", "lettuce", None, "Saturday"),
        ("G02", "tomato", "T1", None),
        ("G02", "basil", "T2", None),
        ("G03", "lettuce", "T3", "Sunday"),
        ("G03", "basil", "T2", "Sunday"),
        ("G04", "tomato", None, None),
    ],
    columns=["order", "crop", "tray", "pickup_day"],
)

Check the assignments

result = fw.explore(
    orders,
    features=["crop", "tray", "pickup_day"],
    table_id="seedling_orders",
)
availability = result.section("missingness").to_frame("availability")
print(
    availability[["feature", "populated", "denominator"]].to_string(
        index=False
    )
)

   feature  populated  denominator
      crop          8            8
      tray          6            8
pickup_day          5            8

The overview keeps each analysis as a section; result.section("missingness") returns the availability analysis as its own result. Six of eight order lines have trays and five have pickup days. These fractions count order lines: an order with three lines contributes three observations. They do not measure the fraction of distinct orders ready for pickup.

Save a report the coordinator can open

Choose the missingness section to focus on assignments:

html = fw.render_html(result, section="missingness", max_findings=20)
report_file = Path("render_html.html")
report_file.write_text(html, encoding="utf-8")

Open render_html.html in a browser. It starts with the population and search coverage. Expand Visual summary for the availability chart. Under Inspect findings, search for pickup_day and expand pickup_day: populated values to see measurements and saved/total source-position counts. The report works offline without a Python server.

This report contains six findings, all within the limit of 20. crop is filled in on every line, so it appears in the availability chart but has no finding of its own. It is a saved snapshot: after assigning the missing pickup days, rerun the analysis and save a new report.

Choose how much to show

To make a shorter report, lower the display limit:

short_html = fw.render_html(
    result, section="missingness", max_findings=2
)
Path("pickup-summary.html").write_text(short_html, encoding="utf-8")

This shows only the first two findings (tray and pickup-day availability) and two availability bars (crop and tray), followed by an omission notice. The pickup-day bar and the availability-pattern findings are hidden by the limit; nothing has become complete. The original result still holds all six findings.

For a discussion about structure alone, use topology detail:

topology_html = fw.render_html(
    result, section="missingness", detail="topology"
)
Path("pickup-structure.html").write_text(
    topology_html, encoding="utf-8"
)

This removes quantitative measurements and source-row positions from the presentation. Labels remain visible. Keep full detail for this coordinator: two missing tray assignments and three missing pickup days are useful quantities for planning the work.

Keep the analysis for later

The HTML is a report, not a complete analysis archive. Save the result dictionary separately if you will need to work with the evidence again:

import json

evidence_json = json.dumps(result.to_dict(), indent=2, allow_nan=False)
Path("pickup-evidence.json").write_text(evidence_json, encoding="utf-8")

See Save and compare for reloading a result. Both live result objects and saved result dictionaries can be passed to render_html.

Continue exploring

fw.render_svg, fw.visualization_data, fw.compare.