The schedule of activities in USDM
In a protocol the schedule of activities is one table. In USDM there is no table. It is assembled from five kinds of object that point at each other, and that indirection is the part of the standard people find hardest. This page shows it working.
Click any mark
This is the schedule of the example study, laid out from its USDM file. Select a mark to see why it is there, or a visit name to see how that visit is placed in time.
| Screening | Treatment | Follow-up | ||||
|---|---|---|---|---|---|---|
| Activity | ||||||
| Planned day | Day -14 | Day 1 | Day 15 | Day 43 | Day 85 | Day 99 |
| Window | -7..+7 days | – | -2..+2 days | -3..+3 days | -3..+3 days | -3..+3 days |
| Informed consent | ||||||
| Eligibility review | ||||||
| Demographics and medical history | ||||||
| Vital signs | ||||||
| 12-lead ECG | ||||||
| Safety laboratory tests | ||||||
| Randomization | ||||||
| Dispense study intervention | ||||||
| Study intervention accountability | ||||||
| Adverse event review | ||||||
| Concomitant medication review | ||||||
Why this mark is here
Vital signs at Week 2
- What. The scheduled instance
ScheduledActivityInstance_3listsActivity_4in itsactivityIds. That entry is the mark. - Where. Its
encounterIdpoints toEncounter_3, the visit shown as Week 2, in the Treatment epoch. - When.
Timing_3places it 14 days after Day 1, which works out to Day 15, with a window of -2..+2 days.
{
"id": "ScheduledActivityInstance_3",
"name": "WEEK_2_INSTANCE",
"label": "Week 2",
"epochId": "StudyEpoch_2",
"encounterId": "Encounter_3",
"activityIds": [
"Activity_4",
"Activity_10",
"Activity_11"
],
"defaultConditionId": "ScheduledActivityInstance_4",
"instanceType": "ScheduledActivityInstance"
}
Which object is which part of the table
| In the protocol table | In USDM | How |
|---|---|---|
| The table as a whole | ScheduleTimeline | One timeline per schedule. A study has one main timeline and can have more. |
| A column | ScheduledActivityInstance | One planned point on the timeline. It names the visit, the epoch and the activities. |
| A column heading | Encounter | The visit the instance points to with encounterId. |
| The band above the headings | StudyEpoch | The epoch the instance points to with epochId. |
| A row | Activity | Defined once on the study design and reused at every visit. |
| A mark in a cell | ScheduledActivityInstance | An entry in the instance's activityIds. There is no object for the mark itself. |
| The day and window rows | Timing | A duration between two instances, with a lower and upper window. |
Reading a timeline, step by step
To turn a USDM file back into the table a study team recognises, a program does this. It is what the grid above does.
- Find the timeline whose mainTimeline is true.
- Start at the instance named by its entryId.
- Follow defaultConditionId from instance to instance to get the visits in order, until one has a timelineExitId.
- For each instance, look up its encounter for the heading, its epoch for the band, and its activityIds for the marks.
- For each instance, find the timing whose relativeFromScheduledInstanceId is that instance.
- Find the timing whose type is Fixed Reference. Its instance is the anchor: Day 1.
- Work outward from the anchor, adding or subtracting each duration, to get a day for every visit.
Timing in detail
The anchor
Every schedule needs a fixed point. In USDM it is a Timing whose type is Fixed Reference, and both of its instance references name the same instance. In the example that is Day 1.
{
"id": "Timing_2",
"name": "DAY_1_TIMING",
"label": "Day 1",
"description": "Day 1 is the fixed reference point for the schedule.",
"type": { "code": "C201358", "decode": "Fixed Reference", … },
"value": "P1D",
"valueLabel": "Day 1",
"relativeToFrom": { "code": "C201355", "decode": "Start to Start", … },
"relativeFromScheduledInstanceId": "ScheduledActivityInstance_2",
"relativeToScheduledInstanceId": "ScheduledActivityInstance_2",
"instanceType": "Timing"
}
Before, after, and relative to what
Every other timing is a duration before or after another instance. Read it as a sentence: the relativeFrom instance is value before or after the relativeTo instance. Most visits in the example are measured from Day 1. The follow-up call is not:
{
"id": "Timing_6",
"name": "FOLLOW_UP_TIMING",
"label": "Day 99",
"description": "Follow-up is planned 14 days after the Week 12 visit.",
"type": { "code": "C201356", "decode": "After", … },
"value": "P14D",
"valueLabel": "14 days",
"relativeToFrom": { "code": "C201355", "decode": "Start to Start", … },
"relativeFromScheduledInstanceId": "ScheduledActivityInstance_6",
"relativeToScheduledInstanceId": "ScheduledActivityInstance_5",
"windowLower": "P3D",
"windowUpper": "P3D",
"windowLabel": "-3..+3 days",
"instanceType": "Timing"
}
It is 14 days after the Week 12 visit, which is how the protocol states it. The grid shows Day 99 because 84 days after Day 1 is Day 85, and 14 days after that is Day 99. The distinction matters in practice: the call follows the last dose, so if the Week 12 visit moves inside its window the call moves with it. A reader that assumes every timing is measured from Day 1 gets this wrong.
Windows
windowLower and windowUpper are durations either side of the planned time, and windowLabel is the same thing in words. A visit with no window has neither. Windows do not have to be symmetric: three days early and seven days late is P3D and P7D.
Durations are ISO 8601
P14D is 14 days, P2W is 2 weeks, PT30M is 30 minutes. Days, weeks and hours convert exactly. Months and years do not have a fixed length, so a timing written as P3M cannot be turned into a day number without a convention the file does not state.
Beyond the simple case
The example is a straight line of six visits. Real schedules are not, and the same classes stretch to cover them.
- Branches and cycles. A ScheduledDecisionInstance is a point where the path depends on a condition. Each of its condition assignments names a condition and the instance to go to. Pointing one back at an earlier instance makes a treatment cycle.
- Time points inside a visit. A pharmacokinetic profile is a second timeline with its own anchor, such as the dose, and instances at each sampling time. It is attached to an activity or to an instance on the main timeline with
timelineId. - Unscheduled and early termination visits. Each is its own timeline with its own entry condition, such as an adverse event, and not an extra column on the main one.
- Grouped activities. An activity can list children with
childIds, which is how a heading such as Safety assessments and the rows under it are represented. - Footnotes and conditions. The small print of a schedule, such as only for women of childbearing potential, is held as notes and as Condition objects that apply to an activity in the context of particular instances.
What the timeline does not say
A USDM timeline states what the protocol requires at each visit and when. It does not say what a coordinator needs in hand on the day: the worksheet for the visit in the site’s own template, the order to do things in, or how the visit is set up in the site’s systems. That work still has to be done from the schedule, at every site, for every study. USDM at the research site picks up from here.