Designing Technical Appendices for Model Review

Purpose and Scope of a Technical Appendix

A technical appendix is not a storage area for everything that did not fit in the main report. It is a structured set of supporting materials that lets a reviewer inspect how an analysis was specified and assess the evidence behind important claims. For a population pharmacokinetic analysis, this may include model code, diagnostic panels, estimation records, data definitions, and supplementary tables.

The main report should still communicate the model, its important results, and the interpretation needed to understand the conclusions. The appendix provides detail that would interrupt that account but is necessary for technical review. For example, the main report may show the principal goodness-of-fit figure and summarize the predictive check; the appendix can provide additional diagnostic panels and the relevant analysis settings. An appendix cannot compensate for a main report that omits a key result or does not explain what was concluded.

The organizing principle is traceable relevance: each item should answer a review question or substantiate a report statement. A parameter table supports a claim about estimated values; a diagnostic panel supports a claim about model fit; a data definition clarifies what was analyzed. This relationship can be expressed as a simple chain: a report claim identifies a conclusion, a supporting artifact shows the relevant evidence or specification, and a caption or note explains how the artifact should be read. If any link is missing, the reviewer must guess what the item is meant to establish.

Design the Appendix Around Review Tasks

Before assembling files, list the principal questions a reviewer is likely to ask: What model was evaluated? What data and definitions were used? Did estimation complete as reported? What evidence supports the evaluation claims? Where are results that are too detailed for the main report? Use these questions to set the appendix sections and their order.

A practical order moves from the analysis specification toward its supporting evidence:

1. Contents and orientation: a short index, document identifiers, and a concise explanation of the included materials.
2. Model specification: relevant model code or a controlled extract, with a clear indication of the analysis represented.
3. Estimation information: settings, completion status, and material warnings or limitations.
4. Data definitions: analysis variables, units, transformations, and any handling conventions needed to interpret the model inputs.
5. Supplementary evaluation: diagnostic panels and tables that support or qualify statements in the report.

This order is not mandatory. The key is to make sections predictable, label them consistently, and direct readers from report claims to relevant appendix items. Give each figure and table a unique number, informative title, and caption. Captions should identify the population or analysis set, variables and units where relevant, and any conventions needed to interpret the display. A title such as “Diagnostic plots” is less useful than “Observed versus individual predictions, analysis set A.”

Keep the presentation readable. Use legible fonts and axes, consistent units, and page breaks that do not split a figure from its caption. For a long appendix, include a contents list and stable section or item labels. Avoid relying on color alone to distinguish groups; use line types or symbols as well, especially when figures may be printed in grayscale. Materials should be accessible to the intended reviewers without exposing unnecessary confidential or identifiable information.

Model Code and Estimation Records

Model code can be important review material because it makes the implemented structure inspectable. Include the code that corresponds to the analysis under review, or a controlled excerpt if the full source is supplied through another defined, accessible channel. State what the code represents and identify its version or filename. Where an excerpt is used, say what has been omitted and why; do not leave the reviewer to infer whether the extract is complete. The appendix should clarify the model’s implementation without requiring a reviewer to search through unrelated project files.

A readable listing should preserve meaningful indentation and line breaks. If code is split across pages, retain line numbering or another stable locator so a reviewer can refer to a specific section. Define acronyms and local variable names that are not self-explanatory, either alongside the code or in the data definitions. Do not include secrets, access credentials, or unnecessary personal data in code or embedded files.

Estimation records should make the reported estimation outcome understandable. Depending on the software and analysis, useful information may include the software and version, estimation method, important settings, completion status, the objective-function value if reported, relevant warnings, and information needed to interpret convergence. Include material that helps explain the reported result rather than an indiscriminate software log. If an estimation record indicates a warning or a nonstandard termination, describe its relevance accurately; do not label a run successful solely because an output file was created.

Data Definitions, Diagnostic Panels, and Supplementary Tables

A reviewer needs enough information to understand how the analysis variables correspond to the reported model. A data-definition section can list variable names, meanings, units, coding, and transformations. Include definitions for dosing and observation records, time variables, covariates, and analysis indicators when they are needed to interpret the model. State the reference units for quantities such as dose, concentration, time, and body size. If a transformation changes interpretation—for example, a logarithm is applied to a variable—state the transformation and the variable to which it applies.

Document relevant data-handling conventions without reproducing an entire data-management history. For example, specify how a record is identified as a dose or observation, how analysis subsets are labelled, and how below-quantification observations are represented when that detail is required to understand the model inputs. These definitions should agree with the analysis and with the corresponding reporting in the main document. Any discrepancy in labels, units, or subset counts can make otherwise correct output difficult to review.

Diagnostic panels should add evidence rather than repeat the same view with cosmetic changes. Select panels that expose different aspects of model behavior and connect them to claims made in the report. Provide complete axes, units, symbols, and captions; state any grouping or stratification. If a panel is supplementary, say so, but do not use the word “supplementary” as a substitute for describing what it displays. Include plots that reveal a material concern as well as plots that support favorable conclusions.

Supplementary tables are most useful when they answer a specific question: they may provide detailed estimates, subgroup summaries, or additional results that are too extensive for the main report. Define all abbreviations and include units. Distinguish an unavailable value from a value that is zero, and explain omitted rows or columns if their absence could be misread. The table should remain interpretable when read on its own, while avoiding unnecessary duplication of the main results.

Completeness Checks, Alternatives, and Limitations

Before release, review the appendix as a reviewer would: navigate from a statement in the report to the supporting item, then check whether that item can be interpreted without undocumented assumptions. Verify that labels, units, analysis-set descriptions, run identifiers, and table or figure references agree across the report and appendix. Confirm that captions are attached to their items and that all abbreviations used in a figure or table are defined.

Common failure signals include missing code context, unexplained variables, estimation warnings absent from the summary, mismatched units, unreadable graphics, and supplementary output that contradicts a report claim without discussion. A long appendix is not necessarily a complete appendix. Conversely, a concise appendix can be adequate when its contents are well selected, clearly identified, and sufficient for the stated review purpose.

There are several reasonable delivery approaches. An embedded appendix keeps relevant materials together with the report and helps reviewers navigate them, but can make the report unwieldy. A separate supplement can be easier to manage for large figures or code, but needs stable labels and reliable access. A controlled electronic package may accommodate extensive material, but reviewers must be able to open it and understand how it relates to the report. In each case, the same principles apply: identify the materials, make them accessible, and explain their relevance. No format alone guarantees that a reviewer can verify a claim.

The appendix also has limits. Code and estimation records document what was supplied, but do not by themselves establish that the data are appropriate or that the model is clinically useful. Diagnostic panels offer evidence for evaluation, not a guarantee of performance in every population or setting. The appendix should support the argument in the report, not replace the interpretation of results or the discussion of limitations.