Plan Independent External Data Sources & Events

[jmorton]

Introduction

This discussion proposes the concept of plan-independent events. In this proposal, we explain the underlying motivation, envisioned use cases, and a high-level design that considers real-world challenges.

But before diving in, let me introduce ourselves and provide some additional background. I'm Jonathan Morton, I manage a software team at NASA Goddard Space Flight Center (GSFC) in the Science Mission Operations (SSMO). We have a squad focused on mission planning that includes myself, Pranav Subramanian, and Joe Volosin. Mission planning is one of the core capabilities required by mission operators. We have a strong desire to adopt a common mission planning system for future missions and think Aerie could be the one! To that end, our team wants to collaborate with the Aerie community to identify, explore, and realize new capabilities of value, not just for the SSMO, but the Aerie community at large.

Motivation

We have explored various ways of using resources and activities to manage information about things that will happen beyond a planner's immediate control that influence their decision making (e.g., orbital events, view periods, etc...). Planners at SSMO distinguish between "events" and what they want to do about them (i.e., activities). Although there are ways to represent event data using activities and resources, we perceive a difference between their apparent purposes. Activities seem to be about what a planner wants to do, are intended to be mutable, always occur within the context of a plan, and are produced as part of the planning process. Resources, although related to events, are more about understanding how state changes over time as activities occur. Events are continually revised predictions that may be superseded by subsequent events; are derived from external sources that potentially span multiple planning periods; and are immutable.

We also need to manage the underlying data sources that inform plans separate from any one specific plan. It is our preference to manage such externally provided data sources within Aerie itself, rather than a separate tool or application.

Goals and Use Cases

Our primary goal is to give planners a way to manage different types of data sources and reference the contained events in plans.

Here is a summary of our envisioned use cases:

Basic Use Cases

• I can upload and manage a source that contains events.
• I can manage the sources included by a plan.
• I can see events on the planning timeline.
• I can inspect an event and see its properties.
• I can see the original source file's contents.

Overlapping Sources

• I can supersede older events with newer events in sources with overlapping time ranges.
• I can understand what events have been superseded.
• I can see a plan's distilled set of events derived from all included sources.
• I can associate an event with an activity.
• I can find activities that are associated with superseded events.
• I can determine if a source exists that should be added to a plan.
• I can find sources relevant to a plan.

Event-Aware Scheduling and Constraints

• I can define scheduling goals that produce activities from events.
• I can define constraints that consider events.
• I can use an event's properties as activity parameters.

Advanced Event Type and Source Type Management

• I can manage source types and event types.
• I can control revisions to source and event types.
• I can see the exact place (e.g., line number of a file) an event came from.
• I can define how a text format is transformed to the canonical format. (maybe)

Approach

We will take incremental steps toward the ultimate goal, explain what we did and why, gather feedback, and take another – more informed – next step. We are currently...

• Proposing a tentative JSON representation of a source and its events.
• Defining relational data model for storing sources and events independent of a plan.
• Adding support to Aerie for uploading sources.
• Giving planners a way to associate sources with a plan.
• Displaying events on a plan's timeline.

Concepts

As part of this work, we have realized the following concepts:

• An event happens at a point in time with either a duration or an end time. It has exactly one type. An unspecified duration or end time implies a zero duration.
• A source is container for events that covers an explicit period of time. Sources have an explicit property that is used to determine their order and another that specifies their type.
• An event type specifies the required properties of an event. Can be revised.
• A source type specifies the required properties of an source. Can be revised.
• An inclusion associates events with a plan through sources. An inclusion has exactly one plan and one source. A source has and belongs to many plans via inclusions.

This entity relationship diagram illustrates the relationship between these concepts:

This is an example of a JSON representation of a source that contains one event:

{
  "source": {
    "key": "DSN_VIEW_PERIOD:MMS1_2024001_2024090.V00.json",
    "source_type": "DSN View Period",
    "valid_at": "2021-01-21T00:00:00Z",
    "period": {
        "start_time": "2024-05-01T00:00:00Z",
        "end_time": "2024-05-08T00:00:00Z"
    },
    "metadata": {
        "type-specific": "and...",
        "arbitrary": "values",
    }
  },
  "events": [
    {
      "key": "externally-provided-event-type-specific-unique-id",
      "time": "2021-01-21T19:55:03Z",
      "event_type": "DSN View Period",
      "duration": "PT2M30S",
      "properties": {
        "type-specific": "and...",
        "arbitrary": "values",
      }
    }
  ]
}

Please note: We are very open to naming and organization choices. We have, for the sake of brevity, used shorter names than what would actually be used in the database.

