Draft SoA and Timepoints Design

[dih-cdisc]

Add of timepoints into the model

1. SoA timepoints This is an interesting one, big topic and might have an impact on existing model
2. Visit windows +/- days. Not the same as visit rules. Add in to the timepoints discussion as it is related

[dih-cdisc]

Initial outline of issue discussed at the SME Meeting 2022 10 19 SampleSoAs_Timepoints.docx

[dih-cdisc]

Comment from various sources:

• "minimal required time between two encounters / periods"
• "screening 28 days prior to enrollment, follow-up 26 - 30 days after last study treatment etc. Also refers to washout"

[dih-cdisc]

The features required are:

• Scheduled Study Visits
  • at a fixed time in the study schedule, can have a visit window (e.g. +/- 3 days)
• Scheduled Study Sub Visits
  • sub visits in a visit group, like: ‘6 Months Visit, Day 1’, ‘6 Months Visit, Day 2’, … )
• Cycled Study Visit
  • a visit re-occurring for at a study event or study intervention)
• ‘Non-scheduled’ Study Visits
  • i.e. data collected at any time like collection of AE data)
• Unscheduled Study Visits
  • the collection of data related to a Scheduled Study Visits at a Unscheduled Visit, i.e. at a non-scheduled time)
• ”Special” visits
  • Study Visit to be done at special study events, like premature discontinuation of study treatment where subject do continue in the study and can complete the study activities (without the study treatments)
  • Time Profiles
  • A set of pre-specified Time Points

Timepoints needed are:

• Are relative to a time reference, milestone or event
• Can be of different ‘types’
  • Sequence Time Point (e.g. before breakfast, i.e. relative)
  • Nominal Time Point (e.g. 10 minutes after dosing, i.e. absolute to a time reference)
  • Actual Time (e.g. at 8:00 AM local time, i.e. absolute to a local time zone)
• Also required in profiles

Also need support for cohort studies

[dih-cdisc]

Specific SoA points to consider (not extensive) from Berber. Timepoints

• Are linked to activity, encounter and assessment (can be specific for a subgroup)
• Are not directly linked to cohorts and arms
• Might be linked to cycle (like subvisits of Mikkel)

Cycles

• Can be grouped on assessments that occur during the cycle (earlier cycles can have more assessments than later ones)
• Can be infinitely repeated. But that is not the case for every study
• Have a number
• Concept of periods in crossover studies is similar to cycle concept because of equal content for repeats. But in crossover studies it is not infinite. Same can hold of rising dose studies.

Arms

• Can be equal in workflows / can be different. General assessment constraints
• Some assessments/activities are not done for a particular arm
• Some assessments are not done for a subgroup (like pregnancy test for women non-postmenopausal)
• Some assessments are only done in the first period of a crossover study (irrespective of treatment). Like genetic testing only on day -1 of period 1 of the crossover study.

Unscheduled visits:

• Not directly shown in SoA
• Some assessments will be mandatory at each unscheduled visits some optional. This is described elsewhere in the protocol.
• Timing can be at any moment in the study but can also depend on events measured in a scheduled visit (like if value above certain range then come back for extra unscheduled visit)

[dih-cdisc]

Sketch design available here on the wiki

In particular note the slide deck and the diagram 2023 01 25 DDF Model Incl Timepoints"

[dih-cdisc]

Updated sketch design and supporting slide deck

@cupkes @ggasg start having a look

[cupkes]

Ok. Here's what I have so far...

[cupkes]

Let's talk about the timline composition starting at the Timeline class. /**

• The Timeline class is used to compose all of the sequence elements related to the SoA.
• We will use this class to collect the entries, exits and sequenced timepoints
• that will be pointed to by objects such as encounters and activities.
• The idea here is to provide a seqencing perspective of the activities, events and subject encounters
• along with the rules used to define the schedule and its progression.
• @author Chris Upkes */

