Creating a Traceable NLME Analysis Dataset

From Source Records to Analysis Records

An NLME analysis dataset is not merely a table of concentrations. It is a documented transformation of source records into records whose subjects, occasions, event types, times, values, and units can be interpreted consistently. If a fitted value looks unexpected, an analyst should be able to trace the relevant analysis record back to what was recorded and identify the rules that changed it.

The decision question and analysis population determine which people and records are relevant. Dataset construction then makes those decisions operational: it identifies the records, applies documented transformations, and records disposition. A clean-looking table is not sufficient if it silently changes a dose time, drops an observation, or converts an unobserved value into a numeric one.

The dataset may be stored in long or wide form, and conventions differ across software and organizations. A common event-oriented structure uses one row per dose event or observation event. It should, at minimum, distinguish the subject, the occasion when relevant, the event type, time, and the event-specific information such as dose amount or observed value. A row identifier or source-record identifier is also needed when otherwise identical records may occur.

Identifiers and Event Meaning

A subject identifier should consistently refer to one person or experimental unit and should not be reused for another. An occasion identifier distinguishes analysis periods within a subject when the design or analysis defines such periods. An occasion is not automatically a calendar day, visit, or dosing interval: its meaning must follow the study records and the analysis definition. If occasions are not meaningful for a particular dataset, do not create them merely to fill a field.

A subject-occasion pair identifies a group of records, not necessarily a unique row. A subject can have multiple events at the same time, such as a dose and a sample, and replicate measurements may also share a time. Therefore, use a stable event or source-record key when one is available, and define the uniqueness checks for the actual dataset rather than assuming that subject, occasion, and time always identify a single record.

Event type is essential because a dose and a measured concentration are not interchangeable. In a typical event-oriented table, a dose record has a dose amount and dose-specific fields, whereas an observation record has an observed value and an observation-specific status. The exact coding depends on the data system. Whatever coding is used, document it and ensure that downstream software interprets it as intended. Do not give a dose record a concentration value simply to make every column nonmissing.

Time, Units, and Derived Variables

A derived variable is a value calculated from source fields according to an explicit rule. Common examples include elapsed time from a reference event, converted measurement units, and a dose interval. Record the inputs, the rule, the output unit, and any assumptions needed to apply it. Preserve the source value when a transformation replaces or supplements it; retaining both is often the simplest way to expose conversion mistakes.

Time derivation requires a defensible reference event and a consistent time basis. A timestamp difference is not meaningful if one timestamp is local time and another is in a different time zone, or if date rollover is handled incorrectly. Record which dose or other event defines time zero, whether scheduled or actual times are used, and how date, time zone, and daylight-saving changes are treated when relevant. Do not infer an actual administration time from a planned schedule without labeling that substitution.

The formula is valid only if the timestamps are comparable and the intended reference event is correctly identified. A negative result may be valid for a predose sample under a chosen reference convention, but it may instead signal a wrong date, wrong occasion, or incorrect time zero. The value should be checked against the event context rather than automatically changed to zero.

Unit conversions should be explicit and dimensionally consistent. For example, if a hypothetical source concentration is 2.4 micrograms/L and the analysis unit is mg/L, then \(2.4\ \text{micrograms/L}\times(1\ \text{mg}/1000\ \text{micrograms})=0.0024\ \text{mg/L}\). The conversion factor and both units should be recorded. A unit label without a conversion rule is not enough to establish that values are comparable.

Missing, Invalid, and Excluded Records

A record that is absent, a record with a missing value, a below-quantification result, and a record excluded by a quality rule are different situations. They should not be collapsed into a single numeric placeholder. For example, a missed scheduled sample is not an observed concentration of zero. A laboratory result reported as below a quantification limit is not the same as a failed assay, and it should retain its reported status and relevant limit information rather than being silently converted to zero.

Keep a disposition for records that do not enter the analysis dataset. This may be an exclusion flag plus a reason, or a separate disposition table linked to the source record. A reason should be specific enough to understand the decision, such as “specimen rejected under the documented laboratory validity rule,” rather than simply “bad data.” Distinguish exclusion of one event from exclusion of an entire subject; they have different consequences for the analysis population.

Traceability Checks and a Short Justification

A useful way to reason about traceability is to view dataset construction as a mapping from source records to analysis records. Let \(R\) denote the identified source records and let \(T\) denote the documented transformation and disposition rules. Then the analysis records are produced by applying those rules to the sources. Some source records can produce a derived analysis record; some may be combined under an explicitly stated rule; and some may be excluded with a recorded reason.

This is a practical traceability criterion, not a claim that every source row must map one-to-one to an analysis row. It justifies retaining source identifiers and transformation rules: without them, a derived value cannot reliably be reproduced, and a missing analysis row cannot be distinguished from an accidental loss. Conversely, a complete mapping does not prove that the source measurement is scientifically valid; source quality still requires appropriate checks.

Practical checks include verifying that subject identifiers map consistently, event keys are unique under the chosen key definition, and occasion assignments are plausible. Check that dose amounts and observation values have the expected units, derived times agree with source timestamps, and records are ordered coherently within subject and occasion. Review unexpected negative times, duplicate samples, impossible dates, unexplained missing values, and records with contradictory event fields. Reconcile counts by subject and event type to source summaries, and investigate differences rather than forcing counts to match by deleting records.

Format Choices, Pitfalls, and Limitations

Long event-oriented data make it straightforward to keep doses and observations as separate rows and to accommodate different numbers of records per subject. Wide data can be convenient for certain review tasks, but separate columns for many scheduled times can make irregular samples, repeated occasions, or event-specific fields cumbersome. Neither format is inherently traceable: identifiers, units, source links, transformation rules, and dispositions are needed in either case.

Another approach is to pass minimally transformed source records directly to analysis software and perform transformations inside the modeling code. This can avoid duplicated datasets, but it makes the data-generation logic harder to inspect unless the code and its inputs are clearly linked and the derived records can be checked. A separate analysis dataset can be easier to review, but creates a risk that the data and transformations drift apart. The appropriate choice depends on the workflow; the essential requirement is that the values used can be reproduced and explained.

• Wrong reasoning: “A blank concentration is inconvenient, so I will set it to zero.” Correction: A blank value does not establish a measured zero. Preserve the missingness or reported status and its reason.
• Wrong reasoning: “Subject, occasion, and time uniquely identify every row.” Correction: Replicates or simultaneous dose and observation events may share those fields. Define and test a key that accommodates the actual records.
• Wrong reasoning: “The scheduled dose time is close enough to the actual time.” Correction: Use the source time selected by the stated rule, and label any substitution. Scheduled and actual administration times represent different information.
• Wrong reasoning: “Removing rejected records makes the final table cleaner.” Correction: Exclusion may be appropriate, but preserve the source record or its identifier and document the reason so the disposition can be reviewed.

Traceability has limits. It cannot correct inaccurate source records, resolve an ambiguous study definition by itself, or establish that a transformation is scientifically appropriate. If subject identity, time basis, event meaning, or units cannot be resolved from available records, flag the ambiguity and obtain a documented decision before treating the resulting values as definitive.