The next sections delves into challenges and implications that inform this proposed (and tentative) structure.

Challenges

There are many challenges to be faced as part of this proposal. We begin with five challenges and explain their implication on our initial design, knowing there will be more to come.

Challenge 1: Source Data Format Variety

Sources come in many different formats that provide various types of events. We propose a JSON representation of sources and events to avoid contending with problems related to handling variety before we do anything else.

Implication 1: Users need to be able to distinguish between types of sources and events. This motivates having a "type" property. We think it is reasonable to differentiate between types of events within a source. There is a separate challenge we identify to discuss versioning of such types and an open question about whether different source types can include the same event type.

Implication 2: Arbitrary properties at the both the source-level and event-level motivate using JSONB to store those properties in the database. We can use JSON schemas to enforce requirements for specific source and event types.

Challenge 2: Source Data Have Rolling Windows

Planners typically receive data that covers a rolling period of time. For example, they may receive a weekly report describing predicted events for a 90-day period. In some cases, changes between events can be clearly established because events have an externally provided identifier. In other cases, it can be difficult to establish equivalence between events from different sources. This has major user experience implications for planners when an activity is predicated on a superseded event. Without a clear identifier, it is more difficult to suggest planners with a resolution.

Our initial foray into a relational model indicates that we can handle both cases using views to distill events. The presence of an externally provided identifier for an event (i.e., a key) – although helpful – is not essential to handle rolling windows. Our preliminary exploration will focus on "keyed" (externally identified events).

Finally, some data sources may not explicitly state that an event contained in previous source was removed; in other words, it is simply omitted and only inferred that the event is no longer expected to happen.

Implication 1: A source must have an explicit ordering property relative to other sources. An implicit property such as the time a file is uploaded could produce surprising and unexpected behavior. The intention of the "valid_at" property seen in the above sample is to provide the ability to order sources.

Implication 2: Sources must explicitly specify the period of time they cover. Without this, it is not possible to determine if events should be treated as if they were removed.

Implication 3: We must maintain an immutable history of all sources and events. We will not update entities in place. Without a history, we impair planners' decision making.

Challenge 3: Externally Provided Identifiers Are Not Coordinated Across Types

Although sources may contain externally provided identifiers, no authority exists to guarantee their global uniqueness.

Implication 1: We must ensure that constraints or aggregates don't treat externally providers as globally unique IDs. Any constraints that are defined, should be also consider an event type.

Challenge 4: Type Definitions May Change

We anticipate a need to support evolving definitions of source-types and event-types. To support this, we suggest a version-aware database schema. Our intent is to allow for an arbitrary JSON schema to enforce type specific requirements of different sources.

Implication 1: Source types and event types must support versioning.

Implication 2: Actual sources and events must refer to a type and version.

Implication 3: We must ensure our uniqueness constraints consider type and type version.

Challenge 5: Event Relationships (e.g., Hierarchy)

We would appreciate community guidance on the subject of relationships between events. Our initial exploration of this topic has been thought provoking yet inconclusive. Although some notion of "parent-child" relationships seems intuitive, the real meaning of a "child" event is unclear.

Furthermore, given the rolling nature of sources, we anticipate many scenarios that will require thorough elaboration consideration to arrive at well-defined system behavior.

Implication: We will defer modeling any event relationships until we have more input.

Other Challenges

Transformers: Providing mission modelers or planners with a way to specify how raw data is transformed into a canonical representation is worth considering. However, it's too early for us to make a recommendation about whether this responsibility is within the scope of Aerie. I am sure the community will have input on this topic!

Streaming: It is conceivable that missions may want to subscribe to a streamed source of events. This suggest that our data model should carefully consider uniqueness constraints and explicit ordering of events. However, we will defer modeling this until further discussion.

Retrodictions: There may be use cases related to viewing historical events (i.e. "retrodictions") to a plan. This could be useful when analyzing executed plans to reason about actual and expected behavior.

Conclusion

Providing a way to support plan-independent events introduces many challenges. We are deeply grateful for your consideration and willingness to collaborate; we are eager to hear your feedback and guidance as we explore this concept.

[ewferg]

@jmorton, thank you for the detailed description on your plans to support plan-independent events into Aerie. We would definitely love to continue to collaborate to fit this idea into Aerie. One additional motivation to note is that the Consultative Committee for Space Data Systems (CCSDS) is currently drafting a standard for Mission Planning and Scheduling services that includes the concept of a "Planning Event" and "Planning Event Type", which is separate from an "Activity" and "Activity Type". If those are interested, these concepts are discussed in the Mission Planning and Scheduling Green Book, which is an information book intended to inform the actual standard (Blue Book).

