Why Package the Report?
A rendered diagnostic report is often shared separately from the project that produced it. If the report is delivered without its figures, tables, configuration, or clear references to the source outputs, a reader may see incomplete content or be unable to identify which outputs the report summarizes. Packaging makes the report and its supporting artifacts travel together, with enough descriptive information to distinguish them from other analyses.
A package is not automatically a full record of how an analysis was conducted. Its purpose here is narrower: to preserve a usable rendered report, include the files it needs to display, retain the relevant report configuration, and identify the source outputs represented in the package. A manifest can document those relationships. It does not, by itself, establish that the source outputs were correct or that the analysis can be rerun.
Define the Package Boundary
Before creating files, decide what the package must contain and what it will only reference. A practical package commonly includes the HTML or PDF report, the figures and tables needed by that report, the relevant report configuration, and a manifest. Some reports embed figures directly; others link to separate image files. In either case, the delivered package should preserve the report’s intended presentation when opened from its delivered location.
Source outputs need not all be copied into the package. A manifest can refer to them by stable output identifier and location, and can record useful identifying metadata such as file size or a cryptographic checksum. If source files are included, keep them in a clearly named directory and list them as package contents. If they are not included, make the reference explicit rather than presenting a local path as though it were part of the delivery.
The package boundary should also respect access and confidentiality requirements. For example, a report may be shareable while intermediate outputs contain sensitive records. In that case, document the source-output identifiers without copying restricted files or exposing personal information in paths or filenames. The reference should still be specific enough to distinguish the intended output from other outputs in the same project.
A Manifest That Makes the Contents Legible
A manifest is a compact inventory, often a CSV, JSON, or plain-text file. Choose a format that can be read without specialized software and that can represent paths and values unambiguously. At minimum, distinguish package files from source outputs and record enough information to identify each item. Useful fields include a relative path, file role, report or analysis identifier, source-output identifier, source location, size in bytes, and checksum when available.
Use relative paths for files within the package. A path such as figures/diagnostic-pk.png remains meaningful if the package directory is moved; an absolute path such as /home/analyst/project/figures/diagnostic-pk.png usually does not. For external sources, record a stable output identifier and a location meaningful to the intended recipient. Avoid relying on a temporary working directory or a user-specific drive letter.
A checksum can help distinguish two files with the same name. For example, a SHA-256 digest can be calculated from a file’s bytes and recorded in the manifest. A checksum is useful as a file identifier and for detecting an accidental change when the file is checked again. It does not tell the reader whether the file is scientifically valid, or whether the analysis that produced it was appropriate.
The configuration included in the package should be the configuration used to assemble that report, not merely a template that might be edited later. Give it a clear name and record its role in the manifest. It may include report options such as selected analyses, plot ordering, labels, and output format. Do not confuse this report configuration with a complete specification of the modeling workflow or the software environment.
Worked Example: Building a Single-Analysis Package
Suppose a hypothetical diagnostic report is rendered as HTML. It uses three PNG figures and two CSV diagnostic tables. The package also includes the report configuration and one manifest. The source outputs remain in a separate project location.
Inventory. The package contains one HTML file, three figures, two tables, one configuration file, and one manifest. The total is \(1 + 3 + 2 + 1 + 1 = 8\) files.
Organization. A simple directory layout could place the report at the package root, the images in figures/, the tables in tables/, and the configuration and manifest at the root. The HTML must refer to the figures and tables using paths that resolve from its location.
Source references. The manifest can record, for example, the source-output identifiers run042-figure-pk-001, run042-table-counts-001, and run042-table-coverage-001, along with their source locations and roles. Those identifiers make the represented outputs distinguishable even though the source files are not copied into the package.
Completeness check. Compare the manifest’s eight package-file entries with the files actually delivered. Then open the HTML from the package location and confirm that its three figures and two tables appear. A correct file count alone is insufficient: a missing figure replaced by an unrelated file would still leave the count at eight.
Completeness as a Dependency Check
A report depends on files that it uses to render its content. Let \(R\) be the rendered report, and let \(D(R)\) be the set of files that the report needs but does not embed. Let \(P\) be the set of files delivered in the package. A necessary condition for a self-contained package is that every required, non-embedded dependency is present at the path the report uses.
This condition follows directly from how linked assets are resolved: if a required file is absent from the delivered location, the report cannot retrieve it from that package. The condition does not establish that the report’s text is accurate or that each included file is the intended one. A useful check therefore combines inventory comparison with opening the rendered report and inspecting its linked content.
A manifest supports this check by giving each package file a recorded path and role. It can also record source-output references separately. Keeping these two categories distinct prevents a common ambiguity: an external source file may be listed to identify the report’s contents, but that does not mean the file has been delivered.
List the figures, tables, and other files referenced by the rendered report. Note which content is embedded and which is linked.
Copy required linked assets and the intended configuration into the agreed directory structure. Preserve filenames or update report links consistently.
Give package files relative paths and roles; give source outputs stable identifiers and clear locations or other identifying metadata.
Compare the manifest with the directory contents, open the report from that directory, and check that the expected figures and tables render.
Worked Example: Packaging Reports for Two Analyses
A hypothetical reporting job produces two HTML reports, one for analysis AN-17 and one for AN-18. Each report has three figures, two diagnostic tables, and its own configuration. The package has one root manifest.
File count. There are two HTML reports, six figures, four tables, two configurations, and one manifest: \(2 + 6 + 4 + 2 + 1 = 15\) files. The count is a useful reconciliation check, provided the inventory also identifies the role and path of each file.
Avoiding name collisions. If both analyses produce a file named diagnostic.png, putting both files in one directory risks overwriting one. Use analysis-specific paths, such as AN-17/figures/diagnostic.png and AN-18/figures/diagnostic.png, or names that explicitly include the analysis identifier. Each report should link to its own corresponding file.
Source references. The manifest should associate each report with its analysis identifier and the source-output identifiers it summarizes. For instance, entries for AN-17 should not accidentally point to the table outputs for AN-18. Keeping the reports and their source references grouped by analysis reduces this risk without claiming that the manifest independently validates either analysis.
Diagnostics and Common Failure Modes
Packaging errors often appear as broken links, missing files, or content that does not match the report’s labels. Check the package after it has been moved or extracted to a clean location, rather than relying only on a report that still opens from the creator’s working directory. A local browser cache or an absolute path to a project folder can hide a missing dependency.
For a package with one HTML report of 18,400 bytes, three PNG files of 245,000 bytes each, two CSV files of 4,800 bytes each, a configuration of 2,100 bytes, and a manifest of 6,500 bytes, the total uncompressed size is:
This total is a reconciliation aid, not proof of correctness. It assumes these are the complete set of package files and uses uncompressed file sizes; a ZIP archive can have a different size because of compression and archive metadata. Compare individual file sizes or checksums when you need to detect substitutions that a total-size check would miss.
Common problems include stale manifests that omit new figures, a configuration file that differs from the one actually used, filenames that are reused across analyses, and source references that point to temporary locations. A missing asset should be fixed or deliberately embedded; adding an entry to the manifest without delivering the file does not repair a broken report. Likewise, a checksum can help identify a source file, but it cannot replace a clear description of that file’s role.
Worked Example: Finding a Broken Reference After Moving a Package
A hypothetical package contains report.html and a figure at figures/obs-pred.png. The report instead refers to ../figures/obs-pred.png. The package is extracted into a new delivery folder, and the figure is not displayed.
Diagnose the mismatch. From the report’s location at the package root, the intended relative path is figures/obs-pred.png. The recorded path begins by moving up one directory, so it resolves outside the package. The package contains the figure, but the report’s dependency path does not point to it.
Correct the package. Update the report link to figures/obs-pred.png, or reorganize the files and update the manifest and report consistently. Then open the report from the extracted delivery folder and confirm that the image renders. This checks both the physical presence of the file and the relationship between the report and the file.
Choosing a Delivery Form and Understanding Its Limits
| Delivery form | Useful when | Main limitation |
|---|---|---|
| Directory of files | Recipients need to browse, inspect, or update individual artifacts under controlled procedures. | Files can be separated or altered unless the directory is transferred and managed as a unit. |
| ZIP archive | A fixed collection of report files should be transferred together. | Recipients must extract it, and the archive alone does not explain the meaning of every file. |
| Single PDF | A fixed-layout report is the main deliverable and its visual content is embedded. | Separate tables, configuration, and source-output references may not be included or easily inspected. |
| Links to a project folder | Recipients already have authorized access to a stable shared location. | Access, retention, or file changes can break the link or change what it refers to. |
A ZIP archive is often convenient for a fixed package, while a directory is easier to inspect. A PDF can preserve layout, but a PDF alone may not satisfy a need to include configuration or references. Choose a delivery form based on what the recipient must access, then include a manifest that explains the contents. No packaging choice proves that the model was correctly specified, that the source outputs are scientifically sound, or that the analysis can be reproduced from the package alone.
Check Your Understanding
Answer each question, then compare your reasoning with the solutions.
- A report links to four image files that are stored in a neighboring project folder, not in the delivered package. Is the package self-contained? What should be changed or documented?
- A manifest lists 12 package files, and the delivery folder contains 12 files. Does this establish that the package is correct? Give one additional check.
- Two analyses each produce a file named coverage.csv. State one packaging choice that prevents confusion.
- What can a checksum of a referenced source output help establish, and what does it not establish?
Solutions. 1. No. The report depends on files outside the package. Include the images and update the links, or embed them; if the images are intentionally external, clearly identify the external dependencies and do not describe the package as self-contained. 2. No. The count does not show that the right files are present or that report links work. Compare paths and roles in the manifest with the directory, then open the report from the delivered location and check its assets. 3. Put each file under an analysis-specific directory, such as AN-17/tables/coverage.csv and AN-18/tables/coverage.csv, and record those paths in the manifest. 4. A checksum can distinguish file contents and help detect a changed file when recalculated and compared. It does not establish that the output is valid, that the analysis was correct, or that the package permits a rerun.