Why Embedding Needs Its Own Checks
A report can be generated without errors and still be incomplete: its figures may be missing, its tables may not display, or an image may be stretched in one output format. These failures often arise not from the diagnostic itself, but from how the report refers to the generated artifact and how the receiving renderer interprets its size.
Reliable embedding therefore requires treating each figure or table as a report dependency. The report must point to the intended file from the location where it will be read, and its display dimensions must be specified or governed by a documented rule. Those references should be checked in the final output, not inferred from the fact that generation finished successfully.
Stable Paths and Resolution
A file path is interpreted relative to a base location. For a linked image in an HTML report, that base is ordinarily the directory containing the HTML document. It is not necessarily the project root, the script's working directory, or the folder from which a user launched a command. Confusing these locations is a common cause of links that work during generation but fail after delivery.
A robust project usually has a known root and a predictable output layout. For example, suppose the project root is analysis-project, the report is saved in analysis-project/reports/diagnostics.html, and the figure is saved in analysis-project/reports/figures/residuals.png. The report's relative reference is figures/residuals.png, because the link is resolved from the reports directory.
This relationship gives a simple justification for using report-relative paths. If the report and its figures folder are moved together while their internal layout is preserved, the same reference still resolves. A path such as /home/analyst/Desktop/analysis-project/reports/figures/residuals.png instead encodes a particular machine's directory structure. It can work locally yet be meaningless on a colleague's computer or in a review environment.
The path rule must match the delivery format. A self-contained report may store image data inside the document; a linked report must deliver its linked files in the expected relative layout. A report that references files outside the delivered folder is not self-contained, even if all links happen to work on the author’s machine.
Worked Example: Finding the Correct Relative Figure Path
A hypothetical report is saved at run-17/output/report.html. Its generated figure is saved at run-17/output/figures/individual-fit.png. Determine the reference from the report to the figure, then assess a proposed alternative.
The report is in the output directory, and the image is in that directory's figures subdirectory. The correct relative reference is therefore figures/individual-fit.png. Resolving it gives run-17/output followed by figures/individual-fit.png, which reaches the intended file.
The proposed reference run-17/output/figures/individual-fit.png is not equivalent: when resolved from the report directory, it would look under run-17/output/run-17/output/figures. The proposed absolute reference /tmp/run-17/output/figures/individual-fit.png may work in one temporary environment, but is not portable. The relative reference is stable if the report and figures directory are delivered together with the same layout.
Set Dimensions Deliberately
An image's intrinsic pixel dimensions describe its stored resolution; they do not, by themselves, guarantee a consistent displayed size. Different renderers, page widths, and default styles can scale the same image differently. Set the intended display width and height, or set a width together with a rule that preserves the image's aspect ratio. Do not specify incompatible dimensions that stretch the figure.
The aspect ratio is width divided by height. If a plot is 1200 pixels wide and 800 pixels high, its ratio is 1.5. Displaying it at 600 pixels wide while preserving that ratio gives a height of 600 / 1.5 = 400 pixels. This calculation provides a check on the dimensions rather than relying on visual guesswork.
Worked Example: Choosing Consistent Figure Dimensions
A hypothetical diagnostic plot is generated at 1600 by 1000 pixels. The report layout provides a maximum figure width of 800 pixels. Choose dimensions that fit the layout without distorting the plot.
The source aspect ratio is 1600 / 1000 = 1.6. At a display width of 800 pixels, the corresponding height is 800 / 1.6 = 500 pixels. A width of 800 and height of 500 preserves the source ratio and fits the stated maximum width.
Suppose instead that the report specifies 800 by 600 pixels. That display ratio is 800 / 600 = 1.333, not 1.6, so the plot would be distorted if both dimensions were forced. The correction is to use 800 by 500 pixels, or to constrain the width and allow the renderer to maintain the intrinsic ratio. If the figure must fit a fixed-height page region, reduce its width proportionally rather than squeezing one dimension.
For print-oriented output, dimensions may be expressed in physical units rather than pixels. Those units need to be chosen for the target page and remain explicit in the report's configuration. In either case, a single documented sizing rule is more reproducible than relying on renderer defaults. Explicit dimensions do not guarantee legibility: axis labels and table text still need inspection at the final displayed size.
Tables as Report Artifacts
A table may be included as structured content in the report or linked as a separate artifact, such as a generated file. Structured report content can adapt more readily to text selection and page layout, while a linked file can be useful when the table must also be delivered independently. The choice should be deliberate: the report must include the table in the form readers are expected to use, and any separate file must be included in the delivery package.
For a table rendered in the report, verify that its headers, rows, units, and missing-value notation survive rendering. For a linked table file, verify both that the reference resolves and that the file can be opened in the intended way. A path that points to a spreadsheet is not the same as an embedded, readable table: the reader may need compatible software, and the table may not appear inline.
Worked Example: Delivering a Diagnostic Count Table
A hypothetical report contains a table of record counts by subgroup. The author exports it to output/tables/counts.csv and saves the report as output/summary.html. The intended delivery is an HTML report in which readers can see the table immediately, plus a CSV file for reuse.
First, the table is included as structured content in the HTML report so that readers do not have to open another file to inspect the counts. Second, the CSV is delivered alongside the report, and any link to it uses the report-relative reference tables/counts.csv. This resolves from output to the intended CSV file.
Before delivery, compare the table in the report with the generated CSV: check the subgroup labels, the count in each row, the total, and any stated units or missing-value convention. If the row counts are 18 and 22, the displayed total should be 18 + 22 = 40 when those are the only two subgroups and each record belongs to exactly one. This arithmetic check can reveal an incomplete or stale table even when the link itself is valid.
Validation Before Delivery
Validation should test the artifact references and the rendered report. Checking only that a file exists does not establish that the report points to it; checking only the reference does not establish that the image is readable or the table is complete. A practical sequence is:
Check that every generated figure and separate table file exists in the delivery layout, with the expected name and extension.
For each linked artifact, combine its reference with the report's directory and confirm that the resulting location is the intended file.
Confirm that figure dimensions follow the declared sizing rule and that tables contain the expected headers, rows, and values.
Open the report from its delivery location and examine it at the intended screen or page size. Check for missing images, clipped content, unreadable labels, and unexpected page breaks.
These checks are meaningful under several conditions: the report's final location is known; its linked files are included in the delivery; relative references are interpreted from the report file; and the renderer used for inspection is representative of the intended output. If the report is later moved alone, or opened in a renderer with materially different layout rules, a previously successful check may no longer apply.
Failure Modes and Alternatives
| Approach or failure | What can go wrong | Practical response |
|---|---|---|
| Machine-specific absolute paths | References fail outside the author's directory structure. | Use paths relative to the delivered report layout when files are linked. |
| Implicit working-directory assumptions | Generation succeeds from one launch location but fails from another. | Set and use a documented project or output location; resolve report links from the report directory. |
| Renderer-default sizing | Figure size varies between output contexts. | Specify a consistent display dimension or sizing rule and inspect the rendered result. |
| Fixed width and height with different aspect ratios | Plots or labels appear stretched. | Preserve the intrinsic ratio or calculate the matching second dimension. |
| Linked table without an inline view | Readers may not see the table or may lack suitable software. | Include the table in the report when immediate inspection is required; deliver the separate file as an additional artifact. |
Embedding data directly can reduce broken-link risk because the report does not depend on a separate image file. However, it can increase report size and does not remove the need to check dimensions and rendering. Linking separate files keeps artifacts independently addressable and may simplify reuse, but requires packaging and path validation. Neither approach is universally better: choose according to the delivery requirement, and verify the resulting report.
A useful diagnostic is to copy the intended delivery folder to a different location and open the report there. If its linked figures or tables disappear, the package depended on an external path or on an unpreserved directory structure. This test does not guarantee identical rendering in every environment, but it exposes many accidental dependencies on the author’s workspace.
Common Mistakes
- Using a path that works only from the generation script. The report renderer resolves links from the report's location, not necessarily from the script's working directory. Verify the base location and the resolved file.
- Assuming file existence proves successful embedding. A figure may exist while the report points to the wrong directory or filename. Test the reference from the delivered report.
- Setting width and height independently. Dimensions with a different ratio stretch the image. Calculate the matching dimension or preserve the intrinsic ratio.
- Assuming an external table file is visible in the report. A downloadable CSV is useful, but it is not an inline table. Include both when readers need immediate viewing and a reusable file.
- Inspecting only the generation preview. The final report may be moved or rendered differently. Inspect it from the actual delivery layout at its intended size.
Check Your Understanding
Answer each question, then compare your reasoning with the solutions.
- A report is saved in deliver/report.html, and a figure is in deliver/images/fit.png. What relative reference should the report use?
- A figure has dimensions 1000 by 500 pixels. If its display width is 700 pixels and its aspect ratio is preserved, what is its display height?
- Why might an absolute path work during local report generation but fail after delivery?
- A table CSV is linked from a report, but readers must see the table immediately in the report. What additional embedding choice is needed?
- Name two checks that should be performed after moving a report and its artifact folder to a new location.
Solutions. 1. Use images/fit.png, because the reference is resolved from the deliver directory. 2. The source ratio is 1000 / 500 = 2, so the height is 700 / 2 = 350 pixels. 3. An absolute path encodes a particular machine's directory structure, which may not exist in the delivery environment. 4. Include the table as structured content in the report as well as providing the CSV link. 5. Confirm that the referenced files exist and that their paths resolve from the report's new location; then open the report and inspect the rendered figures and table for missing, clipped, or unreadable content.