diff --git a/docs/planning/assets/create_derivation_group.png b/docs/planning/assets/create_derivation_group.png new file mode 100644 index 0000000..5f5dd6b --- /dev/null +++ b/docs/planning/assets/create_derivation_group.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5d6ea77e145a21655b9da1c66a8ce54883daf768747a5d216c253da510849ec6 +size 81090 diff --git a/docs/planning/assets/create_external_event_type.png b/docs/planning/assets/create_external_event_type.png new file mode 100644 index 0000000..df8885f --- /dev/null +++ b/docs/planning/assets/create_external_event_type.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:eebbfc471a799bddfbc41a67a86e36918ced6d3b57308d15a80a3b3459229a8f +size 77785 diff --git a/docs/planning/assets/create_external_source_type.png b/docs/planning/assets/create_external_source_type.png new file mode 100644 index 0000000..887230a --- /dev/null +++ b/docs/planning/assets/create_external_source_type.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:22b74e49510a117482463d520526d0f34846b495633d65f61dab0462c47eb28f +size 79420 diff --git a/docs/planning/assets/create_groups_and_types_button.png b/docs/planning/assets/create_groups_and_types_button.png new file mode 100644 index 0000000..67bd026 --- /dev/null +++ b/docs/planning/assets/create_groups_and_types_button.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:845a86c6018a34451d8a95ff1c979b83b330cd7363e44f43ddc3bb2f3ba2c13c +size 31934 diff --git a/docs/planning/assets/derivation_example_full.png b/docs/planning/assets/derivation_example_full.png new file mode 100644 index 0000000..edff034 --- /dev/null +++ b/docs/planning/assets/derivation_example_full.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e0a5834dbf72dff4654669bb075c7c206c29e54d48a2620f60b50bd00487beb7 +size 73067 diff --git a/docs/planning/assets/derivation_group_motivation.png b/docs/planning/assets/derivation_group_motivation.png new file mode 100644 index 0000000..9999789 --- /dev/null +++ b/docs/planning/assets/derivation_group_motivation.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6851b6d9998c81d80e1389514e319c818fbfdf9048665d8407c12ce5a5c45181 +size 93623 diff --git a/docs/planning/assets/derivation_group_motivation_ii.png b/docs/planning/assets/derivation_group_motivation_ii.png new file mode 100644 index 0000000..4a09f68 --- /dev/null +++ b/docs/planning/assets/derivation_group_motivation_ii.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9f70e0beef0157651aa27e22e9392303188faa6c2107624a3854feb35e651db4 +size 95461 diff --git a/docs/planning/assets/derivation_motivation.png b/docs/planning/assets/derivation_motivation.png new file mode 100644 index 0000000..9bbdca2 --- /dev/null +++ b/docs/planning/assets/derivation_motivation.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:41caf9b3c55ae06b29f2542fef610f07a955984238a77b1b00a48cf2c54f7bfe +size 57748 diff --git a/docs/planning/assets/external_event_options.png b/docs/planning/assets/external_event_options.png new file mode 100644 index 0000000..7311deb --- /dev/null +++ b/docs/planning/assets/external_event_options.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8a1af0d147f9ae92021219944b124bb76f9d989f346b6ea1504487790cc7c41e +size 38875 diff --git a/docs/planning/assets/external_event_table.png b/docs/planning/assets/external_event_table.png new file mode 100644 index 0000000..5a3ba09 --- /dev/null +++ b/docs/planning/assets/external_event_table.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:24fe6ba30cc1eb74e75956cefff26e823a539c5de35b1a10a02eb9c38469cdab +size 77953 diff --git a/docs/planning/assets/external_events_before.png b/docs/planning/assets/external_events_before.png new file mode 100644 index 0000000..803cb69 --- /dev/null +++ b/docs/planning/assets/external_events_before.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b9c51e5c540458deb7339bf6580f8c70584179b83a6bcda317b66331e4f0e663 +size 492133 diff --git a/docs/planning/assets/external_events_derivation_group_disabled.png b/docs/planning/assets/external_events_derivation_group_disabled.png new file mode 100644 index 0000000..57fb8fc --- /dev/null +++ b/docs/planning/assets/external_events_derivation_group_disabled.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1d2d38842d59ea33d97443a272c2721fbaad55d6cd5b7b42619930b55c10c550 +size 138905 diff --git a/docs/planning/assets/external_events_derivation_group_enabled.png b/docs/planning/assets/external_events_derivation_group_enabled.png new file mode 100644 index 0000000..5e8858b --- /dev/null +++ b/docs/planning/assets/external_events_derivation_group_enabled.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:151be35418e2b9ff5d7ff315fed6e6b2a6ab1db2f7bceb698f54b5cfb141f9c0 +size 157973 diff --git a/docs/planning/assets/external_events_group_by_event_type.png b/docs/planning/assets/external_events_group_by_event_type.png new file mode 100644 index 0000000..431d6bb --- /dev/null +++ b/docs/planning/assets/external_events_group_by_event_type.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:fca17e0e2bc361b6fe194e46ce9fd894891f4cacba03583e091518cca1f27ec6 +size 25703 diff --git a/docs/planning/assets/external_events_group_by_source.png b/docs/planning/assets/external_events_group_by_source.png new file mode 100644 index 0000000..00cd443 --- /dev/null +++ b/docs/planning/assets/external_events_group_by_source.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c58cc153f9593b69b50922b81c962ebcdd6e3907e877549996b35a7d07b3fa94 +size 33543 diff --git a/docs/planning/assets/external_events_on_timeline.png b/docs/planning/assets/external_events_on_timeline.png new file mode 100644 index 0000000..afaa7a7 --- /dev/null +++ b/docs/planning/assets/external_events_on_timeline.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a024e493216bf639bc7cdc523b6de1b0e266928f42035e247296dd03664c5d63 +size 31104 diff --git a/docs/planning/assets/external_events_options.png b/docs/planning/assets/external_events_options.png new file mode 100644 index 0000000..74ff610 --- /dev/null +++ b/docs/planning/assets/external_events_options.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4ff0e768e2e34e34555339bf06391e9ff3d4c0949c83dff4bdf32a76e8078b0b +size 93867 diff --git a/docs/planning/assets/external_events_table.png b/docs/planning/assets/external_events_table.png new file mode 100644 index 0000000..1a006a8 --- /dev/null +++ b/docs/planning/assets/external_events_table.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:33d1663c1f55a272a520b29c8466f3a978034d950eccabe6d2f9cead4769aaa1 +size 153962 diff --git a/docs/planning/assets/external_source_manager_intro.png b/docs/planning/assets/external_source_manager_intro.png new file mode 100644 index 0000000..8cb9cdb --- /dev/null +++ b/docs/planning/assets/external_source_manager_intro.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c4ba57a4db965b33f777e53c27a184d751ced0969c2f3502f0f823b188b9a081 +size 419048 diff --git a/docs/planning/assets/external_source_manager_upload.png b/docs/planning/assets/external_source_manager_upload.png new file mode 100644 index 0000000..579db70 --- /dev/null +++ b/docs/planning/assets/external_source_manager_upload.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4085c3e17cd021c3ce70b103d0b28fe204250c92ccd369e0e9d5280fb669738e +size 46869 diff --git a/docs/planning/assets/external_sources_table.png b/docs/planning/assets/external_sources_table.png new file mode 100644 index 0000000..9d4a9ab --- /dev/null +++ b/docs/planning/assets/external_sources_table.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:76d9f374e24d8c092bd5c5730cf8440d940a3215fb5fba05a20ef96bc5c76e09 +size 368479 diff --git a/docs/planning/assets/inspected_source.png b/docs/planning/assets/inspected_source.png new file mode 100644 index 0000000..a1b90b4 --- /dev/null +++ b/docs/planning/assets/inspected_source.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e44e8110b1b0dd6c0a5415e74d89ce3a15ed0ea6f656858146b19ada80e9b01c +size 52203 diff --git a/docs/planning/assets/manage_derivation_group_modal.png b/docs/planning/assets/manage_derivation_group_modal.png new file mode 100644 index 0000000..f0957ee --- /dev/null +++ b/docs/planning/assets/manage_derivation_group_modal.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4b3b14aa3a58ce96a316624700ce5ac56fd4f1de66a1aad4646e29e0f2c33666 +size 242640 diff --git a/docs/planning/assets/ordering_external_sources.png b/docs/planning/assets/ordering_external_sources.png new file mode 100644 index 0000000..e8c968c --- /dev/null +++ b/docs/planning/assets/ordering_external_sources.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:fb46ab0d859a310728494a8d9993efdba8fa097b08e3c14745cfd7aef3a6aeb9 +size 79791 diff --git a/docs/planning/assets/plan_external_source_full_view.png b/docs/planning/assets/plan_external_source_full_view.png new file mode 100644 index 0000000..0ac39ef --- /dev/null +++ b/docs/planning/assets/plan_external_source_full_view.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4bef05de154c3d0cf1fb4f477ce12bd2b99325c40164ffd040072695ef48b22b +size 669650 diff --git a/docs/planning/assets/plan_external_sources_panel.png b/docs/planning/assets/plan_external_sources_panel.png new file mode 100644 index 0000000..c20d7a5 --- /dev/null +++ b/docs/planning/assets/plan_external_sources_panel.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ecda120f619abab45f0f212e2e148891971049b295dab81e96fce99ccb30e18a +size 132005 diff --git a/docs/planning/assets/plan_selected_external_event.png b/docs/planning/assets/plan_selected_external_event.png new file mode 100644 index 0000000..f207551 --- /dev/null +++ b/docs/planning/assets/plan_selected_external_event.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e317cb1529b7b2b14a3e5fd75e3ab72fef84748e6caeaaba2a2a8a28829a0989 +size 350228 diff --git a/docs/planning/assets/timeline_and_editor_full.png b/docs/planning/assets/timeline_and_editor_full.png new file mode 100644 index 0000000..c2c0385 --- /dev/null +++ b/docs/planning/assets/timeline_and_editor_full.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:685011885b47ab742e2e5c62f359c683e69564a084047b13777960b42f38903e +size 391106 diff --git a/docs/planning/collaboration/merging-plans.mdx b/docs/planning/collaboration/merging-plans.mdx index f41d9ff..9d7330e 100644 --- a/docs/planning/collaboration/merging-plans.mdx +++ b/docs/planning/collaboration/merging-plans.mdx @@ -133,3 +133,9 @@ import approveMerge from './assets/approve-merge.png'; Aerie UI - Approve Merge
Figure 9: Aerie UI - Approve Merge
+ +:::info External Events and Plan Merge + +External Events (specifically, derivation groups) are not included in plan snapshots and merges. This will be addressed in a future release. See [External Events](../../external-events) for more information. + +::: diff --git a/docs/planning/external-events.mdx b/docs/planning/external-events.mdx new file mode 100644 index 0000000..4a3871c --- /dev/null +++ b/docs/planning/external-events.mdx @@ -0,0 +1,570 @@ +import derivationExampleFull from './assets/derivation_example_full.png'; +import derivationMotivation from './assets/derivation_motivation.png'; +import derivationGroupMotivation from './assets/derivation_group_motivation.png'; +import derivationGroupMotivation2 from './assets/derivation_group_motivation_ii.png'; +import externalEventsOnTimeline from './assets/external_events_on_timeline.png'; +import externalEventsTable from './assets/external_events_table.png'; +import externalEventsWithResourcesAndActivities from './assets/external_events_before.png'; +import externalEventLayerOptions from './assets/external_event_options.png'; +import externalSourceOrdering from './assets/ordering_external_sources.png'; +import externalSourceManager from './assets/external_source_manager_intro.png'; +import externalSourceManagerCreateDerivationGroup from './assets/create_derivation_group.png'; +import externalSourceManagerCreateExternalEventType from './assets/create_external_event_type.png'; +import externalSourceManagerCreateExternalSourceType from './assets/create_external_source_type.png'; +import externalSourceManagerCreateGroupsAndTypesButton from './assets/create_groups_and_types_button.png'; +import externalSourceManagerUpload from './assets/external_source_manager_upload.png'; +import externalSourceTable from './assets/external_sources_table.png'; +import externalSourceInspected from './assets/inspected_source.png'; +import planExternalSourceView from './assets/plan_external_source_full_view.png'; +import planExternalSourcesPanel from './assets/plan_external_sources_panel.png'; +import planDerivationGroupModal from './assets/manage_derivation_group_modal.png'; +import planSelectedExternalEvent from './assets/plan_selected_external_event.png'; +import timelineEditorFull from './assets/timeline_and_editor_full.png'; + +# External Events + + +An **External Event** is temporal data used to inform a mission planner's decision making process. By nature, these events are *external* to Aerie itself and represent temporal occurrences that are immutable in nature. + +Examples of External Events include: +* Ground station contacts +* Orbital events +* Weather forecasts + +In this document, we will discuss what External Events are, what their containing entities (External Sources) are, their grouping mechanisms (Derivation Groups), as well as how they manifest within Aerie. + +## Concepts + +### Data Constructs +With External Events (and External Sources) come several constructs. + +#### External Events +External Events represent temporal occurrences outside of the locus of control of the modelled spacecraft(s). See [External Events](#external-events-2) below for more information. + +#### External Sources +External Sources are containers for External Events and the primary way that users interact with External Events. To get External Events into Aerie, an External Source must be uploaded that contains the event definitions inside. See [External Sources](#external-sources-1) below for more information. + +#### External Event Types +External Event Types define the *typing* of each External Event. This typing groups External Events on the basis of the data they represent. For example, an External Event may be of the type `Ground Station Contact`, `Solar Flare`, or `Weather Forecast`. + +#### External Source Types +External Source Types define the *typing* of each External Source. This typing groups External Sources on the basis of the data they contain. For example, you may have an External Source Type of `Weather Report` to represent all your weather reports, and inside each of the `Weather Report`-typed sources you can expect to find External Events that share a common External Event Type that appears in all `Weather Report`-typed sources (ex: Temperature). + +#### Derivation Groups +Derivation Groups are collections of External Sources that can be associated with plans. Within a Derivation Group, the collective External Events from its member External Sources are used to create a *derived* set of events for the Derivation Group. See [Derivation](#derivation) below for more information. + +#### Derivation Group & Plan Associations +Derivation Groups can be *linked* to a plan (or plans) which allows their derived events to be utilized within the plan for visualization, planning, and scheduling. See [UI Usage](#ui-usage) below for more information on use within the UI. + +### External Events +An **External Event** is a construct that represents the occurrence of something outside of what is modeled in the mission model. They could be events that are close to the spacecraft and directly affect behavior on it, like a Ground Contact event that might affect when communications happen, or they could be much more remote, like a constellation event. The main concept with External Events is that they are immutable events that occur at some point in time (either instantaneously, or for some set duration) and can/will impact mission planning. Functionally, these are at the interstice between external datasets and activities, in that they manifest on the timeline as activities (discrete blocks of time), but they themselves do not affect the mission model or invoke any actions similar to external datasets. + +
+ Figure 1: External Events - Timeline view +
Figure 1: External Events - Timeline view
+
+ +#### Why? +The need for these became apparent after an exploration of External Events implemented as activities and as resources. To mimic the same construct as a resource, we would need to parse the external data and then place it on the timeline as a discrete resource, which given the fact that there are gaps between events and there can also be simultaneous events proved extremely unwieldy and awkward. While activities were a more natural representation, we still required an intermediary of a resource to schedule these activities based off of an ingested file, as it isn't possible to schedule activities exclusively following information in a file. + +
+ Figure 2: External Events - External Events with resources and activities +
Figure 2: External Events - External Events with resources and activities
+
+ +:::info Note + +Currently, External Events are *not* accessible to the automated scheduler for purposes of generating activities based on events, satisfying constraints, or other interactions with other data in Aerie. However, this is in the planned scope for External Events, and future releases will add these capabilities + +::: + +### External Sources +**External Sources** represent a collection of External Events. When we upload External Events, we can only do so by uploading them in an External Source. + +These sources are to be defined in `JSON`, following a general format that will be discussed below. Any data a user wishes to turn into an External Source/External Events should be converted to the `JSON` format to allow ingest within Aerie. + +:::info Note + +There is currently no well-defined, official `JSON` schema for External Source input, however there are required fields which will be mentioned below, and any non-known fields included will be ignored during ingest. Additionally, no tool currently exists to provide the generic translation to the `JSON` format, however this is a feature planned for a future release. + +::: + +#### Schema +There are two parts to each External Source: 1) a `source` header and 2) a collection of `events`: +```json +{ + "source": { + // fields + }, + "events": [ + // events + ] +} +``` + +##### Source + +The `source` field includes the following fields: + +* `key` + * Unique identifier for the External Source + * Uniqueness must hold across the **Derivation Group** that it is a a part of + * Typically a filename or combination of details about the source itself (i.e., an external version number, spacecraft identifier, etc.) + * **Example**: `ExampleExternalSource:example-external-source.json` + +* `type` + * Used to classify the External Source, and categorize for grouping/filtering within the UI & Derivation Groups (see [External Source Types](#external-source-types) for more information) + * **Example**: `ExampleSourceType` + +* `valid_at` + * Similar to a version number, though it describes at exactly what real-world time a file becomes *valid* + * Can be sorted and ordered like a version number, but additionally provides extreme detail about when it can/should be utilized which plays a key role in [derivation](#derivation) + * **Example**: `2022-001T00:00:00Z` + +* `period` + * Specifies the exact range of simulation/plan time over which this external source applies. + * Multiple External Sources of the same External Source Type may cover the same `period`, which is where `valid_at` comes into play - see [derivation](#derivation) for more information + * Composed of a combination of `start_time` and either `end_time` *or* `duration` + * **Example** + ```json + ..., + "period": { + "start_time": "2022-001T00:00:00Z", + "end_time": "2022-008T00:00:00Z" + }, + ... + ``` + +##### Events + +Events are represented as a set of objects contained in a list, and each event has the following fields: + +* `key` + * Unique identifier for the External Event + * Uniqueness is required within the External Source, but **not** across different External Sources. For more information, see [derivation](#derivation) + * Currently has no restrictions or requirements, though those can be optionally imposed by users - see [Formal JSON Schema](#formal-json-schema) for more information + * **Example**: `ExampleEvent:1/sc/sc1:1:X/1` + +* `event_type` + * Used to classify the External Event, and categorize for grouping/filtering within the UI & Derivation Groups (see [External Event Types](#external-event-types) for more information) + * **Example**: `GroundContact` + +* `start_time` + * Specifies the start time of the External Event within simulation/plan time + * **Example**: `2022-001T00:00:00Z` + +* `duration` + * Specifies how long the External Event lasts in simulation/plan time (represented in `HH:MM:SS`) + * This value may be 0 to represent an instantaneous event (ex: time of sunrise/sunset) + * **Example**: `00:30:00` + +##### Full External Source Example + +The following is a full example of a valid, `JSON` representation of an External Source that can be ingested by Aerie. + +The example represents a week-long weather forecast where each event is the report for a specific day. + +```json +{ + "source": { + "key": "WeatherForecast2024001_2024008.json", + "source_type": "WeatherForecast", + "valid_at": "2024-01-00T00:00:00Z", + "period": { + "start_time": "2024-001T00:00:00Z", + "end_time": "2024-008T00:00:00Z" + } + }, + "events": [ + { + "key": "Weather/Day/001", + "event_type": "WeatherReport", + "start_time": "2024-001T00:00:00Z", + "duration": "24:00:00" + }, + { + "key": "Weather/Day/002", + "event_type": "WeatherReport", + "start_time": "2024-002T00:00:00Z", + "duration": "24:00:00" + }, + { + "key": "Weather/Day/003", + "event_type": "WeatherReport", + "start_time": "2024-003T00:00:00Z", + "duration": "24:00:00" + }, + { + "key": "Weather/Day/004", + "event_type": "WeatherReport", + "start_time": "2024-004T00:00:00Z", + "duration": "24:00:00" + }, + { + "key": "Weather/Day/005", + "event_type": "WeatherReport", + "start_time": "2024-005T00:00:00Z", + "duration": "24:00:00" + }, + { + "key": "Weather/Day/006", + "event_type": "WeatherReport", + "start_time": "2024-006T00:00:00Z", + "duration": "24:00:00" + }, + { + "key": "Weather/Day/007", + "event_type": "WeatherReport", + "start_time": "2024-007T00:00:00Z", + "duration": "24:00:00" + }, + ] +} +``` +:::info Note + +Currently, External Sources only accept a `start_time` and an `end_time`, whereas External Events accept only a `start_time` and a `duration`. This may change in the future (i.e. External Events may accept a start time and an end time as well, for example). This is largely due to simplicity in implementation. + +::: + +### Derivation + +Derivation was an operation conceived for the reconciliation of overlapping External Sources. The problem at hand was that it is entirely possible for sources to be generated at later points in time, that cover slightly different windows of plan time than their predecessors. + +
+ Figure 3: A diagram illustrating a motivating case for derivation +
+ Figure 3: A diagram illustrating a motivating case for derivation. Which events should be present? +
+
+ +If this is the case, some reconciliation scheme is needed to determine which External Events from these External Sources are valid and should be visible on the timeline. + +#### Reconciliation Mechanism + +To begin this discussion, we should first talk about when External Sources apply. + +External Sources, as discussed earlier, have within them a `valid_at` field, which was described as a more particular form of a version number. With this, we know we can impose an ordering of External Sources. Given that ordering, figuring out when each External Source actually applies is as simple as determining, for a given time (or slot of time), what the most recently valid External Source is. For example, the following set of 4 External Sources would be applicable in the following order. Note that one of the External Sources, `B`, is valid twice, as it is the most recently valid External Source for a given slot of time: + +
+ Figure 4: A diagram illustrating how External Sources are reconciled against each other in terms of the time slots they occupy +
+ Figure 4: A diagram illustrating how External Sources are reconciled against each other in terms of the time slots they occupy +
+
+ +Given this, we can now discuss how to derive External Events from a Derivation Group of External Sources. There are 4 rules (though the first two are effectively cases of each other): + +1. _An External Event superseded by nothing will be present in the final, derived result._ + + The logic behind this is that this External Event has no future data that might challenge its validity, so it reasonably would trickle down as an event in a final result. + +2. _An External Event partially superseded by a later External Source, but whose start time occurs before the start of said External Source(s), will be present in the final, derived result._ + + The logic behind this is similar. This External Event, at its start, has no future data that might challenge its validity. Because its start is still considered valid, we accept the event in its entirety to the final, derived result, as no future External Source that could overlap with this External Event could place an External Event that applies to the time that this External Event starts at. If it did, we have a case of rule 3. + +3. _An External Event whose start is superseded by another External Source, even if its end occurs after the end of said External Source, will be replaced by the contents of that External Source (whether they are blank spaces, or other events)._ + + The logic here is simply that we now have more recent data, so we can safely do a complete replacement. Should an External Event be replaced despite ending after the original source, we can still justify this as the updated External Source - if it had need for such an External Event - would have included it. + +4. _An External Event that shares an ID with an External Event in a later External Source will always be replaced._ + + By introducing naming, we can allow replacement. + +#### Derivation Example +A diagram illustrating each of the derivation cases follows: + +
+ Figure 5: An example illustrating each derivation case +
+ Figure 5: An example illustrating each derivation case +
+
+ +The following explains what is happening to each External Event in the example: + +* **External Source A** + + * **2:D** + * Status: _Excluded_ + * Rules + * **3**: Even though its end is after end of External Source B, the start is subsumed. In any case, it is wholly subsumed by External Source C. + * **4**: Replaced by key in External Source C (regardless of the fact that the new event has a different type). + + * **7:C** + * Status: _Excluded_ + * Rules + * **3**: Even though its end is after end of External Source B, the start is subsumed. + + * **8:B** + * Status: **Included** + * Rules + * **1**: This External Event is subsumed by nothing. + +* **External Source B** + + * **1:A** + * Status: **Included** + * Rules + * **1**: This External Event is subsumed by nothing. + + * **2:A** + * Status: _Excluded_ + * Rules + * **3**: Completely subsumed by External Source D. + * **4**: replaced by key in External Source C (regardless of the fact that the new event has a different type). + + * **3:B** + * Status: **Included** + * Rules + * **2**: Starts before any other External Source, despite end being subsumed. + + * **4:B** + * Status: _Excluded_ + * Rules + * **3**: Completely subsumed by later External Source. + +* **External Source C** + + * **5:C** + * Status: **Included** + * Rules + * **1**: This External Event is subsumed by nothing. + + * **6:C** + * Status: **Included** + * Rules + * **1**: This External Event is subsumed by nothing. + + * **2:B** + * Status: **Included** + * Rules + * **1**: This External Event is subsumed by nothing. + * **4**: Also most recent occurrence by key name, so this is the only one that persists + +* **External Source D** + + * **9:C** + * Status: **Included** + * Rules + * **1**: This External Event is subsumed by nothing. + +#### Derivation Groups + +The final question remaining is: **what set of external sources** will this derivation operation be run against? One possible candidate for this could be the External Source Type. External Events that share an External Source Type include External Events of the same types, and will likely overlap in key namespace as well. This is a nearly ideal solution except in the case of contingencies. + +Imagine we have 4 sources of the same source type. Two of these relate to an ideal contingency, and two of these relate to a degenerate contingency: + +1) **Ideal** + + * `DSN_Contact_Ideal_2026001007.json` + * `DSN_Contact_Ideal_2026003010.json` + +2) **Degenerate** + + * `DSN_Contact_Degen_2026001007.json` + * `DSN_Contact_Degen_202603010.json` + +If we were to derive solely based on External Source Type, we would effectively be stacking **all** of these sources against each other to produce **one** result: + +
+ Figure 6: A diagram illustrating the unwanted conflation of two sets of sources +
Figure 6: A diagram illustrating the unwanted conflation of two sets of sources
+
+ +Given that these are different cases (despite sharing a source type) it would be useful to have different groups under which derivation is possible. This way, we don't conflate sources just for sharing a source type: + +
+ Figure 7: A diagram illustrating the prevented conflation of two sets of sources +
Figure 7: A diagram illustrating the prevented conflation of two sets of sources
+
+ +As such, we now define the notion of a **Derivation Group**. A Derivation Group defines a subgroup within an External Source Type, of External Sources to derive against each other. Derivation Groups are what we associate with plans (as opposed to individual, un-derived External Sources, or entire External Source Types). + +## UI Usage +External Events show up in the UI in two main places - an External Source Manager, and in plans (both in panels and timelines). Our discussion of UI features will therefore be divided along which page the features appear on. + +:::info Note + +There is also a [tutorial section](../../tutorials/external-events/introduction) that walks through the content of this section in a step-by-step fashion, albeit with less detail. + +::: + +### External Source Manager +The External Source Manager page handles the uploading & inspection of External Sources, as well as the creation and management of Derivation Groups. + +
+ Figure 8: External Source Manager +
Figure 8: External Source Manager
+
+ +#### Creating External Source Types, External Event Types, and Derivation Groups +Within the External Source Manager, the user is able to create new External Source Types, External Event Types, and Derivation Groups. While this is currently **not required** (and these structures will be automatically created if they don't exist on source upload), it is planned to be the main way of creating these types in the future as each will require a strict schema to generate. + +To create one of these types, click the `Create New Groups or Types` button in the top-right: + +
+ Figure 8: Create Groups and Types button +
Figure 8: Create Groups and Types button
+
+ +Once the modal has been opened there is a set of tabs - select the tab for the data type you'd like to create: + +##### Creating a Derivation Group +Creating a Derivation Group requires both a name for the group, and a source type to link it with. + +
+ Figure 8: Create a Derivation Group +
Figure 8: Create a Derivation Group
+
+ +##### Creating an External Source Type +Creating an External Source Type just requires a name for the type. + +
+ Figure 8: Create an External Source Type +
Figure 8: Create an External Source Type
+
+ +##### Creating an External Event Type +Creating an External Event Type just requires a name for the type. + +
+ Figure 8: Create an External Event Type +
Figure 8: Create an External Event Type
+
+ +#### Uploading an External Source +The main view allows users to upload External Sources. Most of these fields autofill and are immutable once parsed - except the Derivation Group which will be autofilled in the style of `external_source_type Default`, but can be edited by the user before upload. + +
+ Figure 9: Uploading an External Source +
Figure 9: Uploading an External Source
+
+ +#### Inspecting an External Source +After uploading an External Source, it will show up in the table on the upper-right pane. This table can be filtered by External Source Type as well as sorted by each of the columns - note the default multi-sorting on the columns `Source Type`, `Derivation Group`, and `Valid At`, which is meant to present the sources in the easiest-to-read manner (grouping by their common types & Derivation Groups, then ordering by their `Valid At` times). + +
+ Figure 10: External Source Table +
Figure 10: External Source Table
+
+ +Selecting a source allows for the inspection of the source, which is essentially an in-Aerie rendering of what's included under `source` in the uploaded `JSON` (as discussed earlier). It is here, as well as in the table, that deletion can be performed. Note that for deletion to work, an External Source must not be associated with any existing plan (that is the Derivation Group it is a part of must be dissociated from all plans before deletions become legal). Aside from that, there is currently no system of ownership, meaning admins and users alike, as long as External Sources satisfy the aforementioned condition, can delete at will. Viewers, however, cannot. + +It should also be noted that all this inspection takes place outside the context of a plan, so that External Sources & their events can be viewed without having to open and associate the External Source(s) to a plan. + +
+ Figure 11: Inspected External Source +
Figure 11: Inspected External Source
+
+ +Finally, it is also possible to inspect each source's contained events as a table. This is useful, as Derivation Groups on plan timelines only show what has been derived, meaning anything that has been selected against won't appear. This page is therefore the absolute truth to see everything that is included, derived-out or not, with a given External Source. + +
+ Figure 12: External Events Table +
Figure 12: External Events Table
+
+ +### Plan +Once an External Source has been uploaded, it can be viewed and interacted with in the context of a plan. + +
+ Figure 13: Overview of the plan view containing External Event information +
Figure 13: Overview of the plan view containing External Event information
+
+ +To begin working with external sources in the plan, the left side panel should be set to the "External Sources" option. This panel is where users (administrators or plan collaborators) can associate different Derivation Groups with the plan. + +#### Derivation Group Management + +There are currently two levels to linking a Derivation Group to a plan: **association** and **enabling**. Association is handled here, via the _Manage Derivation Groups_ button. This presents a modal where users can expand different Derivation Groups to view the associated sources and select whether or not they would like to associate said Derivation Group with their plan. + +
+ Figure 14: Derivation Group Modal +
Figure 14: Derivation Group Modal
+
+ +**Association** simply means that the plan is *aware* of the existence of the Derivation Group, and is the gatekeeper for whether it is visible in the External Sources panel. In this panel lies the second level to linking, which is enabling. **Enabling** simply dictates whether a Derivation Group (even if the filters in the *Timeline Editor* select for it) is *visible* on the timeline. Disabling hides all events associated with the group completely, whereas enabling does the opposite. It does not, however, dissociate the plan and Derivation Group. This is simply a visibility attribute and is actually persisted as part of the view (and even persists after Derivation Group dissociation/reassociation, meaning if a Derivation Group is dissociated and then re-associated, its "enabled" setting stays the same). + +Once a Derivation Group has been associated with the plan, new external event sources may be added to it (or deleted from it), causing the derivation process to automatically re-run, and affecting the events which are shown on the plan timeline. For this reason, this panel also provides users with a notification of recently added and deleted sources which affect this plan, and their respective External Source Type and Derivation Group. This notification persists until acknowledged with the `Dismiss` button. + +Enabled|Disabled +:-------------------------:|:-------------------------: +![Enabled.](./assets/external_events_derivation_group_enabled.png) | ![Disabled.](./assets/external_events_derivation_group_disabled.png) + +
+ Figure 15: External Sources Panel +
Figure 15: External Sources Panel
+
+ +#### Timeline +The timeline shows any events from Derivation Groups that are associated with the plan, enabled in the current view, and are filtered for in the timeline editor. Having covered the first two, we can now discuss the editor and its effects on the timeline. + +
+ Figure 16: Timeline & Layer Editor +
Figure 16: Timeline & Layer Editor
+
+ +The layer of the timeline is modelled after the activity layer, as it provides an easily readable representation of discrete-time occurrences. Layers share the layer options also provided to activity layers, as well as implementing a 'Group By' option specifically for external events. The 'Group By' mechanic allows the user to have external events either grouped by their external source (within the derivation group), or their event types. + +'Group By' External Source|'Group By' External Event Type +:-------------------------:|:-------------------------: +![External Source](./assets/external_events_group_by_source.png) | ![External Event Type](./assets/external_events_group_by_event_type.png) + +
+ Figure 17: External Event Layer Options +
Figure 17: External Event Layer Options
+
+ +#### Tables and Inspection +The screenshot below shows a brief overview of the remaining panels that have been added to plans. It is possible to either mouse over External Events for additional detail or to select them in the timeline, which selects them in a table view beneath the timeline as well as details them in the right pane. This looks as follows: + +
+ Figure 18: The selected External Event view and a table of External Events, working in tandem +
Figure 18: The selected External Event view and a table of External Events, working in tandem
+
+ +#### A Note on Views +As a final note on the frontend, it is worth briefly detailing what parts of the plan page additionally get persisted when a view is saved: +- _Derivation Group enablement_ - whether a Derivation Group is enabled or not in the External Sources panel, +- _External Event Type filters_ - the External Event Type filters selected in the timeline editor, +- _External Event options_ - the options in the timeline editor filter. + +## What Remains +Here, we discuss briefly everything that is not currently implemented but that we do plan to in the future. + +### Formal JSON Schema +We currently lack a formal schema uploaded External Sources and their contained External Events. The extent of our schema is just that we ask users to include the fields described in [External Sources](#external-sources), and that any additionally defined fields will be ignored. + +Prior to starting work in the UI, some work on a schema was done. However, it was ultimately ruled that making something restrictive like a schema might be smarter after having done some work on External Events, as it is entirely possible to spend a lot of time on a schema beforehand only to discard or rework a fair amount of it as we progress with development. At this point, we are a lot more confident in what fields should definitely be present in a [JSON Schema](https://json-schema.org/learn/getting-started-step-by-step), which means that creating a definition should be a lot more feasible in a future batch of work. + +These Schemae would likely be a part of the mission model themselves; seeing as defining what activities and resources are allowable for a mission plan are part of a mission model, so too would be definitions of allowable External Source Types and External Event Types. + +This raises the question of how External Source Types and External Event Types should be handled in a Schema. The idea we are currently floating is a multilayered Schema - one that is common to all sources (and events), which essentially details the fields listed in [External Sources](#external-sources), as those show in any External Source regardless of type. The second layer would constrain for an External Source's `metadata` field (to be included in a future update) and for an External Event's `metadata` field (to be included in a future update). Different External Source Types and External Event Types should have different allowable `metadata`, and as such defining a subschema for these fields becomes necessary to restrict and add uniformity to what should be included in that field given the type. It is these subschemae that we suggest should be part of a mission model. Exactly how this definition is to be created, how these layers are to be reconciled, and how to integrate them with the concept of a mission model is yet to be decided. + +### Ownership/Roles + +Our current solution to a lack of clear ownership/roles around External Sources is as follows: +- any user and any administrator can add External Sources, +- as there is no ownership yet, any user and any administrator can delete External Sources as long as the Derivation Group they are a part of is not associated with any plans, and +- associations between plans and Derivation Groups can be handled by any administrator or a user that is collaborating on that plan. + +It might make sense to add ownership, i.e. a given user owns an External Source and therefore has privileges to delete it (much like how plans are implemented, except External Sources cannot be edited), but as it would primarily be used for deletion functionality but would introduce a lot of complexity for this simple problem, it was sidelined entirely. + +That being said, as we move forward with more features relating to External Events, more nuance may come to the problem of ownership and roles. Once plans start actually depending on these plans, the rules surrounding ownership and permissions may need to change or be entirely rethought. Ultimately, we need something that justifies the implementation of such a scheme in that it provides more than the status quo. + +### Scheduling/Constraints + +This is the biggest "coming-next" feature, but also the least explored. It is planned to be part of the next batch of work relating to External Events. We would like External Events to get the same visibility that activities and resources get in the scheduling and constraints EDSLs and engines. Ideally, we could define a scheduling goal (or constraint), like the following: + +``` +export default () => + Goal.CoexistenceGoal({ + forEach: ExternalEventExpression.ofType(ExternalEventTypes.Eclipse), + activityTemplate: ActivityTemplates.SolarDisable({ rate: 0.5 }), + startsAt: TimingConstraint.singleton(WindowProperty.START) + }); +``` + +which might be how one could write a scheduling goal to place an activity disabling a solar panel whenever an eclipse occurred. diff --git a/docs/tutorials/external-events/assets/external_events_overlapping_sources.png b/docs/tutorials/external-events/assets/external_events_overlapping_sources.png new file mode 100644 index 0000000..0618d77 --- /dev/null +++ b/docs/tutorials/external-events/assets/external_events_overlapping_sources.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:cd7e2309fd774ac8eabcd30c325cb61d55f2404dd9b90e2bb09d21c10bcdb30f +size 60855 diff --git a/docs/tutorials/external-events/assets/external_events_tutorial_adding_row_step1.png b/docs/tutorials/external-events/assets/external_events_tutorial_adding_row_step1.png new file mode 100644 index 0000000..bdc0656 --- /dev/null +++ b/docs/tutorials/external-events/assets/external_events_tutorial_adding_row_step1.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4bcdd71961db0c0274b897cb5185b17d2b0bef3663f9cf6469bf605a538f3210 +size 50963 diff --git a/docs/tutorials/external-events/assets/external_events_tutorial_adding_row_step2.png b/docs/tutorials/external-events/assets/external_events_tutorial_adding_row_step2.png new file mode 100644 index 0000000..2bfff05 --- /dev/null +++ b/docs/tutorials/external-events/assets/external_events_tutorial_adding_row_step2.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e430202ae893354943bec83db7ccda06fdde69ba4880531cbaeafd1dd170e371 +size 127661 diff --git a/docs/tutorials/external-events/assets/external_events_tutorial_adding_row_step3.png b/docs/tutorials/external-events/assets/external_events_tutorial_adding_row_step3.png new file mode 100644 index 0000000..4c607f0 --- /dev/null +++ b/docs/tutorials/external-events/assets/external_events_tutorial_adding_row_step3.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6dfa4b8456d3e3f50c2ff95672f8bed503bb46879a475f6c3f95f48667a1fdaa +size 45687 diff --git a/docs/tutorials/external-events/assets/external_events_tutorial_disableddgview.png b/docs/tutorials/external-events/assets/external_events_tutorial_disableddgview.png new file mode 100644 index 0000000..42a6ee8 --- /dev/null +++ b/docs/tutorials/external-events/assets/external_events_tutorial_disableddgview.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:af7d82dd6e707b30cd71902df006ee2f7454ff234c4aa01acd5129fd9e05ce38 +size 106675 diff --git a/docs/tutorials/external-events/assets/external_events_tutorial_disableddgviewreal.png b/docs/tutorials/external-events/assets/external_events_tutorial_disableddgviewreal.png new file mode 100644 index 0000000..335f40e --- /dev/null +++ b/docs/tutorials/external-events/assets/external_events_tutorial_disableddgviewreal.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:67533f161545271b3fe7aabafc267a7d1e8c0428700dd85e0e39dd52f1e5a9e4 +size 510168 diff --git a/docs/tutorials/external-events/assets/external_events_tutorial_enableddg_view.png b/docs/tutorials/external-events/assets/external_events_tutorial_enableddg_view.png new file mode 100644 index 0000000..5df9819 --- /dev/null +++ b/docs/tutorials/external-events/assets/external_events_tutorial_enableddg_view.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b22a186d73e6e58e907a7daaa4e51ffcbefd26e9d030c5aab95ec5f403058959 +size 107107 diff --git a/docs/tutorials/external-events/assets/external_events_tutorial_enableddgviewreal.png b/docs/tutorials/external-events/assets/external_events_tutorial_enableddgviewreal.png new file mode 100644 index 0000000..0ca5bf1 --- /dev/null +++ b/docs/tutorials/external-events/assets/external_events_tutorial_enableddgviewreal.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7c131aae2385622133dd4ab8b335693cd1023a172a7656a4746da5762015d46e +size 527265 diff --git a/docs/tutorials/external-events/assets/external_events_tutorial_external_sources_empty.png b/docs/tutorials/external-events/assets/external_events_tutorial_external_sources_empty.png new file mode 100644 index 0000000..da1767b --- /dev/null +++ b/docs/tutorials/external-events/assets/external_events_tutorial_external_sources_empty.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:39ab1f9021ee16778e040cb5326dc5a926293fef5f035b81704670c768764a10 +size 51721 diff --git a/docs/tutorials/external-events/assets/external_events_tutorial_filter_shown.png b/docs/tutorials/external-events/assets/external_events_tutorial_filter_shown.png new file mode 100644 index 0000000..c7011f9 --- /dev/null +++ b/docs/tutorials/external-events/assets/external_events_tutorial_filter_shown.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:96c3bfb74987d271184433ccd067a82ffff3dca6c3fd69ee8a7fc048f6e74027 +size 279948 diff --git a/docs/tutorials/external-events/assets/external_events_tutorial_manage_derivation_groups_modal.png b/docs/tutorials/external-events/assets/external_events_tutorial_manage_derivation_groups_modal.png new file mode 100644 index 0000000..580a5a8 --- /dev/null +++ b/docs/tutorials/external-events/assets/external_events_tutorial_manage_derivation_groups_modal.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:165d02a0182c035852d042fe463893e990fc11cc8c0736bbfcec597405a55107 +size 176601 diff --git a/docs/tutorials/external-events/assets/external_events_tutorial_new_association.png b/docs/tutorials/external-events/assets/external_events_tutorial_new_association.png new file mode 100644 index 0000000..62072b8 --- /dev/null +++ b/docs/tutorials/external-events/assets/external_events_tutorial_new_association.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ed537d2471c883ff81735b488212dc119247a5e6d4da2f8beedcf7e1c92890e4 +size 110653 diff --git a/docs/tutorials/external-events/assets/external_events_tutorial_opening_edit_row.png b/docs/tutorials/external-events/assets/external_events_tutorial_opening_edit_row.png new file mode 100644 index 0000000..16b20c9 --- /dev/null +++ b/docs/tutorials/external-events/assets/external_events_tutorial_opening_edit_row.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:dc24079b9e0bce0eea558f9a72d56288b2a310f59e8c5a67515d7fe293f4717a +size 51752 diff --git a/docs/tutorials/external-events/assets/external_events_tutorial_opening_row_settings.png b/docs/tutorials/external-events/assets/external_events_tutorial_opening_row_settings.png new file mode 100644 index 0000000..dfe16f8 --- /dev/null +++ b/docs/tutorials/external-events/assets/external_events_tutorial_opening_row_settings.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b86ed83b69a4c9b58aacb9e7d6310124756c8a8316281feeaea583d24a805c8e +size 19652 diff --git a/docs/tutorials/external-events/assets/external_events_tutorial_plan_page.png b/docs/tutorials/external-events/assets/external_events_tutorial_plan_page.png new file mode 100644 index 0000000..9f03a4a --- /dev/null +++ b/docs/tutorials/external-events/assets/external_events_tutorial_plan_page.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c420446246270ace59800c3ffe42b8f0afdf226a44578d8e1ed484b5c6751e44 +size 132076 diff --git a/docs/tutorials/external-events/assets/external_events_tutorial_plan_parameters.png b/docs/tutorials/external-events/assets/external_events_tutorial_plan_parameters.png new file mode 100644 index 0000000..0c6a0e7 --- /dev/null +++ b/docs/tutorials/external-events/assets/external_events_tutorial_plan_parameters.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:db4e6e199ad47ce4f66a983f7bd41c36d72a561f2b4bebd1e35ede672587c340 +size 79681 diff --git a/docs/tutorials/external-events/assets/external_events_tutorial_plan_specific_intro_page.png b/docs/tutorials/external-events/assets/external_events_tutorial_plan_specific_intro_page.png new file mode 100644 index 0000000..11f83c3 --- /dev/null +++ b/docs/tutorials/external-events/assets/external_events_tutorial_plan_specific_intro_page.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7769108b644bf320e9dc1065dde23e1f45b2f54a561c7eb86a301f8a6c54e265 +size 427517 diff --git a/docs/tutorials/external-events/assets/external_events_tutorial_timeline_editor.png b/docs/tutorials/external-events/assets/external_events_tutorial_timeline_editor.png new file mode 100644 index 0000000..4aaa5e6 --- /dev/null +++ b/docs/tutorials/external-events/assets/external_events_tutorial_timeline_editor.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:86b113f02a673a32103a86eb7d885ea278307b8df6d09fdd63a636ede3afcec8 +size 106907 diff --git a/docs/tutorials/external-events/assets/external_events_tutorial_timeline_step1.png b/docs/tutorials/external-events/assets/external_events_tutorial_timeline_step1.png new file mode 100644 index 0000000..d872fde --- /dev/null +++ b/docs/tutorials/external-events/assets/external_events_tutorial_timeline_step1.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:984055bc8b7a416677b4925ec5998fe4c12d49965af53ca8208e43f4481daf12 +size 134201 diff --git a/docs/tutorials/external-events/assets/external_events_tutorial_timeline_step2.png b/docs/tutorials/external-events/assets/external_events_tutorial_timeline_step2.png new file mode 100644 index 0000000..c77f9f1 --- /dev/null +++ b/docs/tutorials/external-events/assets/external_events_tutorial_timeline_step2.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:579e4f2fef776ec9ba0a5a5593c8590e99c5c5139cefae3692cb642a5b3c50a7 +size 101789 diff --git a/docs/tutorials/external-events/assets/external_events_tutorial_upload_step1.png b/docs/tutorials/external-events/assets/external_events_tutorial_upload_step1.png new file mode 100644 index 0000000..a01aa01 --- /dev/null +++ b/docs/tutorials/external-events/assets/external_events_tutorial_upload_step1.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:acc6392a24a61d8699ba3259ba70f8258bbd0f42e9648e14b845c9ffeee6ab51 +size 115462 diff --git a/docs/tutorials/external-events/assets/external_events_tutorial_upload_step2.png b/docs/tutorials/external-events/assets/external_events_tutorial_upload_step2.png new file mode 100644 index 0000000..e9fb44b --- /dev/null +++ b/docs/tutorials/external-events/assets/external_events_tutorial_upload_step2.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3350ee5716c0c59074afbc4b45d159fa3ebeca4aedb4826c14b63791a39f2d2e +size 43964 diff --git a/docs/tutorials/external-events/assets/external_events_tutorial_upload_step3.png b/docs/tutorials/external-events/assets/external_events_tutorial_upload_step3.png new file mode 100644 index 0000000..ffa0f8d --- /dev/null +++ b/docs/tutorials/external-events/assets/external_events_tutorial_upload_step3.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:115672a75c4777bf76692decd10bfc7b7dd2b166df26109cf48931fd4eb345dc +size 331700 diff --git a/docs/tutorials/external-events/assets/external_events_tutorial_upload_step4.png b/docs/tutorials/external-events/assets/external_events_tutorial_upload_step4.png new file mode 100644 index 0000000..87a878d --- /dev/null +++ b/docs/tutorials/external-events/assets/external_events_tutorial_upload_step4.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8d9496806831fd734e2392a8e28e6e2c9a31fc3a7c88904ec91992cc7179b9a5 +size 348269 diff --git a/docs/tutorials/external-events/assets/external_events_tutorial_upload_step5_table.png b/docs/tutorials/external-events/assets/external_events_tutorial_upload_step5_table.png new file mode 100644 index 0000000..58e1979 --- /dev/null +++ b/docs/tutorials/external-events/assets/external_events_tutorial_upload_step5_table.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b1ac860d2725c1df8185d5b8918ed53ba1ac836a825f9115b8786c6f7dab307a +size 150599 diff --git a/docs/tutorials/external-events/assets/external_events_tutorial_upload_step5_timeline.png b/docs/tutorials/external-events/assets/external_events_tutorial_upload_step5_timeline.png new file mode 100644 index 0000000..dd3667a --- /dev/null +++ b/docs/tutorials/external-events/assets/external_events_tutorial_upload_step5_timeline.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a6a53d1c9fc4b5633bab768b393c663289687a9d48b74f12e961b8a0fe032973 +size 128804 diff --git a/docs/tutorials/external-events/associating-derivation-groups.mdx b/docs/tutorials/external-events/associating-derivation-groups.mdx new file mode 100644 index 0000000..5a70c2d --- /dev/null +++ b/docs/tutorials/external-events/associating-derivation-groups.mdx @@ -0,0 +1,129 @@ +import externalEventsTutorialAddingRowStep1 from './assets/external_events_tutorial_adding_row_step1.png'; +import externalEventsTutorialAddingRowStep2 from './assets/external_events_tutorial_adding_row_step2.png'; +import externalEventsTutorialAddingRowStep3 from './assets/external_events_tutorial_adding_row_step3.png'; +import externalEventsTutorialPlanPage from './assets/external_events_tutorial_plan_page.png'; +import externalEventsTutorialPlanParameters from './assets/external_events_tutorial_plan_parameters.png'; +import externalEventsTutorialPlanSpecificIntroPage from './assets/external_events_tutorial_plan_specific_intro_page.png'; +import externalEventsTutorialExternalSourcesEmpty from './assets/external_events_tutorial_external_sources_empty.png'; +import externalEventsTutorialManageDerivationGroupsModal from './assets/external_events_tutorial_manage_derivation_groups_modal.png'; +import externalEventsTutorialNewAssocation from './assets/external_events_tutorial_new_association.png'; +import externalEventsTutorialOpeningRowSettings from './assets/external_events_tutorial_opening_row_settings.png'; +import externalEventsTutorialOpeningEditRow from './assets/external_events_tutorial_opening_edit_row.png'; +import externalEventsTutorialTimelineEditor from './assets/external_events_tutorial_timeline_editor.png'; +import externalEventsTutorialFilterShown from './assets/external_events_tutorial_filter_shown.png'; + +# Associating the Derivation Group with a Plan +Now that we have some External Sources uploaded, we can utilize them within a plan to see them on a timeline (and in the future, use them to power constraints, dictate scheduling goals, etc.). + +## Creating a Plan +Start by going to the Aerie **Plan** page: + +
+ The Aerie plan page +
+ +Once there, create a new plan with the following parameters: + +
+ The example plan's parameters +
Note: The start and end times are important here, as they are bounds that contain all the external events in the sources we uploaded!
+
+ +To create this plan, make sure that there exists _some_ mission model that can be associated with the plan. The exact model is, at present, entirely unimportant as it has no bearing on External Events functionality. The mission model used here, arbitrarily, is that of Aerie's mission model template. + +After the plan has been created, select the plan on the table to the right, and then select **Open plan** in the pane on the left. You should be presented with a plan view that resembles the image below: + +
+ The plans page showing an empty timeline +
+ +Select the `External Sources` tab on the left, and you should see the following: + +
+ External Sources pane with no associations +
+ +This panel tells us that there are no derivation groups currently linked to our plan, meaning the external events we uploaded before are not yet associated with it. + +## Associating the Derivation Group +There are currently no Derivation Groups associated with this plan! While we should have one created, there aren't any that this plan is aware of. To change this, we need to click `Manage Derivation Groups`, to open the Derivation Group management modal. + +Once here, we can now look at all of our available (currently only one) Derivation Groups and select which ones to associate with our plan. Association implies that the plan or at least the plan page is in some way aware of the fact that this Derivation Group exists (details on what exactly association entails can be found [here](../../../planning/external-events/#derivation-group-management-modal) under 'Derivation Group Management Modal'). + +In the `Manage Derivation Groups` modal, check the check-box for our Derivation Group (`DemoType Default`). The check-box itself does not do anything yet, it requires the `Update` button at the bottom of the modal to be clicked to 'save' the linked/un-linked derivation groups. + +Click the `Update` button to link the derivation group. + +The modal should now appear as below, with a success toast in the bottom-right corner of the screen: + +
+ The Manage Derivation Groups modal after the Derivation Group has been associated +
+ +Leaving this modal, it should now be present in the `External Sources` tab on the left. + +
+ Plan view after the Derivation Group has been associated +
+ +On the left-pane, we can see the breakdown of External Event Counts - where the Derivation Group is shown to have **4 derived events** which come from the two sources, `External_Events_Demo_00.json` and `External_Events_Demo_01.json`, that both have **3 raw events** (or, un-derived. The External Event counts on External Sources represent the amount of present in the file itself, with no derivation or filtering applied). + +## Creating an External Event timeline row +Now that we have a derivation group associated with our plan, we can put those external events on the timeline to visualize them. + +By default, a dedicated 'External Events Row' is **not** created *unless* the user loads a plan that already existed and has at least one derivation group previously linked. In our case, because this is a new plan we must create our own row to see the events. Alternatively, a filter for the event types can also be added to a pre-existing row. + +First, switch to the `Activity, Resource, & Event Types` tab. + +
+ Switch to the 'Activity, Resource, & Event Types' tab +
Switch to the 'Activity, Resource, & Event Types'
+
+ +Click on the `Events` tab in the pane. The external event types from the example events should appear inside of the pane - these can be dragged to pre-existing rows to add as a filter, or by using the `+` icon when hovering over the type entry. + +For this tutorial, we'll create a new row entirely. We can expedite the process by using the `Add Filter to Row` button at the top of the pane, and then clicking the `New Row +` button at the bottom of the list. This will create a new row, with all available external event types included. + +
+ Click 'Add Filter to Row' and then 'New Row +' +
Click 'Add Filer to Row' and then 'New Row +'
+
+ +We can now see our example events on the timeline! There are 4 **derived** events shown, these represent the set of events that are *derived* from all the sources that exist within the derivation group. + +
+ External Events Row +
External Events Row
+
+ +In the next section, we'll look at the options available when editing a layer on the timeline. + +## Editing the External Event timeline layer +Clicking the three dots on the bottom right of the layer and then clicking **Edit Row** will bring up the layer timeline editor: + +
+ Opening the layer row settings +
Click the three dots
+
+ +
+ Opening the layer 'Edit Row' option +
Click 'Edit Row'
+
+ +
+ The Timeline Editor panel +
Timeline Editor for the external events row displayed in the right panel
+
+ +External events appear in the same layer type as activities, and as such share options with them inside of the timeline row editor. + +[//]: # (There is a single option that is specific to external events: `Group By`. This allows the user to display the external events either as being grouped underneath the their respective external sources, or grouped underneath their respective external event types.) + +[//]: # (Additionally, there is an option for external events on the timeline that doesn't appear underneath the timeline editor: enabling/disabling visibility. This allows the user to hide (or un-hide) derivation groups from being drawn on the timeline irrespective of what row or layer they appear on. More information can be found under the [Plan](../../../planning/external-events/#plan) section of the main External Events documentation.) + +[//]: # (Examples of the two different `Group By` modes, as well as visibility enable/disable can be seen in the [Plan](../../../planning/external-events/#plan) section of the main External Events documentation.) + +## Additional Resources + +More detail on the topics discussed in this tutorial can be found under [External Events](../../../planning/external-events) diff --git a/docs/tutorials/external-events/creating-an-external-source.mdx b/docs/tutorials/external-events/creating-an-external-source.mdx new file mode 100644 index 0000000..4a150da --- /dev/null +++ b/docs/tutorials/external-events/creating-an-external-source.mdx @@ -0,0 +1,95 @@ +import externalEventsOverlappingSources from './assets/external_events_overlapping_sources.png'; + +# Creating an External Source +We are going to manually create two External Sources and upload them to Aerie. They will be slightly staggered in the times they cover to help us later in illustrating how derivation works. + +
+ Diagram of the two source's overlapping time ranges +
Diagram of the two source's overlapping time ranges
+
+ +Create the following JSON files in an editor: + +`External_Events_Demo_00.json`: +``` +{ + "source": { + "key": "External_Events_Demo_00.json", + "source_type": "DemoType", + "valid_at": "2024-01-01T00:00:00Z", + "period": { + "start_time": "2026-001T00:00:00Z", + "end_time": "2026-007T00:00:00Z" + } + }, + "events": [ + { + "key": "DemoType/SampleTypeA/1", + "event_type": "SampleTypeA", + "start_time": "2026-001T12:00:00Z", + "duration": "02:00:00" + }, + + { + "key": "DemoType/SampleTypeA/2", + "event_type": "SampleTypeA", + "start_time": "2026-002T00:00:00Z", + "duration": "01:00:00" + }, + + { + "key": "DemoType/SampleTypeA/3", + "event_type": "SampleTypeA", + "start_time": "2026-003T12:00:00Z", + "duration": "03:00:00" + } + ] +} +``` + +`External_Events_Demo_01.json`: +``` +{ + "source": { + "key": "External_Events_Demo_01.json", + "source_type": "DemoType", + "valid_at": "2024-01-02T00:00:00Z", + "period": { + "start_time": "2026-003T00:00:00Z", + "end_time": "2026-010T00:00:00Z" + } + }, + "events": [ + { + "key": "DemoType/SampleTypeA/1", + "event_type": "SampleTypeA", + "start_time": "2026-003T20:00:00Z", + "duration": "02:00:00" + }, + + { + "key": "DemoType/SampleTypeA/3", + "event_type": "SampleTypeB", + "start_time": "2026-004T12:00:00Z", + "duration": "01:00:00" + }, + + { + "key": "DemoType/SampleTypeA/4", + "event_type": "SampleTypeB", + "start_time": "2026-009T20:00:00Z", + "duration": "03:00:00" + } + ] +} +``` + +We are now ready to upload our test External Source files to Aerie! + +:::info Note + +In each of these files, the exact formatting of event keys is currently not important. + +::: + +More details can be found in the [External Events](../../../planning/external-events/) section. diff --git a/docs/tutorials/external-events/introduction.mdx b/docs/tutorials/external-events/introduction.mdx new file mode 100644 index 0000000..133f351 --- /dev/null +++ b/docs/tutorials/external-events/introduction.mdx @@ -0,0 +1,11 @@ +# External Events Tutorial + +In this tutorial, we will provide a brief overview of External Events in Aerie in a walkthrough format. Extensive details on what External Events, External Sources, and Derivation Groups are can be found under at [External Events planning](../../../planning/external-events) section. + +## Prerequisites + +External events are a component similar to Activities and Resources within Aerie, and as such requires a deployment of Aerie. Additionally, to interact with the external events in a plan's context, a mission model must be created (though as of now, there is no connection between anything related to external events and mission models, so any mission model should be fine). + +You can deploy Aerie locally on your machine by following the simple steps outlined in our [Fast Track](../../../introduction/#fast-track) instructions. + +After you've confirmed the Aerie UI is available on [http://localhost/](http://localhost) and a mission model has been uploaded, you should be ready to proceed with this tutorial. diff --git a/docs/tutorials/external-events/uploading-an-external-source.mdx b/docs/tutorials/external-events/uploading-an-external-source.mdx new file mode 100644 index 0000000..e43bf84 --- /dev/null +++ b/docs/tutorials/external-events/uploading-an-external-source.mdx @@ -0,0 +1,38 @@ +import externalEventsTutorialUploadStep1 from './assets/external_events_tutorial_upload_step1.png'; +import externalEventsTutorialUploadStep2 from './assets/external_events_tutorial_upload_step2.png'; +import externalEventsTutorialUploadStep3 from './assets/external_events_tutorial_upload_step3.png'; +import externalEventsTutorialUploadStep4 from './assets/external_events_tutorial_upload_step4.png'; +import externalEventsTutorialUploadStep5Timeline from './assets/external_events_tutorial_upload_step5_timeline.png'; +import externalEventsTutorialUploadStep5Table from './assets/external_events_tutorial_upload_step5_table.png'; + +# Uploading the External Source +Having created our sources, we are now able to upload them. Assuming you have deployed an instance of Aerie, navigate to the External Sources page: + +
+ Click 'External Sources' button +
+ +Once here, we can now upload our new External Sources. Click the **'Browse...'** button, and select the first file, `External_Events_Demo_00.json`. The upload section should autofill as follows: + +
+ Click the 'Browse...' button and select the first test file - uploaded file form should become populated +
Uploaded file form should become populated
+
+ +Go ahead and leave the `Derivation Group` as `DemoType Default`. + +Finally, click upload. The new External Source should show in the table on the right: + +
+ External Sources table is populated +
+ +Click the 'x' next to 'Selected External Source' to deselect it, then repeat these steps with the second file. The table should now look as follows: + +
+ External Sources table is populated with both test files +
+ +We can now see both external sources we've uploaded in the top-right table, and the external events of the selected source (in this case, the 2nd example file as it's the last we uploaded) in the bottom-right table. + +We are now ready to associate our new Derivation Group (`DemoType Default`) with a plan! diff --git a/sidebars.js b/sidebars.js index 185aff8..828fbf2 100644 --- a/sidebars.js +++ b/sidebars.js @@ -71,6 +71,19 @@ const sidebars = { 'tutorials/mission-modeling/simulation-config', ], }, + { + type: 'category', + label: 'External Events', + link: { + id: 'tutorials/external-events/introduction', + type: 'doc', + }, + items: [ + 'tutorials/external-events/creating-an-external-source', + 'tutorials/external-events/uploading-an-external-source', + 'tutorials/external-events/associating-derivation-groups', + ], + }, ], }, { @@ -142,6 +155,7 @@ const sidebars = { 'planning/create-plan-and-simulate', 'planning/external-datasets', 'planning/activity-directive-metadata', + 'planning/external-events', { type: 'category', label: 'Collaboration',