From Protocol to an Analysis Table
A GLMM analysis table should be designed from the study protocol, not assembled by collecting every available column and deciding later what might be useful. The protocol states who or what is observed, when measurements are taken, what the outcome represents, and how participants or units are grouped. Those details determine what each row means and which columns the model needs.
The goal here is a clear specification: a data dictionary describing the variables and an analysis table with a defined record grain. This does not fit the model or decide every modeling choice. It makes those choices auditable by ensuring that the planned outcome, predictors, and grouping structure can be represented by the data.
For a GLMM, each analysis record must provide the outcome information and the predictor and grouping information needed for that record. A grouping variable identifies the cluster membership relevant to the planned model; it is not automatically a substantive predictor. A participant ID may be needed to connect repeated records or audit the data, but an ID is not ordinarily a meaningful explanatory measurement.
Specify the Table Before Building It
Start by translating the protocol into a short analysis specification. State the scientific question, outcome, intended observational unit, relevant grouping levels, and candidate predictors. Then decide what one row represents. The row definition must be specific enough that two analysts would make the same decision about whether a particular measurement belongs in one row or another.
For example, “one record per participant” is not sufficient if the protocol measures the outcome at several visits. The specification needs to say whether the table represents one participant-level summary or separate participant-visit records. Those alternatives encode different information and do not generally answer the same analysis question.
A convenient abstract representation is to let \(r\) index rows, \(y_r\) denote the outcome for row \(r\), \(x_{r1},\ldots,x_{rp}\) denote its predictors, and \(g(r)\) denote its cluster label. This notation is only a planning aid: the dictionary must say what each of these quantities means in the study and how its value is obtained.
Specify the population, outcome, and comparison or association of interest. This prevents unrelated protocol fields from being treated as necessary model variables.
Name the entity or measurement occasion represented by one record, and state which protocol measurements contribute to that record.
Identify the outcome, substantive predictors, grouping variables, identifiers, and any variables used only for data checks or derivations.
Record sources, units, allowed values, derivation rules, and consistency checks before creating the final table.
The roles can overlap in a useful way. A baseline measurement may be a predictor and also be used to verify eligibility. A clinic code can be a grouping variable in one analysis and merely an identifier in another. The role is determined by the stated analysis, not by the column name or the fact that the variable appears in the protocol.
Worked Examples: Making the Specification Concrete
Worked Example: A Cluster-Randomized School Study
Hypothetical protocol. Eight schools are assigned to one of two programs. Investigators enroll five students per school, measure each student's end-of-term assessment score, and record baseline score and age. The planned analysis compares assessment scores by program while accounting for clustering by school.
Record grain. The outcome is measured on each student, so the table is specified as one record per enrolled student. With eight schools and five students in each, the planned number of records is \(8 \times 5 = 40\) student records. The school label repeats across students because school is the cluster; it must not be replaced by a different label for each row.
Column plan. The outcome is end-of-term assessment score, in score points. Program is a categorical predictor assigned at school level. Baseline score, in score points, and age, in years, are candidate student-level predictors if included in the planned analysis. School ID is the grouping variable. Student ID identifies records and supports checks for duplicate students.
A compact dictionary entry for the outcome might read: name: end_score; meaning: end-of-term assessment score per enrolled student; type/unit: numeric, score points; source: assessment record; allowed range: 0–100 according to the assessment scale. The program entry should state the two permitted program labels and that its value is constant within each school.
Checks. There should be 40 distinct student IDs if all planned students are present; each student should have exactly one end score; and each school should have five records. Program assignment must not vary among records from the same school. A mismatch indicates either a data problem or that the written protocol and table do not describe the same design.
Worked Example: Clinic-Month Count Records
Hypothetical protocol. Four clinics report the number of new referrals during each of three consecutive months. The analysis concerns monthly referral counts, with clinic as a grouping variable and month and staffing level as predictors. Each clinic-month has one count and a recorded staff-hours total.
Record grain and count. One row represents one clinic in one month. If all four clinics report all three months, the expected table size is \(4 \times 3 = 12\) rows. This calculation is not an observed result; it is a completeness target derived from the protocol.
Example rows. Suppose Clinic A reports 12 referrals and 160 staff-hours in January, then 15 referrals and 168 staff-hours in February. These are two rows, both with clinic ID A, with month values January and February, respectively. The count remains attached to its own clinic-month record; summing the two counts into one clinic total would remove the monthly outcome information specified by the question.
The dictionary should define referrals as a nonnegative count of new referrals recorded during the stated calendar month, month as a time label with an unambiguous year, staff-hours as hours worked during that same month, and clinic ID as the grouping label. The protocol must clarify how partial months or reporting corrections are handled; otherwise two people could produce different counts from the same source records.
Checks. The pair (clinic ID, month) should uniquely identify rows, and there should be 12 such pairs if reporting is complete. For each row, the referrals and staff-hours must refer to the same clinic and month. A zero referral count is a possible count; a blank value is not automatically equivalent to zero.
Worked Example: Repeated Measurements Within Participants
Hypothetical protocol. A study follows six participants, each measured at baseline and at weeks 4 and 8. The measured outcome is a symptom score, and participants attend one of three centers. The planned table has one record per participant at each scheduled measurement occasion.
Expected number of records. With six participants and three scheduled occasions, complete follow-up gives \(6 \times 3 = 18\) records. For example, participant P03 has three rows: P03 at baseline, P03 at week 4, and P03 at week 8. Each row has that occasion's symptom score, the participant's center, and the time label.
The dictionary should identify the score scale and its valid limits, define the time labels and their scheduled weeks, and state whether center means the center at enrollment or the center of the visit. That distinction matters if a participant can change centers. Participant ID links the rows from the same participant; center is a grouping label only if the analysis plan uses it as such.
Checks. There should be at most 18 participant-occasion combinations and no duplicate combination. A missing week-8 score is not a new participant and must not be represented by copying the week-4 score into a second row. The table should preserve the fact that the scheduled measurement is unavailable, using the project's documented missing-data representation.
Why the Record Grain Matters
The row definition determines what information is available to the model and what repeated or clustered structure can be represented. If one row represents a student but the school ID is omitted, the table no longer carries the school grouping needed for a school-level random effect. If several student records are accidentally copied, the outcome distribution and apparent amount of information change. If repeated measurements are collapsed to a summary without protocol justification, time-specific information is lost.
A useful internal check is to derive the expected row count from the design. If \(J\) clusters are expected and cluster \(j\) contributes \(n_j\) records, the planned total is \(N = \sum_{j=1}^{J} n_j\). When every cluster has the same planned number \(m\), this simplifies to \(N=Jm\). This is a design-based check, not a requirement that the final table contain no missing records: withdrawal, nonresponse, and other documented events can make the observed count smaller. The point is to make the discrepancy visible and explainable.
Diagnostics, Alternatives, and Limitations
Before fitting a model, inspect the table using checks that follow directly from the protocol and dictionary:
- Uniqueness: verify that the columns identifying a record do not occur more than once.
- Completeness: compare observed records and cluster sizes with the planned schedule or enrollment targets, and account for discrepancies.
- Consistency: check that cluster-level assignments do not change within a cluster unless the protocol permits changes.
- Validity: verify units, allowable categories, plausible numeric ranges, and that dates fall within the study period.
- Alignment: confirm that outcome, predictor, and exposure measurements refer to the same record and time window.
These checks can reveal problems, but they do not prove that the data are correct. A unique key can still identify a row with the wrong participant; plausible values can still be measured in the wrong units. Compare records with their source and retain a documented trail for derived columns.
There are alternatives to a row-level analysis table, but they answer different questions. An event-level file can preserve multiple events within a person or interval; it may need a documented aggregation rule before it matches a planned outcome record. A cluster-level summary can answer a question about cluster summaries, but discards within-cluster variation and generally cannot substitute for individual records in an individual-level GLMM. A wide table with separate columns for each occasion may be convenient for storage or review, yet it does not directly express one record per participant-occasion. Choose the representation that matches the analysis question and keep the transformation rules explicit.
A carefully specified table cannot repair a weak design, an ambiguous measurement definition, or biased missingness. Nor does assigning a variable a role in the dictionary establish that it belongs in a final model. Those decisions require substantive reasoning and the model's assumptions. The dictionary makes them transparent; it does not certify them.
Common Pitfalls
- Using every protocol column as a predictor. The wrong reasoning is that any recorded variable must improve the model. Instead, distinguish predictors from identifiers, operational fields, and variables retained for audit or description.
- Treating a blank as a zero. A count of zero means none were observed; a blank means no recorded value unless the protocol explicitly defines otherwise.
- Dropping a grouping label because it repeats. Repetition is expected when multiple records belong to the same cluster. Check that the label is consistent and correctly assigned rather than forcing it to be unique.
- Aggregating to simplify the table. Combining observations changes the record grain and can discard information. Aggregate only when the analysis question and a stated derivation rule support it.
- Leaving units or timing implicit. A value such as “12” is not interpretable without knowing whether it means referrals per month, score points, or something else, and which period it covers.
Check Your Understanding
Answer each question, then compare with the brief solutions.
- A protocol measures 9 clinics monthly for 4 months. If every clinic reports each month, how many clinic-month rows are planned, and what pair of columns should uniquely identify them?
- In a student-level study, why is a school ID not interchangeable with a student ID?
- A repeated-measures table has one row per participant and separate columns for three scheduled outcome occasions. What information does this representation fail to express directly as one record per occasion?
- A count field is blank for one clinic-month, while another clinic-month has a recorded count of zero. Why should these values not automatically be treated alike?
Solutions. (1) \(9 \times 4 = 36\) rows; clinic ID together with month should identify each clinic-month record. (2) Each student has a student ID, while several students can share a school ID; the latter identifies cluster membership, not an individual record. (3) It does not make each participant-occasion a separate row, so occasion-specific outcomes and their record-level alignment are not directly represented in the planned long-form grain. (4) Zero records a measured count of none; blank indicates no recorded value unless a protocol rule defines it otherwise.