public class Timeline {

**private final String timelineId;**
// A textual description of the timeline.  There will likely be numerous timelines in a study and this
// field provides the context for the particular timeline.
**private String timelineDescription;**
// It makes sense to have object references to SoA structure objects (timepoint, entry, exit)
// This should be the highest level in the JSON payload to attach the object details.  Below this level
// (such as pointers between timepoints) references will be ID references to avoid duplication.
// The timeline entry and exi don't seem to be as important in the composition of a timeline, if
// we reference "timelines" from higher in the class hierarchy.
// If every timeline has a discrete entry and exit point, then why do we really need seperate, referenceable
// Entry and Exit classes.  This could simply be just some useful attribution in a timeline.
// Example, if I'm grabbing timeline named "base timeline for this study", and I grab the timeline, why do
// I need to deferefeence the entry?  It seems as if I would just ask for the first timepoint, ordinally.
// Maybe entry is an attribute of a timepoint?  Just my thoughts.
**private Entry timelineEntry;**
// Ditto from above for exit.
**private Exit timelineExit;**
// At this point, this is an unordered list of timepoints.  We might consider more encapsulation by
// creating a timepointSequence wrapper.
**private List<Timepoint> timelineTimepoints;**

// Are cycles really discrete timelines that provide some type of iteration mechanism?
// Do we force the design to break cyclic seqences
// off from strictly linear sequences?  Or, do we add complexity to the definition of a timeline
// Maybe a cycle is just attached to an existing timeline defines a time loop?  Remember,
// these aren't your typical "timeines"...they are more of a seqencical structuring of activities, conditions
// and encounters.  So, it's quite logical to want to repeat a portion of a longer sequence to
// meet a particular condition.  I must noodle on this...

// Ok, my initial thoughts lead to a sentinel that observes a timeline and has a cycle start and end maybe...
// and there must be an iteration condition (iterate?  Yes, No).
// A timepoint of type Cycle with a relationship that points to a cycle start (another timepoint) and
// with a condition attached that determines progression?  This could muddy the timepoint and it's
// truly polymorphic while currently the Branch vs Node types don't really have anly overloaded behaviors (yet).
// However, I'm still for it because how is a cycle that much different than a branch except it points
// to something upstream as opposed to downstream?

// It seems plausible to encapsulate starts, ends and loops in the actual timeline class itself.

[cupkes]

Now, let's review the timepoint class:

[cupkes]

/**

• The Timepoint class is used to link activities and encounters to a schedule timeline.
• @author Chris Upkes */

public class Timepoint {

private final String timepointId;
// The textual representation of the timepoint.
private String timepointDescription;
// Denotes the type timepoint object added to the timeline.  The value can be either a node or a branch.
// a branch being used to link alternate or sub-timelines to an existing timeline.
private Code timepointType;
// The condition that may be associated with the timepoint, if the timepoint is of type branch
// (according to the presentation material).
// Even though a condition could or should be re-used across multiple timepoints and/or entries
// this reference should be an object reference as there would be no other object reference
// available to ensure inclusion in the JSON payload (to my understanding)
private Condition timepointCondition;
// Unsure of the nescessity of this id reference to an actual Exit class.
// It seems to make sense to associate an exit condition and maybe an exit flag to a timepoint.
// What attributes are required to be associated with an Exit that should be solely
// contained in an Exit class?  Maybe just saying a timepoint is a final timepoint is just as intuitive?
private String timepointExitId;
// Must assume this is an object reference as no other references exist in the model except for Encounter and
// that would not necessarily be the same timepoint being referenced, so no duplication will likely exist.
// This could be considered an attribute of the timepoint because I'm not sure that the timing
// has any value outside of its inclusion in the timepoint data (except for maybe...reuse?)
private Timing timepointScheduledAt;
// when referencing objects from the timeline, it's important to use id references
// because the API JSON payload would result in duplicate expressions of objects pointing
// to the timeline.  This assumption should be asserted.
// All of these fields below should be defined as relationships in the CT.
// In particular for pointers between timepoints, it seems to me that there
// should be some clear understanding that only a Branch type timepoint
// is capable of pointing to more than one previous or next timepoint.  Am I misunderstanding the
// the use of the type attribute?
private List<String> previousTimepointIds;
private List<String> nextTimepointIds;
// I'm somewhat confused as to why an encounter has multiple touchpoints in the timeline, but I haven't
// heard of a broad set of use cases for traversal of the timeline.
// You can get to a timepoint from an encounter via a timing.  You then have a circular reference from the timing
// via the timepoint.  There is potential for these to be out of sync as well, correct?
private String timepointEncounterId;
// This is the only way to associate activities with timepoints, as we've decided that the cardinality
// from timepoint to activities is one to many, correct?
private List<String> timepointActivityIds;
// I'm still waffling on this entry concept.  We know the first timepoint in any sequence simply because
// it has no pointer to a predecessor. If a timepoint can be a node or a branch, why can't it also be
// an entry timepoint or an exit timepoint.  Polymorphism has been problematic, however, much like BC data,
// it is more elegant that trying to provide solid semantics to differentiate things that are ideally
// seen as similar yet unique among themselves.  Like managing anything as a category without actually
// referencing the category (i.e. StudyData).
private String timepointEntryId;

[cupkes]

Timing up next:

/**

• The Timing class is used to relate timepoints. In graph, this information would likely
• sit on relationship that exists between timepoints. Timepoints can have relationship context
• more sophisitcated the previous and next. This is where that information is captured.
• @author Chris Upkes */

public class Timing {

private final String timingId;
// Code values that describe the type of timing.  Valid values include Before, After and Absolute.
private Code timingType;
// According to the presentation, the value will be provide further context based on the type of the timing.
// For example, if the timing type is absolute then maybe something like "first dose, day 0"
// and if the type is Before it could be "1 day before x".
private String timingValue;
// Code values that describe the timing relative to the associated timepoint, I believe.  Somewhat unsure here.
// Values are typical of gant task relationship dependencies.  They are:  StartToStart, StartToEnd,
// EndToEnd and EndToStart.
private Code timingRelativeToFrom;
// Defines window of time associated with the timing.  This seems like slack in a project timeline.
// Example value could be 2 hour window.  In a standard task sequence that sounds like "2 hours of slack"
// in the schedule to accomplish associated activities, etc... Is this correct?
private String timingWindow;

[cupkes]

Let's wrap up for today with Condition:

/**

• A guide that governs the allocation of subjects to operational options at a discrete decision point or branch
• (e.g., assignment to a particular arm, discontinuation) within a clinical trial plan.
• The above sentencee was associated with the TransitionRule class. We have deprecated the TransitionRule class
• and replaced it with condition. Now...the question is...is the above description appropriate for a condition?
• If not, I believe that deprecating the TransitionRule was a mistake and that we will likely need to
• change the design to provide for both Condition and TransitionRule classes and their assoiated logic.
• @author Chris Upkes */

public class Condition {

private final String conditionId;
// The textual representation of the transition rule.  'Nuff said.
private String conditionDescription;

// Not much to this class.  Doesn't seem like enough information to reside in its own class definition.
// Are we defining this class strictly for reuse in timelines, like codes?
// Still is hard to argue that it's way better as a class reference than a string field, since
// the conditionId is the only thing we're associating with the class except for description.
// The answer must be that we are not done defining the class.