PF research library · 9 min read
ISAES scientific reports, exploration and presentation exports
r34 documentation · isaes-presentation.md · Formatted reading copy
On this page
The reporting renderer consumes retained analysis results. It does not call an AI provider, acquire hardware measurements, fit a model, recompute uncertainty, interpolate time frames or modify a scientific check. The common presentation document binds the report, figures and slide deck to the same findings and evidence.
Files and identities
| File | Contents |
|---|---|
report.json |
Final structured report, independent status dimensions, export availability and report hash |
presentation.json |
Versioned pf.isaes.presentation/1 document with exact finding copies, ordered explanations, qualifications, checks, citations, tables and provenance |
visualization_plan.json |
Versioned pf.isaes.visualization-plan/1 views with source/finding identity, retained data hash, units, coordinates, basis/frame, transforms, scales and selected frame |
report.html |
Self-contained report, bundled local Plotly when available, retained values, evidence navigation and exploration controls |
report.pdf |
ReportLab narrative and tables followed by Matplotlib vector scientific figure pages; the legacy Matplotlib text path remains available if ReportLab/pypdf cannot be imported |
report.pptx |
Editable narrative text and ordinary tables, exact PNG scientific figures, finding/source/check labels and complete figure/finding records in slide notes |
figures/figure-NNN.json |
Exact plotted specification, including all retained frames |
figures/figure-NNN.svg / .png |
Vector and raster scientific figures of the initial selected frame |
figures/figure-NNN.csv |
Numeric data for the initial selected slice where tabular conversion applies |
export_manifest.json |
File SHA256 values and byte counts, tied to the report and presentation identities |
report.zip |
Registered report, presentation, plan and figure artifacts plus their manifest |
The manifest intentionally excludes its own hash and the enclosing ZIP hash. report_sha256 hashes the canonical structured report without its hash field. Presentation and visualization hashes similarly exclude their own hash fields. The presentation document does not contain the final report hash, avoiding a circular identity dependency. Source and finding identities remain unchanged by rendering.
Exact numerical values remain in JSON and the numerical appendix. Axis ticks are display labels; they do not replace retained values. CSV exports escape text beginning with spreadsheet formula prefixes; JSON preserves the exact original labels. Scientific plots are embedded images in PPTX, not advertised as editable native chart objects.
Reading status and evidence
Report coverage and scientific validity are distinct. Review execution, delivery, coverage, numerical, statistical and literature status independently. A successfully delivered report can contain failed numerical checks or unresolved requirements. The same pass/fail checks, tolerances, assumptions, literature locations and warnings are carried into HTML, PDF and slides.
Open a finding's evidence record to see its source pointer, method, retained numerical values and any literature document hash/page. Supplementary retrieved literature remains marked as having unconfirmed applicability. Source origin is preserved; a simulated, measured, reconstructed or mitigated result is not relabeled by its plot.
Interactive exploration and retained exports
- Open the report's Explore control in the authenticated workbench, or open the downloaded
report.html. The offline file includes its plotting code and data and needs no server, account, AI provider or network connection. - Click an observation or use the keyboard Observation index → Inspect evidence controls. The panel displays exact selected values, source, finding, method and evidence identity. Inspect row on a table provides the same access.
- Explicit
link_groupand uniqueobservation_idsconnect plots and table rows. Frame views useframe_observation_ids, one identity per retained frame. Selecting a checkpoint in a series or table switches linked state frames; selecting a frame highlights the corresponding observation. Equal positions alone never establish alignment. Integer observation identities must fit the exact browser range (absolute value at most 2^53−1); larger identifiers must use strings. - Retained frame chooses an existing cycle/time/parameter checkpoint. No intermediate value is interpolated. Show selected observations applies a reversible display filter; Show all observations restores them. Table filters perform a literal text match, with 100 displayed rows per page. Counts expose the filtered and total row counts. These operations do not recalculate statistics.
- Zoom a two-dimensional view and save the exploration. In the workbench, saved views are stored through the authenticated retained-view API; the offline file downloads JSON. State includes exact plan identity, frames, selected IDs, visible IDs, axis ranges and table filters. Restore rejects foreign plans, unresolvable IDs, invalid frames/ranges, unknown fields and oversized filters.
- The workbench can request Export current view. The server verifies the original analysis checkpoint and plan before queuing a render-only child report. PDF, PPTX, SVG, PNG, CSV and HTML use the chosen retained slice and display settings. Exact figure JSON still includes the complete source and every retained frame; report findings, checks and original values are unchanged. The source report remains available.
Initial exports remain immutable when browser controls change. A selected-view export is a new, traceable presentation. Its provenance records the source plan and saved-state digest. Filtered table exports retain original full rows in structured JSON and declare their display filter. Plotly logarithmic ranges are retained as log10 display coordinates and mapped to the same static bounds.
At most six Plotly charts remain active in one browser document. Two initialize automatically; Activate interactive chart loads another and releases the least recently activated chart when the limit is reached. Static figures and exact values remain available. For ordered views above 5,000 observations, the browser draws the full unsimplified trajectory without individual SVG marker glyphs. All values and identities remain available through exact point/keyboard inspection. A separate overlay marks the first 128 selected observations; all selected identities stay in saved state and counts disclose larger selections. This bounds active browser rendering resources, without sampling, discarding data or generating values. All data must still fit the declared report and figure payload limits.
The embedded explorer runs in an opaque-origin sandbox with scripts and downloads permitted, without same-origin access. The trusted parent injects its exact origin, applies its existing CSP script nonce to trusted renderer scripts without relaxing the parent policy, and starts a pf.isaes.bridge/1 session with an unpredictable session identity, report identity and plan hash. The child checks message source and exact parent origin; the parent checks its exact iframe source, opaque origin, session/report identity and plan hash. Saved-state messages contain display state, never executable commands or arbitrary HTML. Standalone exports have no parent-origin declaration, so the bridge stays inactive. New reports advertise export_capabilities.embedded_exploration = "pf.isaes.bridge/1"; historical HTML without that capability keeps its offline download path and can be regenerated as a separate report to use embedded exploration.
Composition, audience and valid alternatives
The presentation options are versioned inside the report's retained requirements:
| Option | Supported values and behavior |
|---|---|
template |
technical, research-summary, presentation: reusable deterministic layouts |
audience |
technical, summary, presentation; research is a compatibility alias for technical |
detail |
full includes method metadata and exact values inline; concise keeps exact values in an appendix |
notation |
plain or scientific axis labels; exact JSON values are unchanged |
section_order |
Explicit retained finding IDs first; all remaining findings follow in their original order |
figure_choices |
Map of figure ID to an eligible alternative listed in the visualization plan |
figure_ids |
Figures selected for the main narrative; others remain in the supporting evidence appendix |
All layouts preserve failed/unresolved checks, warnings, uncertainty, assumptions, limitations, evidence references and exact findings. A deterministic attention section surfaces failed or unresolved checks and warning-bearing findings. Selecting concise detail never converts an exploratory finding to a validated claim. Slide presentation layout uses larger body text and fewer lines per slide. Tables and figure notes retain their evidence links.
Each visualization plan records an explainable selection rationale, its valid alternatives and constraints. A line can become a scatter plot without changing data. An independent scatter plot cannot become a connected trajectory. A declared ordered scatter plot can become a line if every retained frame satisfies the ordering constraints. An uncertainty band can become error bars only when retained bounds enclose their estimates. Alternatives are validated against every frame, scale and uncertainty field before rendering. No arbitrary chart choice is silently substituted. Unknown options or unsupported choices fail with an explanation.
Supported figure specifications
The common static catalog supports line, scatter, bar, heatmap, uncertainty band, error-bar, three-dimensional scatter, declared network and circuit diagrams. Local Plotly supplies interactive line/scatter/bar/heatmap/band/error-bar/3D views. Network, circuit and private Matplotlib extension figures retain static exports and their exact evidence records.
- Connected line/band/error-bar coordinates must be strictly increasing. Unordered observations should use scatter.
- Symmetric uncertainty uses retained nonnegative
y_error. Asymmetric uncertainty uses pairedy_error_lower/y_error_upper. Bars also accept retained enclosingy_lower/y_upperbounds; bands require lower and upper bounds. The renderer only converts geometric extents needed by the plotting API. - Frames are explicit retained objects, with
selected_frameas an integer index. Shared observation identities must remain stable across frames. Frames may override only retained data fields;label,value,sourceandoriginare permitted descriptive metadata. Identity, kind, scales, link groups, nested frames and arbitrary encoding overrides are rejected, including for private renderers. Static and interactive renderers use the same exported field allowlist and all-frame validation. Frame source/origin metadata cannot contradict the enclosing declared source/origin. - Heatmaps can carry explicit increasing
x/ycoordinates, axis labels and az_labelcolorbar. Static and interactive output preserve nonuniform coordinate geometry; CSV includes exact coordinates. Without coordinate arrays, declared matrix indices remain the axes. - Units, coordinate basis, frame, origin and transforms come from the upstream specification and scientific metadata. Missing metadata is exposed; a plot does not infer physical meaning.
- Linear and logarithmic axes are supported for applicable two-dimensional numeric views. Log views must have valid positive coordinates and intervals.
Malformed or unsupported figures produce an explicit render issue and incomplete delivery; valid findings remain inspectable. Invalid identity/evidence contracts fail closed. Missing required PPTX support fails with an actionable dependency error. Optional interactive availability is recorded separately; the retained static view remains readable.
Bounds and verification
A retained display specification is limited to 16 MiB, 256 frames and 262,144 numeric values per supported vector or matrix view. Heatmap axes are limited to 2,048 entries, networks to 1,024 nodes/8,192 edges, and circuit displays to 64 qubits/1,024 gates. These are presentation limits, not guarantees that an arbitrary workload at every limit is interactive. The analysis executor's resource limits also apply.
HTML stores each exact figure payload once and populates its readable JSON panel when opened. This avoids duplicating large matrices as both pretty-printed text and plotting data. No automatic downsampling is performed. Large arrays should be reduced through an explicit recorded upstream analysis or supplied as meaningful retained slices. Preview PNGs are omitted when needed to keep the structured report inside its result budget; full exported figures remain available.
Validation includes exact finding/check/citation parity across exported documents, artifact hashes, immutable values, malformed-view refusals, asymmetric interval geometry, provider-disabled generation, browser selection/frame/zoom/save/restore, and foreign-plan rejection. Browser validation checks that no external request is made, linked plots/tables/checkpoint frames stay aligned, filters survive saved-state restore, the active-chart bound holds, and bridge messages with incorrect plan/origin/session identities are rejected. Representative PDF and LibreOffice-rendered PPTX pages are inspected for clipping and overlap. This does not constitute a representative-researcher usability study or unrestricted large-data performance qualification.