####################################################### Events overview and event-based segment generation tool ####################################################### Overview ======== The Events overview and event-based segment generation tool (EOE) is a very powerful tool to analyze the distribution and the geometry of events (Flybys, Transits and Earth, Stellar and Sun Occultations) in order to generate opportunity segments. Context ======= EOE is part of The Events and Segments Visualisation and Coverage Tool (ESVCT) suite that consists of three complementary tools that support the science segmentation of the Jupiter Tour. In this context these tools are a perfect complement to the `JUICE SOC Timeline tool `_. The three tools are briefly described hereunder. :ref:`30_event_tool:Events overview and event-based segment generation tool`: Analyze the distribution of events (Flybys, Transits and Earth, Stellar and Sun Occultations) in the geometry space of interest; select the most interesting ones and create the corresponding opportunity segments outputs. :ref:`32_opportunity_segments:Opportunity segments coverage tool`: Analyze the coverage of opportunity segments in the geometry space of interest within a selected time window. Identify the most relevant ones to export and use it in the timeline tool. :ref:`33_segmentation_coverage:Segmentation coverage tool`: Explore the coverage of a given segmentation in the geometry space of interest and compare it to theoretical opportunities. Tool Audience ============= The main audience of ESVCT are the SOC Operations Scientists, the Working Groups leads and the Instrument Teams scientists involved in the trajectory science segmentation. The Operations Scientists serve as first users of the functionalities developed by the SOC such as the ESVCT. Accessibility ============= The Events overview tool is accessible from the `JUICE SOC Website `_ in ``Science Operations Planning Tools > Science Opportunity Analysis > Events Overview and Segment Coverage Tools``. This takes you to the `Events and Segments Visualization and Coverage Tool `_ and then you need to select the Crema instance of the ``Events overview and event-based segment generation tool``. E.g.: `Crema 5.0 `_. Geometrical Events ================== Concept ------- An event is a time window over which certain geometric conditions are met. Most geometry computations performed involve calculating quantities of interest -- such as distances, vectors, angles, or orientations -- for specified times. When calculating events the inverse problem is solved: find times when specified geometric conditions are met. An event can be instantaneous, such as an observer attaining its minimum distance to a target, or it can have finite duration -- and therefore define a time window, or interval -- as does an occultation. EOE displays all events as instantaneous: for events with finite duration such as an occultation or a transit it provides the "start" and the "end" events as different instantaneous events. Visualizing the Events ---------------------- EOE allows you to visualize and analyze a number of events by providing you access to a the events pre-computed in a database for a given Crema. Each event can have different **targets**, a number of **geometrical criteria** associated to them, and different **geometrical quantities** that can be displayed on a plot. The geometrical criteria are used to filter a given event, e.g.: we want to see the Earth Occultations by Callisto between to dates (``occultation calendar time (occ_utc_cal)``) and for a given sub-spacecraft latitude range (``ssc point longitude (ssc_lon)``). The geometrical quantities for plots can be the Occultation time (``occultation ephemeris time``) for the X axis, the distance between JUICE and the point at the occulting body limb (``distance``) for the Y axis, and the distance to Earth (``distance to Earth``) for the Color Serie. Available Events ---------------- The currently available events are: * Earth Occultations * Transits * Stellar Occultations * Flybys * Perijoves and Apojoves * Sun Occultations The following sections describe the available events with further detail and provides the description of some of the particularities of each event. Some descriptions involve how events are displayed in the :ref:`30_event_tool:Event Geometry Plots`. Earth Occultations ------------------ Earth occultation by one of the jovian system major bodies: Jupiter, Io, Callisto, Europa or Ganymede as seen from the JUICE s/c. When Earth occultations event are selected, you need to choose one of the occulting bodies; the equirectangular map will be set to the occulting body and will display the occultation ingress (blue triangle) and egress (orange circle) surface points. Transits -------- Transit of an occulted body by an occulting body as seen from the JUICE s/c. The body can be one of the jovian system major bodies: Jupiter, Io, Callisto, Europa or Ganymede. In the table that lists events, the occulted (back) and occulting (front) bodies are added to the available columns. Stellar Occultations -------------------- Stellar occultation by one of the jovian system major bodies: Jupiter, Io, Callisto, Europa or Ganymede as seen from the JUICE s/c. The available stellar occultations are defined by a star catalog provided by the JUICE UVS team. The names are from the Henry Daper catalog. The catalogue with star names and coordinates is available for the JUICE SOC at the `JUICE Gitlab conf repository `_. When Stellar occultations event are selected, you need to choose one of the occulting bodies; the equirectangular map will be set to the occulting body and will display the occultation ingress (blue triangle) and egress (orange circle) surface points. Flybys ------ Flyby is the closest approach of JUICE with respect to a target body over a specified time window. These time windows are defined in such a way that all the relevant flybys are considered. The targets are the jovian system major bodies: Jupiter (``jupiter_ca`` Type in the Event table), Io, Callisto, Europa, and Ganymede, and all available Jovian Inner and Irregular Satellites (``peri`` Type in the Event table). The complete list of jovian system minor bodies is available at the `SPICE JUICE Science Frames Kernel `_. For convenience, Flybys also include the Jupiter far approaches or apocenter events (``jupiter_fa`` Type in the Event table) and the Ganymede apocenter events (``apo`` Type in the Event table), further distance to Ganymede per orbit, useful during the Ganymede phase. In the equirectangular map and in the plot, moons closest approaches (``peri`` Type in the Event table) are considered **ingress** events whereas The Ganymede apocenter event (``apo``) and the Jupiter Closest and Far approach events (``jupiter_ca`` and ``jupiter_fa``) are considered egress events. Perijoves/Apojoves ------------------ Peijoves are the point in the orbit of JUICE s/c nearest the Jupiter's center and Apojoves the further point in the orbit. Perijoves are numbered: ``1PJ``, ``1AP``, ``2PJ``, etc., as described in the ``Target`` column of the Event table. Perijoves are considered ingress events in the plots and apojoves egress events. Sun Occultations ---------------- Sun occultation by one of the jovian system major bodies: Jupiter, Io, Callisto, Europa or Ganymede as seen from the JUICE s/c. User Interface ============== EOE consists of a top bar and an event display dashboard with three columns. A timeline table at the bottom can be displayed by clicking the top level bar button ``Show Timeline``. This table provides events and the segmentation of a chosen segmentation plan. These elements are described in detail hereunder. Top bar ------- The top bar is divided in three sections. From left to right, the first section provides information of the Crema version, the selected event being displayed, and the event target(s). The next element is the ``Show timeline`` button that allows you to show/hide the timeline at the bottom. Finally the last element are the buttons to select the event type that will be displayed in the tool. A target always has to be chosen although some only have one option (``All``). In addition the ``saturn`` left most icon of the top bar takes you back to the ESVCT suite tool selection menu. Event Display Dashboard ----------------------- The event display dashboard is the central element of the tool and consists of three different columns. The left column is to **filter events**, the central column **event geometry plots** in a equirectangular map projection and in a plot window, the right column **lists events, controls their exports, and controls the plots**. Filter Menu ^^^^^^^^^^^ This menu allows you to filter the events by different criteria, the criteria is defined by a geometrical parameter associated to the different events that you can select from the top drop down menu. When doing so you will have a number of options with a name and a mnemonic in parenthesis. If you want to know more information about a specific parameter choose it and a text description wil appear at the bottom of the criteria. For example, if you choose the Sun Occultation events, you can choose the ``angle sc-body sc-jupiter (sc2body_sc2jup_angle)`` parameter which will provide the following description:: [number] angle between the directions spacecraft-to-occulting body and spacecraft-to-jupiter (deg) The first word in brackets is the field type and tells us that this parameter is a number quantity and the last word in parenthesis tells us the units. The possible field type values are: ``text``, ``number``, and ``blob``. A ``blob`` can be considered a "vectorial" value, or a value with more than one element. After the parameter is selected we can choose the relationship and the value to filter the event. The list of operators for numerical parameters are: * ``is_null`` * ``is_not_null`` * ``==``, Equal (eq) * ``!=``, Not Equal (ne) * ``>``, Greater than (gt) * ``<``, Less than (lt) * ``>=``, Greater or equal (ge) * ``<=``, Less or equal (le) * ``like`` * ``ilike`` * ``not_ilike`` * ``in`` * ``not_in`` * ``any`` * ``not_any`` For example, if we choose to filter the Sun Occultations by ``occultation type (evt_type)`` and set it ``==`` to ``TRANSIT_END`` to only see the sun occultation egress events. Please note that for example one can derive the value to be used for ``occultation type (evt_type)`` by looking the Event List table ``Type`` column or by deriving it from the parameter description which in this case is: ``Egress (TRANSIT_END) or ingress (TRANSIT_START) occultation``. Advanced filters can be applied by choosing the ``Advanced`` tab, as opposed to the ``Simple`` tab. When applying a filter from the ``Simple`` tab, it will be made available in the ``Advanced`` tab as well. You can use the advanced filters following the indications hereunder. Filters must be provided in a list and will be applied sequentially. Each filter will be a dictionary element in that list, using the following format:: filter_spec = [ { 'field': 'field_name', 'op': '==', 'value': 'field_value' } , { 'field': 'field_2_name', 'op': '!=', 'value': 'field_2_value' } , # ... ] Where field is the name of the field that will be filtered using the operator provided in ``op`` (optional, defaults to ``==``) and the provided value (optional, depending on the operator). The list of operators that can be used is the same as described above. Boolean Functions: and, or, and not functions can be used and nested within the filter specification:: { 'or': [ { 'and': [ { 'field': 'field_name', 'op': '==', 'value': 'field_value'} , { 'field': 'field_2_name', 'op': '!=', 'value': 'field_2_value'} , ] } , { 'not': [ { 'field': 'field_3_name', 'op': '==', 'value': 'field_3_value'} ] } , ], } The list of available geometrical parameters for the events filter criteria is provided in the sections provided hereunder: - :ref:`31_event_parameters:Earth Occultations` - :ref:`31_event_parameters:Transits` - :ref:`31_event_parameters:Stellar Occultations` - :ref:`31_event_parameters:Flybys` - :ref:`31_event_parameters:Perijoves/Apojoves` - :ref:`31_event_parameters:Sun Occultations` The parameters are also available to private users in the configuration files of the `JUICE SciGit conf repository `_. Event Geometry Plots ^^^^^^^^^^^^^^^^^^^^ The center of the dashboard has two different plots: a equirectangular map projection at the top and in a plot window in the bottom. The equirectangular map provides the latitude and longitude coordinates of a relevant quantity associated with the event as follows: * Earth Occultations ``occulted point latitude/longitude``: Lat/Lon of the occulted point (in the IAU body-fixed reference frame), direction of increasing longitude toward the East (deg). * Transits ``ssc latitude/longitude at Jupiter``: Lat/Lon of the sub-spacecraft point at the occulting body (deg). * Stellar Occultations ``occulted point lat/lon``: Lat/Lon of the occulted point (in the IAU body-fixed reference frame), direction of increasing longitude toward the East (deg). * Flybys ``latitude/longitude``: Sub-spacecraft lat/lon at the flyby epoch on the target (in the IAU body-fixed reference frame), direction of increasing longitude toward the East (deg). * Perijoves and Apojoves ``latitude/longitude``: Sub-spacecraft lat/lon (in the Jupiter IAU body-fixed reference frame), direction of increasing longitude toward the East (deg). * Sun Occultations ``occulted point latitude/longitude``: Sub-spacecraft point lat/lon at occulting body (in the IAU body-fixed reference frame), direction of increasing longitude toward the East (deg). The Plot at the bottom is able to display different geometrical quantities depending on the event, the X axis, Y axis, and Color Series values can be controlled from the bottom box of the right column of the dashboard with the ``X Serie``, ``Y Serie``, and ``Color Serie`` drop down menus. When a quantity is chosen, its description is displayed at the bottom of its drop down menu. The available geometrical parameters correspond to the ones that are eligible from the :ref:`30_event_tool:Filter Menu` on the left that have a ``[number]`` field type. These can be checked per event on :ref:`30_event_tool:Event Parameters`. or on the private user files of the `JUICE SciGit conf repository `_. Both the map and the plot are interactive as per the functionalities provided by the package in use, Plotly. This interactive capabilities are important because they allow you to choose events from the plots and from the map that allows you to better contextualize them with the geometrical parameters of interest. When hoovering the mouse over both the map and the plot, a number of icons will appear on the top right section of the plot with the following actions: * Download plot as png ``camera`` icon: Download the plot. * Zoom ``magnifying glass`` icon: Zoom the plot with a box. * Pan ``Cross arrow`` icon: Pan through the plot. * Box select ``dashed square`` icon: Select the events inside a box. * Lasso select ``lasso`` icon: Select the events inside the lasso. * Reset axes ``home`` icon: Reset a zoomed and/or panned plot view. * Deselect ``crossed box`` icon: Deselect all selected events. These actions are triggered with a left click with the mouse. The selection and deselection actions are important because are interlinked with the :ref:`30_event_tool:Event List Table`. Also when you hoover your mouse over events, the event id (see :ref:`30_event_tool:Event List Table`) and the X and and Y series value will be displayed. About Coordinate Systems and Reference Frames ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For all cases coordinates are in the latitudinal or planetocentric coordinate system, with a spheroidal model of Jupiter and unless indicated contrarily all reference frame used are IAU body-fixed reference frames based on the SPICE Planetary Constants Kernel in use, as available from the `JUICE SPICE repository `_. Event List and Controls ----------------------- The right most column of the dashboard consists of three different windows. The first window is a table that lists all the events, the second window allows you to export events, and the third window is the plot control window. The plot control window is described in :ref:`30_event_tool:Event Geometry Plots` whereas the other windows are described hereunder. Event List Table ^^^^^^^^^^^^^^^^ The Event List Table lists the events of the selected type. It can list all the events or the ones filtered with the :ref:`30_event_tool:Filter Menu`. The event list has six columns: * Id: Is the event id and corresponds to the id that is displayed in the central column plots. * To be Exported: Indicates whether if the event is selected to be Exported by the Export Window. * Date: Provides the date of the event in UTC calendar format. * Target: Indicates the event target. The target is different for each event and is further explained in :ref:`30_event_tool:Geometrical Events`. * Type: Indicates the event type within the events being displayed. For Example for Perijoves/Apojoves it can be either, for transits it can be a transit start or transit end, for a flyby it can be the closest approach or the further approach, etc. * Display: Some events have the option to be visualized with the **Pointing Tool**. This is a **very powerful tool** that starts the Pointing Tool at the time of the event with default attitude and for an interval of 60 seconds. .. note:: The **Pointing Tool** display for **Sun Occultations** provides the S/C-Sun direction with the default pointing; it is recommended to use the Spacecraft View option. The display for **Earth Occultations** Sun Occultations and Earth Occultations. The reason is because the principal axis of these observations is not the +Z S/C axis but rather the -X axis of the S/C and the Pointing Tool cannot accomodate these axis for visualization. The event list is complemented by an ``Unmark all`` button at the top that deselects all the events and an event count at the bottom of the table (``Total``) that indicates the number of events or the ones present after filtering them. Export Window ^^^^^^^^^^^^^ Allows you to export the selected events. The selected events are indicated by a green tick in the ``To Be Exported`` column of the Event List Table. When at least one event is selected there are two export options (green buttons): * ``Timeline Tool Export``: Exports the events in a JSON file with a format that is loadable by the JUICE SOC Timeline Tool. This file can then be loaded in a timeline of the Timeline Tool. The generated filename is ``segments_YYYY-MM-DDTHH_MM_SS.json`` * ``CSV Export``: Exports the events in a CSV table. The generated filename is ``events_YYYY-MM-DDTHH_MM_SS.csv``. The JSON file events have the following format:: { "creationDate": "2022-08-21T20:44:40.262Z", "name": "Export 2022-08-21T20:44:40.262Z", "segments": [ { "start": "2031-01-20T07:44:35.000Z", "end": "2031-01-20T09:44:35.000Z", "segment_definition": "TRANSIT_ET", "name": "TRANSIT_ET_3134", "overwritten": false, "timeline": "LOCAL", "source": "GENERIC", "resources": [] } ], "segmentGroups": [], "trajectory": "CREMA_5_0", "localStoragePk": "segmentation-1661114680262" } whereas the CSV file have a simplified one:: 3134,TRANSIT_START,2031-01-20T08:44:35.000Z For the Timeline Tool JSON exports, you can choose the Delta for the event Start and End times. The ``Delta Time Start`` is a negative delta to the event (by default is 1 hour), the ``Delta Time End`` is a positive delta to the event (by default is 1 hour). By default the exported events will become segments with a duration of 2 hours with the event at the center of the segment. Timeline Table -------------- The Timeline Table is activated by clicking on the ``Show Timeline`` button of the top bar. The Timeline table allows you to load a Segmentation plan and display it along with all the events of the event type being visualized. Only the Prime timeline of the segmentation plan is displayed. The Science Segmentations plans are available from the `Timeline tool `_ and also from the `JUICE Core System Plan Database `_. Please note that both only the public segmentation plans are available. The table header indicates the epoch, the second row displays the events and the third row the segmentation. You can pan the table left to right to move across time. The events are displayed as circles and have a label with the event target and event id, an example for each event is provided hereunder: * Earth Occultations e.g.: ``CALLISTO 1`` * Transits e.g.: ``io 3866`` * Stellar e.g.: ``HD116658 1`` * Flybys e.g.: ``amalthea 4`` * Perijoves/Apojoves e.g.: ``1PJ 1`` * Sun Occultations e.g.: ``jupiter 66`` If you double click an event in the Event List Table, the Timeline Table will be automatically moved to the event epoch. When a segmentation plan is loaded it can be cleared with the red ``Clean`` button. Working with EOE ================ Getting Started --------------- When EOE is started the default event displayed are the Stellar Occultations by Europa. Quick Guide ----------- During the segmentation harmonization process, you should **visualize the relevant event type** (e.g. solar occultation) and select the ones that provides the best geometry conditions: Geometry conditions associated to each event occurrence can be displayed (lower right panel for plot selection) and box selection allows to limit the selection to the occurrences of interest. The filtered selection is reflected on the upper right panel. Alternatively, the user can select filtering criteria for the relevant even* type on the left panel using filters conditions (each computed fields can be selected). Within the resulting plot, box selection allows to limit the selection to the occurrences of interest. The filtered selection is reflected on the upper right panel. Pointing display of each event can be done through direct link to the pointing tool. The user can **display the event occurrences of interest** on top of the segmentation timeline to check for overlaps with prime segments to refine his/her selection further. The user can then select a delta time around the event of interest and **export either the event list with associated time, or the created segments (JSON export)** to be ingested in the timeline tool. Selecting Events ---------------- An important feature of EOE is the ability to select a number of events to be displayed/exported. This selection is interactive and interlinked in between the central plots and the Event List Table on the right. Firstly it is important to distinguish in between a *marked* and a *selected* event. *Marked* events are events to be exported while *selected* events are highlighted in the Event List Table. You can select events from the Event List Table with a left click with the mouse. When doing so, the event will be highlighted in blue in the table and it will become the only event shown in the plots. You can then select more events in the event list and one by one they will be highlighted and shown in the plots. You can unselect an event from the Event Table List by right clicking on it again. Although these events are selected, they are not *marked*, *marked* events are those that are selected in the ``To Be Exported`` column of the Event List Table Marking an event (left click on the red X icon for it to become a green tick) does not *select* it to be visualized in the plots or highlighted in the table. Marked events can be unmarked by clicking on the ``Unmark all`` button on top of the Event List Table. You can also mark one or multiple events from the plots by using the ``Box Select`` and ``Lasso Select`` options. When doing so is best to have all the events available, regardless of if events have already been selected from the event list or not. To unselect all the events in the plots -- but not in the Event List Table --, you can click the ``Deselect`` button on either plot. Afterwards you can either use the lasso or the box tool to mark a number of events. A message will be displayed for you to confirm the event selection, these will be added to the already marked events in the Event List Table (if events had been marked). When you do so, only the marked events will be visible in the plots. By default no event is selected. Currently there is no way to *unselect* all selected events, you need to do so by cliking them on the Event List Table one by one. If you want to select all the events the best option is to select them from the plot as there is no "Mark all" option in the Event List Table. Finally, if you double click an event in the Event List Table, the Timeline Table will be automatically moved to the event epoch. References ========== Associated SOC Use Cases ------------------------ These SOC Use Cases might not be available if you do not have a JUICE Confluence account. * `UC-24: Top level Harmonize Segmentation `_: Procedure for SOC to iterate a segmentation with PIs, includes brief instructions on how to use EOE. * `UC-22_3: Top level Create Review and Update Event-Tool Event Parameters `_: Procedure to create and update the event parameters for EVT. Event Parameters ================ .. include:: 31_event_parameters.rst