Building HTML Diagnostic Reports

From Diagnostic Outputs to a Usable HTML Report

Diagnostic figures and tables are useful only if a reviewer can find them, understand what they show, and open the associated artifacts. An HTML report brings those pieces together in a document that can be opened in a browser and distributed with its supporting files. In a pharmacometric workflow, the report should preserve context such as the diagnostic quantity, units, transformation, and analysis identifier—not just display an image.

The earlier material on diagnostic captions, data-linked narrative summaries, and reusable report sections supplies useful content for this task. Here the focus is on rendering that content as a coherent HTML document, with readable layout and links that resolve in the delivered package. A report package is “self-contained” in the practical sense that its HTML and required assets travel together and do not depend on a live analysis session or a particular working directory. It need not mean that every image is encoded inside one HTML file.

A useful starting structure is deliberately simple:

diagnostic-report/
  index.html
  figures/
    observed-predicted.png
    cwres-time.png
  tables/
    subgroup-summary.csv

The HTML document provides the reading order and context. The figures and table export remain separate files, linked from the document. This structure is easier to inspect and transfer than HTML that points to files in a user-specific temporary folder. It also makes clear which files belong to the report.

Structure the Document Around the Review Task

A report should have a predictable sequence: a concise report heading, a brief description of the analysis represented, then diagnostic sections with figures or tables and their explanations. Use headings to create meaningful sections, and use descriptive link text rather than vague labels such as “click here.” A small set of in-page links can let a reader move directly to important sections. These are ordinary links to named section anchors; they do not replace a carefully ordered report.

Use semantic HTML elements for their intended purposes. A heading identifies a section; a paragraph gives narrative context; a table represents values in rows and columns; and a link points to a destination. For a figure, place the image, a descriptive alternative text, and its caption together. The caption should identify the diagnostic and clarify any needed units or scale, while the surrounding text can explain the review-relevant pattern. Do not make the caption carry conclusions that the plotted data do not support.

Readable layout is not decoration added after the analysis. It affects whether readers can compare panels, find table headers, and distinguish context from interpretation. A modest embedded stylesheet can set a readable maximum text width, consistent spacing, responsive images, and table borders. Avoid relying on color alone to communicate a distinction, and check that text remains legible when the browser window is narrow.

<section id="observed-predicted">
  <h2>Observed versus population-predicted concentration</h2>
  <p>Concentrations are shown in mg/L. Points are observations
  from the hypothetical diagnostic data set.</p>
  <figure>
    <img src="figures/observed-predicted.png"
         alt="Observed concentration plotted against
              population-predicted concentration">
    <figcaption>Figure 1. Observed versus population-predicted
    concentration (mg/L); the diagonal is the line of identity.</figcaption>
  </figure>
  <p><a href="figures/observed-predicted.png">
    Open the observed-versus-predicted image artifact
  </a></p>
</section>

Relative Paths and Artifact Links

A browser resolves a relative URL from the directory containing the HTML document. Thus, if index.html is in diagnostic-report/, the link figures/observed-predicted.png points to a file inside diagnostic-report/figures/. This remains valid if the entire report directory is moved, because the relationship between the document and the image has not changed. In contrast, a link such as /home/analyst/run42/observed-predicted.png is tied to a particular machine and directory layout.

This rule gives a simple justification for a pre-delivery link check: resolve each local link from the report directory, then verify that the resulting file exists. Checking only that a link string is nonempty is insufficient; a plausible-looking path can still point to the wrong directory or to a missing file. Use consistent, descriptive filenames without unnecessary spaces or ambiguous versions. If names contain spaces or non-ASCII characters, ensure that URLs are encoded correctly; avoiding such names in generated artifacts is often simpler.

Render Tables and Generated Text Safely

A diagnostic table should remain understandable in HTML, not merely resemble a spreadsheet. Give it a clear caption, use header cells for column labels, and put units in the header or caption. For example, a column called “Median prediction error” is incomplete if the quantity’s scale or units are not otherwise stated. If the table is also offered as a downloadable CSV, link to it with a description that identifies the artifact.

Automated reports often insert values from data or metadata into HTML. Treat these values as text, not as trusted HTML. A subject label or analysis name could contain characters such as < or &, which have special meaning in markup. Escape text values before inserting them into HTML so they display as text rather than changing the document structure. Do not escape the surrounding HTML tags themselves. When constructing URLs, use URL-appropriate encoding for path components rather than assuming that HTML text escaping alone makes a URL valid.

Checks, Failure Modes, and Alternatives

A report is ready to review only after both its content and its delivery structure have been checked. A practical validation pass should include the following:

• Open the entry-point HTML file in a browser and inspect the report at a normal and narrow window width.
• Check that each figure is visible, its alternative text is present, and its caption identifies the quantity and relevant units or scale.
• Check that tables have clear headers and that values, missing-value labels, and units are rendered as intended.
• Resolve each local artifact link from the HTML file’s directory and confirm that the target exists.
• Follow in-page links to confirm that each reaches the intended section; check that section identifiers are unique.
• Move or copy the complete report package to a different directory and open it there. This tests whether it accidentally depends on the original working location.

Common failures are often small but consequential: a link points to an analysis scratch directory, a figure filename differs in capitalization from the filename on disk, an anchor does not match its target ID, or a generated label breaks markup because it was not escaped. A report can also be technically openable but hard to review if it omits units, uses unreadable text, or places interpretation in a figure without explaining the relevant context. When an asset is missing, do not silently leave a broken image; make the generation or validation process report the missing target so the issue can be corrected before delivery.

There are two broad delivery alternatives. A linked-asset package keeps images and downloadable files separate from the HTML, making individual artifacts straightforward to inspect and replace, but the directory structure must be preserved. A single HTML file can instead include assets inside the document, which reduces the number of files to distribute but can make the file larger and its contents less convenient to inspect. The choice depends on distribution needs; neither approach removes the need to test the rendered report. Avoid external resources that require network access when the report is expected to work offline.

These checks have limits. A file-existence check does not prove that an image is an appropriate diagnostic, that a table is numerically correct, or that a narrative interpretation is justified. Browser rendering can also differ across environments. HTML report validation complements—not replaces—review of the underlying diagnostic content and the generated artifacts.