If you feel comfortable, the community may also be interested in seeing some of the specifications you have designed out for the various elements of your design (e.g. source, source type, event type).

[jmorton]

I have analyzed the description of CCSDS planning events and how they relate to this effort. Although there are similarities between CCSDS planning events and the concepts we are proposing, there is an appreciable difference. Fortunately, the green book explains the distinction.

From section 6.2.4:

"A Planning Event marks when a condition is being met. It is not envisaged to use it to express a condition itself, but rather to express the fact that it is fulfilled. A Predicted Event is the specific instantiation of a Planning Event with its associated value, which may be used during the planning process and in the generated Plan. The Predicted Events are typically provided externally from the planning function (for example by a Navigation function); therefore these elements are not part of the Plan but only referenced from the Plan."

The statement "a predicted event is the specific instantiation of a planning event" trips me up a bit. It seems to me that in Aerie, predicted (externally provided) events will be used by scheduling goals to produce (instantiate) activity directives. That nuance aside, I am quite relieved to see that the notion of externally provided, predicted events and planning events are related but distinct concepts.

[Mythicaeda]

@jmorton Thank you for the detailed write-up! I have one major question and two minor topics I just want your clarification on:

My major question is:
What "level" is a set of uploaded events associated with? As in, are events associated with individual plans, plan families (as in, all plans related to each other via branching), models (as in, all plans belonging to a model), or the entire deployment (as in, all plans). This is very important, as the answer may involve needing to dig into how events interact with plan branching and merging. I initially assumed it was the individual plan level, as the Overlapping Sources section includes the note I can associate an event with an activity, but it seems like the better usability would be model-level or deployment-level, as events are not controlled by the planner and should be persistent regardless of plan.

Minor topics I'd like clarification on:

1. I can associate an event with an activity. I read this as "there may exist a relationship from an event to an activity" and "there are no relationships from activities to events". In this case, I mean "relationship" as a persistent, tracked entity in the DB, as I understand and support the desire to schedule activities or check constraints based off of events.
   • If that understanding's correct, could you please clarify what this relationship might look like, as I'm not sure why an event would reference a specific activity. I can understand why an event might want to reference another event, but that would be related to the "Event Relationships" section.
   • If you mean the inverse of my understanding, then it'd be great if you could again clarify this. However, I can tell you that I'm asking specifically to find out if this was a way of saying "Activities can be anchored to events". When designing activity anchoring, we initially tried to include a different feature also called "events" that served a similar purpose to your proposal, but ran into headaches trying to allow activities to be anchored to the plan or to another activity or to an "event".
2. I can use an event's properties as activity parameters. This is exclusively in the context of scheduling, correct? I assumed so given it was in the Event-Aware Scheduling and Constraints section and that Aerie currently doesn't have any infrastructure to have "variable" activity parameters (as in, an activity directive with a parameter whose value is explicitly pointing to another directive's fields).

[jmorton]

Thank you for the clarifying questions @Mythicaeda. Although we discussed most, if not all, of these questions during our conversation yesterday, I want to provide a recap.

You asked, "what 'level' is a set of uploaded events associated with?" I think events should exist independently of plans and models. In other words, when a file (or source) that contains events is added to Aerie, planners can include those events by selecting sources of interest within the context of a plan. For the time being, I have referred to this association between a plan and sources as an inclusion. During our discussion, I think we reached agreement on a need for an explicit association to provide planners with more control and to avoid dealing with complex rules that infer which sources should be included in plans, especially ones that have been completed. As an aside, I think it's essential for us to understand and support plan branching and merging as part of our effort.

On the matter of the relationship between events and activities, I think it's best for me to explain what we're trying to accomplish before getting into a data model. Planners should be able to schedule activity directives predicated on events and deal with superseding events as new sources are added.

As part of scheduling activities, I would like to use event properties (or values derived from event properties) as activity parameters. For example, an event may contain information about the band during a view period. The scheduler should be able to use the event's property value as an activity parameter. I don't see a benefit to resolving this value by reference. Similarly, there are some activities that should be scheduled some fixed amount of time before or after an event starts (or ends). I need to familiarize myself with the mechanics of anchoring before suggesting we introduce the notion of an activity anchored to either an activity or an event. My intuition is that using anchoring could be problematic.

In order to deal with superseding events, planners will need to know exactly which event was used to schedule an activity. Something we'll need to discuss further is whether activities are associate with a single event or if there are use cases that suggest one activity could be predicated on a collection of events. In the absence of such use cases, the simplest possible data model seems to be a reference from an activity to an event.

I have tried my best to avoid bringing up new discussion items, please let me know if you have additional questions or if you would like me to elaborate further!