Why Event-Type Coding Needs a Clear Contract
A longitudinal pharmacometric dataset can contain different kinds of records for the same subject: a measured concentration, an administered dose, or a record marking a model-state reset, for example. A field such as EVID identifies the broad event type represented by a record. If one part of a dataset uses a code to mean “observation” while another uses the same code to mean “other event,” software may process records incorrectly even when each row looks plausible by itself.
The practical goal is not merely to fill in a code column. It is to define one explicit mapping from codes to record meanings, apply that mapping consistently across the dataset, and check that the rest of each record is compatible with its assigned type. The codes below follow a common NONMEM-compatible convention. A project must verify that its software and data specification use the same meanings; a numeric code has no universal interpretation independent of its documented convention.
A Common EVID Dictionary
Under the convention used here, the core codes are as follows. These definitions describe broad record classes. They do not, by themselves, specify every field needed to represent a dose, how to encode a reset, or how to order records that share a time.
| EVID | Record class | Core meaning |
|---|---|---|
| 0 | Observation | A record representing an observation, such as a measured endpoint. |
| 1 | Dose event | A record representing a dose. |
| 2 | Other event | A record that is neither an observation nor a dose event, with its specific purpose documented separately. |
| 3 | Reset | A record that marks a reset event under the model and dataset specification. |
| 4 | Reset and dose | A record representing both a reset and a dose event under the chosen convention. |
A project may adopt a different software-specific convention, but it must document that choice and use it consistently. Do not assume that a code means the same thing merely because the column is named EVID. The dictionary should specify the allowed values, explain each value in operational terms, and state which fields are expected, allowed, or disallowed for each record class. It should also name the units and scope of the coding, such as the dataset version or analysis population to which the dictionary applies.
Event type is not a substitute for other variables. For instance, EVID distinguishes a record class; it does not identify the analyte, define the observation endpoint, or explain why a value is missing. Those meanings remain in their designated fields. Likewise, EVID=2 only says “other event” in this convention: the project must document what that other event represents rather than relying on the code to convey detail it does not contain.
Assigning and Validating Codes
Assign a code from the record’s documented role, not from a convenient pattern in another column. A record intended to represent a measured endpoint is an observation record; a record intended to represent a dose is a dose-event record. A record that has neither role must have a documented reason for its other, reset, or combined classification. If its role is unclear, resolve the specification before assigning a code.
Before validating records, state the assumptions that make the checks meaningful:
- One approved event-code dictionary applies to the records being checked.
- Each row represents the record grain specified for the dataset, rather than an accidental combination of distinct events.
- The record’s underlying purpose is known well enough to compare it with the assigned code.
- Observation and dose indicators, where present, have documented meanings and are not silently repurposed.
- Rules for any software-specific codes and exceptions are explicit rather than inferred from the data.
With those assumptions in place, validation has two complementary parts. First, check that every EVID value is allowed by the dictionary. Second, check whether the code agrees with the record’s other fields and documented role. For example, an observation-coded record should be consistent with the project’s observation indicator rules. A dose-coded record should be consistent with the project’s dose-record rules. The precise field-level constraints belong in the project specification; they should not be guessed from the code alone.
Record the allowed codes and meanings, including the software convention and any permitted extensions.
Use the documented role of each row to choose the code; do not infer the role from a missing or populated value alone.
Compare EVID with observation, dose, and other relevant fields using explicit rules from the data specification.
Investigate unknown codes, contradictions, and ambiguous records; document any approved exceptions and the dataset version.
Worked Examples
Worked Example: Assigning Codes From Record Purpose
Consider four hypothetical records from one subject. The project has adopted the dictionary above. Its specification states that measured concentration rows are observation records, administered-dose rows are dose events, and a documented model-state restart is a reset. Assign the broad event code to each record.
| Record | Documented purpose | Assigned EVID |
|---|---|---|
| A | Measured concentration | 0 |
| B | Administered dose | 1 |
| C | Documented reset, without a dose | 3 |
| D | Documented event that is neither observation nor dose nor reset | 2 |
The assignments follow from the row purposes: A is an observation, so EVID=0; B is a dose event, so EVID=1; C is a reset alone, so EVID=3; and D is an other event, so EVID=2. The description “other event” is not sufficient documentation for a final analysis dataset: the reason for D’s classification must also be stated in a project field or specification. This example does not determine the detailed encoding of the dose or reset.
Worked Example: Counting and Investigating Unknown Codes
A hypothetical validation run finds these EVID values in eight records: \(0, 0, 1, 1, 2, 3, 4, 7\). Under the dictionary above, count the records assigned each allowed code and identify the coding problem.
For the allowed codes, the counts are: EVID=0 appears \(2\) times; EVID=1 appears \(2\) times; and EVID=2, EVID=3, and EVID=4 each appear \(1\) time. The sum is
There are eight records, so one record remains outside those allowed-code counts. Its value is EVID=7. Since 7 is not in the approved dictionary, that record fails the allowed-value check. Do not silently recode it to 2 or another value: inspect its source and purpose, then correct the code under the documented rule or revise the dictionary through the project’s change process. The validation identifies a discrepancy; it does not establish what the record was intended to mean.
Worked Example: Finding a Contradiction Across Fields
In a hypothetical dataset, the specification says that an observation row has EVID=0 and an observation indicator OBS=1. A dose row has EVID=1 and OBS=0. A reset row has EVID=3 and OBS=0. Three records are presented below.
| Record | EVID | OBS | Validation result |
|---|---|---|---|
| A | 0 | 1 | Consistent with the specified observation rule |
| B | 1 | 0 | Consistent with the specified dose rule |
| C | 0 | 0 | Inconsistent with the specified observation rule |
Record C is coded as an observation but has OBS=0. Applying the stated rule, an observation requires OBS=1, so the check fails for C. The available information does not tell us whether EVID or OBS is wrong, or whether the project has an unrecorded exception. The correct action is to compare the record with its source and specification, resolve the inconsistency, and retain a traceable correction. Changing EVID automatically because OBS=0 would be unsafe: the indicator alone does not establish the record’s underlying purpose.
Why These Checks Work—and Where They Stop
The key justification is that validation tests a code against two independent pieces of information: the dictionary and the record’s documented role. The dictionary check establishes whether the value is a defined category. The compatibility check asks whether the assigned category agrees with the role and required field rules. Passing the first check is necessary but not sufficient: EVID=0 can be an allowed value and still be wrong for a dose record.
In logical form, let \(C\) mean that a code is allowed, and let \(K\) mean that the code is compatible with the record’s documented role and field rules. A record passes the event-type checks only when both conditions hold:
This follows directly from the purpose of the two checks. If \(C\) is false, the code has no defined interpretation under the approved dictionary. If \(K\) is false, the code’s defined interpretation conflicts with the record. Thus neither check alone is enough to support a valid classification.
These checks have limits. They cannot recover a record’s true purpose when source information is absent, and they cannot prove that the dictionary itself matches the software configuration. They also do not resolve the ordering of distinct events at the same time, determine whether a dose was fully or partly administered, or define the detailed handling of resets. Those require their own data definitions and checks. Event-type validation should flag uncertainty rather than conceal it by assigning a plausible-looking code.
Diagnostics, Pitfalls, and Alternatives
Useful diagnostics include a frequency table of EVID values, a list of values not in the dictionary, and cross-tabulations of EVID against observation and dose indicators. Review a sample of records from every code, not only those that fail: a systematic mapping error may affect every row while still using allowed values. Track the number of records checked, the number flagged by each rule, and the resolution of each exception. When the dataset is revised, rerun the checks and record the version.
A common mistake is to reason, “The observation value is missing, therefore this must be a dose or other event.” That does not follow. A missing observation value may have several meanings, and record role must be determined using the specification and source information. Conversely, a populated value does not by itself prove that the row has the correct event code. Check both the intended role and the defined compatibility rules.
A single shared code dictionary is usually the clearest approach for one analysis dataset. Separate dictionaries can be appropriate when software or source systems genuinely use different conventions, but they require an explicit, tested mapping into the analysis convention. A project-specific extension can also be appropriate if the software supports it and the code is documented. Reusing a standard code with a new meaning is not a safe shortcut: it makes records ambiguous and can change how downstream software processes them.
Check Your Understanding
Answer each question using the common dictionary and validation principles above.
- A record represents a measured endpoint and has EVID=0. Under a project rule that observations require OBS=1, what should be checked if OBS=0?
- A dataset contains EVID=6, but the approved dictionary permits only 0 through 4. What can be concluded, and what cannot be concluded from this discrepancy alone?
- Why is a missing observation value not enough evidence to assign EVID=1?
- Four records have codes \(0, 1, 1, 3\). How many records are assigned each code, and how many are assigned EVID=1 or EVID=3 combined?
- What two conditions must hold for a record to pass the event-type checks?
Solutions. (1) The record conflicts with the stated compatibility rule. Compare its intended role and source with the specification; do not automatically change either field without resolving the conflict. (2) EVID=6 is outside the approved dictionary, so the record fails the allowed-value check. The code alone does not reveal the intended event type. (3) Missingness does not establish record purpose; the record may have another explanation, so use documented role and source information. (4) EVID=0 occurs once, EVID=1 occurs twice, and EVID=3 occurs once. EVID=1 or EVID=3 combined occurs \(2+1=3\) times. (5) The code must be allowed by the dictionary, and it must be compatible with the record’s documented role and applicable field rules.