Why Generate Diagnostic Captions from Metadata?
A diagnostic plot is easier to review when its caption states exactly what is displayed. A useful caption identifies the diagnostic quantity, any grouping, the scale, the number of plotted records, and filters that determine which records appear. If those details are typed separately for each figure, they can drift out of sync with the plotted data: a caption may say “linear scale” after a logarithmic transformation, or report the number of input rows rather than the number actually plotted.
Generating captions from plot metadata addresses this consistency problem. The goal is not to have software interpret a pattern or make a scientific claim. It is to assemble a concise, factual description from explicit properties of the plot and the data used to draw it. The result should be traceable to the same finalized data and plotting specification that produced the figure.
Caption Fields and Their Meaning
Each required field answers a different question. The diagnostic quantity names what is represented, such as a standardized residual or prediction error. It should be specific enough to distinguish quantities that may have similar-looking values. If the plotted quantity has units or a transformation, use terminology consistent with the axis labels and the plot specification.
The grouping states how plotted records are separated or encoded, for example by treatment group, study occasion, or none. It should not imply that every group is equally represented. If the plot has no grouping, say so when that information helps identify its structure. The scale describes the plotted axes or other relevant scale choices. Distinguish a logarithmic axis from a transformation applied to the data: they are not interchangeable descriptions. The caption should agree with the labeling and scale specification established for the plot.
The record count is the number of records represented in the plotted data after the plot’s filters and any required exclusions have been applied. It is not automatically the number of subjects, visits, or rows in an earlier source table. State the counting unit explicitly: “records” is appropriate when each plotted row contributes one plotted record. If one subject contributes several records, do not call the total a subject count.
Finally, filters describe restrictions that changed which records were eligible for display. A filter may select a study occasion, a population, or records with an available value for the plotted quantity. State applied filters in reader-understandable terms. Do not list conditions that were merely considered but not applied, and do not omit exclusions that materially define the displayed subset.
Constructing a Caption from a Plot Specification
A robust workflow separates metadata collection, validation, and sentence assembly. The metadata should be tied to the plot being generated, not maintained as an unrelated caption string. A minimal record might contain the quantity name, grouping variable and levels, axis scales, count unit, finalized plotted-record count, and a list of applied filters. It can also store the plotted-data identifier or version so a reviewer can trace which data the caption describes.
The count follows directly from the filtered plotting data. Suppose there are \(N_0\) candidate records and filters \(F_1,\ldots,F_k\) are applied in sequence. Let \(N_j\) be the number remaining after filter \(F_j\). Then the final record count is \(N_k\). If filters are applied to one shared record set, the order may not change the final intersection, but it can change the intermediate counts. For that reason, report the final count and describe the conditions actually applied, rather than implying that a sequence of intermediate counts is the final plotted total.
Here \(I(\cdot)\) equals 1 when the stated condition is true and 0 otherwise. This expression makes an important distinction: eligibility includes both explicit filters and requirements for a usable plotted value. If records with missing diagnostic values cannot be plotted, the count should reflect their exclusion, and the caption or accompanying filter description should make that exclusion clear when relevant.
A caption template can then assemble the fields in a stable order. For example: “Standardized residuals by study occasion on linear axes; 84 plotted records after restricting to occasion 2 and excluding records with unavailable residuals.” The exact wording can vary, but the field meanings should not. A template should avoid adding interpretations such as “good fit” or “systematic bias”; those are judgments, not metadata.
Name the diagnostic quantity, grouping, transformations, and axis scales using the finalized plotting specification.
Record each applied filter and any eligibility rule, including how unavailable plotted values are handled.
Compute the count from the data actually supplied to the plotting step and label its unit.
Check that metadata agrees with the data and plot settings, then insert the validated fields into the caption template.
Worked Examples
Worked Example: Filtering to One Study Occasion
A hypothetical diagnostic data set contains 120 candidate records. A plot displays standardized residuals by treatment group, but only for study occasion 2. Of the 120 records, 46 are from occasion 2. Three of those records have no available standardized residual and cannot be plotted. Determine the count and construct a caption.
Quantity and grouping. The diagnostic quantity is standardized residual, and the grouping is treatment group. The grouping describes how records are distinguished in the plot; it does not mean that the groups have equal counts.
Filters and count. The occasion restriction leaves 46 records. Excluding the 3 records without an available residual leaves \(46-3=43\) plotted records. Equivalently, the count is 43 records meeting both the occasion condition and the plotting eligibility condition. The count is not 46, because three eligible occasion-2 records lack the displayed quantity; it is not 120, because the plot is restricted to occasion 2.
Scale and caption. Suppose the horizontal and vertical axes use linear scales. A metadata-based caption is: “Standardized residuals by treatment group on linear axes; 43 plotted records for study occasion 2, excluding records with unavailable residuals.” This caption identifies the quantity, grouping, scale, final record count, and filters without making a claim about the residual pattern.
Worked Example: Distinguishing Records from Subjects
A hypothetical plot displays prediction errors against time after dose, with separate panels for two dose groups and a logarithmic horizontal axis. The source contains 30 subjects, each with up to four observations. After selecting the predose and postdose observations specified for the analysis, the plotting data contain 76 rows; 6 rows have unavailable prediction errors. Find the plotted-record count and write a precise caption.
Counting unit. Each row is one candidate observation record, while each subject may contribute multiple rows. Removing the six unavailable prediction errors gives \(76-6=70\) plotted records. The figure does not contain 70 subjects; it contains records from at most 30 subjects. Reporting “70 subjects” would misidentify the unit.
Grouping and scale. The grouping is dose group, shown by separate panels. The horizontal axis is logarithmic; the vertical axis scale should also be checked in the plot metadata before caption assembly. Suppose it is linear.
Caption. “Prediction errors versus time after dose, faceted by dose group; logarithmic time axis and linear prediction-error axis; 70 plotted observation records after selecting the specified predose and postdose observations and excluding records with unavailable prediction errors.” “Observation records” makes the count unit explicit. The caption does not equate records with subjects, and it states the transformation of the horizontal scale rather than loosely calling the data themselves logarithmic.
Worked Example: Detecting a Metadata–Data Mismatch
A hypothetical plot is intended to display prediction error by study occasion on linear axes. The metadata say that records were restricted to occasion 1 and that 52 records were plotted. A check of the finalized plotting data finds 48 rows, all from occasion 1, with no unavailable prediction-error values. What should the caption generator do?
Check the count. The plotted data contain 48 rows, so the count derived from the plotting data is \(N_{\text{plot}}=48\). The stated metadata count of 52 does not match. The generator must not silently use 52 simply because it is already present in a caption field.
Check the discrepancy. The four-record difference could reflect a stale count, a change in the plotting data, or another processing step. The information given does not establish which explanation is correct. The caption-generation process should flag the mismatch and require the metadata or data lineage to be reconciled before finalizing the caption.
Caption after reconciliation. If inspection confirms that the 48 rows are the intended plotted records and that no additional filter was applied, the caption can state: “Prediction errors by study occasion on linear axes; 48 plotted records restricted to occasion 1.” If the discrepancy cannot be resolved, omit neither the check nor the uncertainty by producing a seemingly precise but unsupported count; treat caption generation as failed for that figure until the source is corrected.
Validation, Diagnostics, and Failure Modes
Generated captions need checks because automation can reproduce incorrect metadata consistently. Useful validation compares the caption fields with both the plot specification and the data passed to the plotting function. At minimum, check that the plotted quantity exists, the declared grouping corresponds to the visual encoding, the scale description matches the axes, the record count equals the number of plotted records, and every listed filter was actually applied.
A practical implementation can reject incomplete or contradictory metadata rather than inventing a default. For example, if the axis scale is missing, it should not claim a linear scale by assumption. If the count is recorded as “subjects” but the plotted data are observation-level rows, the metadata should fail validation or require an explicitly computed unique-subject count. That unique-subject count is a different quantity from the record count and should not replace it without clear wording.
- Stale counts: a count was computed before filtering or missing-value exclusion. Recompute it from the finalized plotting data.
- Ambiguous scale wording: “log plot” does not identify whether the axis is logarithmic or the data were transformed. Name the axis or transformation precisely.
- Missing filter descriptions: a caption reports a subset count but not the restriction defining the subset. Include the applied condition in interpretable terms.
- Overstated grouping: a caption says “by treatment group” even though the plot does not encode treatment group. Derive grouping language from the visual specification.
- Unjustified interpretation: automatically generated text says a model fits well because of a plotted quantity. Keep captions descriptive; interpretation requires separate review.
Alternatives and Limitations
The main alternative is a manually written caption. Manual text can provide useful context and nuanced explanation, but repeated manual entry makes it easier for counts, filters, or scale descriptions to become inconsistent with figures. Metadata generation improves consistency for factual fields, especially across many related plots. It does not ensure that the underlying metadata are correct, that the plot is scientifically appropriate, or that the caption explains a surprising pattern.
A hybrid approach is often suitable: generate the factual core from validated metadata, then permit a reviewed explanatory sentence when needed. Keep that sentence separate from the machine-generated fields so a change in plot data cannot leave an outdated count embedded in free text. The automated portion should not infer causes, assess model adequacy, or describe visual trends unless a separate, validated procedure supports those statements.
Generated captions also depend on controlled terminology. If one plot uses “prediction error” and another uses a distinct metric, metadata labels must preserve that distinction. Likewise, a filter label such as “complete cases” is only clear if the relevant variables are named or defined. Reproducibility comes from a stable mapping between plot settings, plotted data, metadata, and caption—not from automation alone.
Common Mistake
A common mistake is to copy the number of rows in the source data into the caption and assume it is the plotted-record count. That reasoning fails whenever filtering, unavailable values, or other eligibility rules change which records reach the plotting step. For example, a source with 120 rows can yield only 43 plotted records after the occasion restriction and unavailable-value exclusion in the first example. The correction is to compute the count from the finalized plotting data and state the unit being counted. A second frequent error is to describe a logarithmic axis as though the diagnostic values themselves had been transformed; report the actual axis scale or data transformation.
Check Your Understanding
Answer each question, then compare your reasoning with the solutions below.
- A plot has 64 candidate rows. A filter retains 25 rows, of which 2 lack the diagnostic quantity. What record count belongs in the caption, and what should the filter description say?
- Each of 18 subjects contributes three plotted observations. Is the plotted-record count 18 or 54? What wording avoids confusing records with subjects?
- A plot has separate panels by occasion and a logarithmic horizontal axis. What should the caption say about grouping and scale?
- The caption metadata report 40 plotted records, but the finalized plotting data contain 38 rows. Should the generator silently select one count? Explain.
- Why should an automated caption avoid stating that a model fits well unless that claim is supported by a separate reviewed analysis?
Solutions. (1) The count is \(25-2=23\) plotted records. State that the plot is restricted to the specified filter condition and excludes records with unavailable diagnostic values. (2) The count is 54 observation records, not 18 subjects; wording such as “54 plotted observation records from 18 subjects” is precise if the subject count has also been verified. (3) State that the plot is grouped or faceted by occasion and that the horizontal axis is logarithmic; do not call the diagnostic values logarithmic unless they were transformed. (4) No. The mismatch should be flagged and reconciled; the caption should not be finalized until the correct count and data provenance are established. (5) A caption generator assembles descriptive metadata, which do not by themselves justify an evaluative interpretation. Fit assessment requires evidence and review beyond the fact that a plot was generated.