################# The Timeline Tool ################# The Timeline Tool, also known as Segment Harmonization Tool (SHT) is a web-based tool supporting the collaborative and assisted creation of the **science segmentation** of a JUICE trajectory. If you want to start using the SHT you can jump directly to :ref:`20_timeline_tool:Working with SHT`. Overview ======== The Timeline Tool is intended to support the strategic science planning which encompasses all the activities of segmenting the Jupiter Tour to define time windows -- segments -- where the conditions for specific science objectives are met with the ultimate goal to elaborate a segmentation plan. This analysis is performed by the JUICE Science Operations Center (SOC), the Science Working Groups (WGs), and the instrument teams. The Segmentation Process ------------------------ The Science Working Team (SWT) and Project Scientist (PS) mandate the WGs and the SOC to propose a trajectory science segmentation for the Jupiter Tour. The high-level definition of science objectives and campaigns is defined by the WGs. The computation of segment opportunities and first instantiation is then performed by the SOC, including the required operational segments (such as TCMs, WOLs and NAVCAM observations slots for navigation and ephemeris refinement) and the operational applicable constraints, defining the operational segments. Segment opportunities can also be provided by the working groups in absolute time, when not computed by the SOC. The harmonization of the science segments is performed by the WGs following the SOC coordination, under supervision of the SWT and PS. When deemed necessary, detailed operational analysis of specific segments are implemented; the detailed knowledge gained from the detailed analysis is fed back into the high-level segmentation harmonization. The incremental operational realism of the trajectory segmentation and supporting detailed scenario gradually build the Science Activity Plan of the mission’s science phase. Ultimately the segmentation plan is a number of continuous segments with full coverage that divide the JUICE Jupiter Tour by science objectives. Tool Audience ------------- The main audience of SHT are the SOC Operations Scientists, the WGs leads and the IT scientists involved in the trajectory science segmentation. The Operations Scientists serve as first users of the functionalities developed by the SOC such as the SHT. Accessibility ============= The SHT is accessible from the `JUICE SOC Website `_ in ``Science Operations Planning Tools > Trajectories > Crema X Y > Timeline``. It is also available at the `JUICE Core System Toolkit `_ menu in the ``Timeline`` panel. There is an instance available for each JUICE candidate trajectory (Crema). Each instance has a unique link, e.g.: `Crema 5.0 `_ The value of the crema can be easily changed in the URL to change the SHT instance. The Timeline tool is public or it can be accessed with a private user provided by the SOC. Not all the functionalities and Plans are publicly available. This manual provides information on the differences in between the public and "private" features. If you need to have a private user of the SHT please contact the JUICE SOC. User interface ============== The SHT user interface is divided in a top horizontal menu bars, a left vertical menu and the timeline dashboard. These elements and their functionalities are described hereunder. Timeline Dashboard ------------------ The timeline dashboard is the central part of the SHT and consists of a dynamic table. This table is divided in dynamic columns that correspond to a time axis or a timeline, the granularity of which -- years, months, days, etc. -- depends on the zoom specified by the user and a number of rows that contain different types of time windows -- or time intervals. These time windows can be geometric, science or operational events, segments or observations. In general, we call them segments. The available timelines are: * Prime * Generic * Working Group 1 * Working Group 2 * Working Group 3 * Working Group 4 * Working Group X * Local * Sandbox * Instrument timeline (one per "instrument") The Prime Timeline is the resulting segmentation plan of the segmentation process while the other timelines provide the opportunities grouped by their specific science domain. These timelines can also be used for practical reasons during the development of a segmentation and can also be used to account for rider science objectives. The timelines are accessible for private users from the `JUICE Core System Configuration Database Timelines `_ Within a timeline segments can have different sources. These sources describe the working group or science domain originator of the segment. Dashboard Controls ^^^^^^^^^^^^^^^^^^ The following actions are available in the SHT dashboard: * **Zoom in/out**: Use the mouse scroll functionality from left to right or bottom to top to zoom in the dashboard and change the time horizontal axis. * **Pan left/right**: Left click the mouse and move it left/right to move across the time horizontal axis. * **Create a segment**: Double left click the mouse to create a segment. The "Create Segment" window will appear. More details in :ref:`20_timeline_tool:Working with Segments`. * **Segment name**: Hoover the mouse over a segment to display the segment mnemonic/name on the dashboard. * **Move a segment**: Single right click the mouse and drag the segment to move it around the horizontal axis of the dashboard. * **Select a segment**: Single left click the mouse on a segment to select it. A red ``X`` will appear with which you can delete the segment. * **Select multiple segments**: Press Command/Control and single left click the mouse on a multiple segments to select them. When doing so the top horizontal bar ``Group Segment`` option will appear. More details in :ref:`20_timeline_tool:Create a Segment Group`. * **Segment Context Menu**: Single right click the mouse on a segment to display a context menu with different options. More details in :ref:`20_timeline_tool:Working with Segments`. * **Event Context Menu**: Single right click the mouse on an event to display a context menu. The "Display Info" will provide all the information available of the event. "Show in Graph" will draw to vertical lines in the Geometry Series of the SHT dashboard to display the event duration. Only one event can be displayed at a time. Sandbox Timeline ^^^^^^^^^^^^^^^^ The Sandbox timeline allows you to load a user-defined segmentation. The particularity of this timelines is that the segments present in the sandbox are for **visualization purposes only** and therefore they do not need to be segments defined in the database. These segments are mainly designed to validate segments from other timelines with user-defined "segments". This also implies that the sandbox timeline is not available for anything else within SHT and cannot be exported. Top Horizontal Bar ------------------ The **top horizontal bar** has two rows and provides a number of top-level functionalities for the segmentation process. The top upper bar provides the Crema version in use and if a Science Segmentation Plan is loaded with the :ref:`20_timeline_tool:Plans Database`, the name of the segmentation plan. In addition, it includes a compass icon that allows the user to download the Trajectory PTR in PTX format. Finally, there is a crank icon to include the :ref:`20_timeline_tool:Engineering Blocks` timeline. In addition, on the right you can sign-in with your user and access the SHT documentation (this documentation) with the ``interrogation`` icon. The top lower bar provides the following icons with different actions: * Clean all segments ``trash bin`` icon: Removes all the segments. * Verify ``checked case`` icon: Opens a window that reports the segmentation status, :ref:`20_timeline_tool:Verify`. * EPS Package ``checked case`` icon: Opens the :ref:`20_timeline_tool:EPS package` menu. * Generate Skeleton PTR ``compass`` icon: Opens the :ref:`20_timeline_tool:PTR generator` menu. * Group Segment ``squares`` icon: Present if a number of segments are selected from the dashboard; opens the Group Segment menu. * Calendar operations ``calendar`` icon: Opens the :ref:`20_timeline_tool:Calendar Operations` calendar. Some of the actions are described in detail hereunder. Engineering Blocks ^^^^^^^^^^^^^^^^^^ This is a special timeline with a trajectory dependant only "segmentation" or blocks that provide the power profiles that are later used by the EPS Package. These blocks containing the S/C "thermal" segments driving the geometrically dependent thermal components of the platform power for Flybys, Eclipses, etc. These blocks do not contain the power information of the Downlink or of the NAVCAMs. Verify ^^^^^^ The Verify window provides a report of the segmentation status. The report includes a "Summary" Section with the number of Segments, Groups, Gaps, and Overlaps, a "Source Distribution" that provides some time statistics of the distribution of segments per source (Generic, WG1, WG2, etc.), a "Segment Definition Distribution" thar provides the time allocated by segment type, and the "Scenario Detail Integrations". EPS Package ^^^^^^^^^^^ The EPS package generator menu allows to generate an EPS Package from the segmentation. There are four different tabs: All, Visible, Filter by phases, Filter by dates: * All: Export all contents without any time filtering * Visible: Export the contents **completely** visible in the current timeline. * Phases: Filter by mission phase. Mission phases depend on the trajectory in use (Crema) and their definitions are available for registered users in the `JUICE Core System Configuration Database Phases `_. Please note that Phases are also available from the Timeline Configuration and can be displayed in the SHT dashboard. * Date: Export the contents filtered by a start and finish date. You can also choose the timelines (groups) you want to export as defined in :ref:`20_timeline_tool:Timeline Dashboard`. When you Export the package a ``eps_package.zip`` is generated. More details on the EPS Package are provided in :ref:`23_eps_package:EPS package`. PTR Generator ^^^^^^^^^^^^^ The PTR generator menu allows you to generate a skeleton Planning Timeline Request XML file (PTR) from the segmentation. This PTR is generated based on the Pointing description of the segments present in the chosen timeline(s) and therefore Prime and Riders are taken into account. If a PTR snippet is not available for a given segment the default attitude provided by the trajectory PTR will be used. In addition, it is important to outline a number of rules that are followed for the generation of these skeleton PTRs which are as follows. The Skeleton PTR blocks include the following comments in the observation blocks meta-data: PRIME= RIDER= OBS_ID= OBS_NAME= where: * `prime_instrument` is the name of the observation's instrument * `list_of_riders` is a list of the instruments that are riding along the observation. They are listed with underscores, e.g.: JANUS_MAJIS_PEP * `obs_number` is the science observation number (count) within the PTR. * `obs_name` is the actual name of the observation for example: PRIME=JANUS RIDER=MAJIS_JMAG_PEP OBS_ID=002 OBS_NAME=JAN_POI In addition the Skeleton PTR follows these rules: * OBS blocks which are SOC Prime must include the start and stop times defined in the timeline * OBS blocks which are NOT SOC Prime must not include the stop time, and if they are preceded by a SOC Prime must not include the start time either. More details on PTR syntax are provided in :ref:`60_pointing_tool:JUICE Pointing Tool`. When the PTR generator menu appears, it provides four different tabs: All, Visible, Filter by phases, Filter by dates: * All: Export all contents without any time filtering * Visible: Export the contents **completely** visible in the current timeline. * Phases: Filter by mission phase. Mission phases depend on the trajectory in use (Crema) and their definitions are available for registered users in the `JUICE Core System Configuration Database `_. Please note that Phases are also available from the Timeline Configuration and can be displayed in the SHT dashboard. * Date: Export the contents filtered by a start and finish date. You can also choose the timelines (groups) you want to export as defined in :ref:`20_timeline_tool:Timeline Dashboard`. When you Export the PTR a ``ptr_skeleton_.xml`` file is generated, e.g.: ``ptr_skeleton_2023-08-28T14_53_39.xml`` Group Segment ^^^^^^^^^^^^^ The Group Segment Menu, available when several segments are selected in the SHT dashboard, allows you to define a segment group. You must provide a segment group Name and Mnemonic. Optionally you can provide a Platform Power Profile and the Instrument Power and Data profiles, that are an envelope for all the segments included in the group. The Platform Power area allows you to either manually set a Platform power value for the segment or to choose a Platform power profile from the ones defined in the `JUICE Core System Configuration Database Power Profile `_. the Instrument Area allows you to view or update "Instrument Type" (science discipline) or "Instrument" resources (Data and Power). The available types are: * Geophysics (RIME, GALA, 3GM) * Remote Sensing (JANUS, MAJIS, UVS, SWI) * In-Situ (JMAG, PEP, RPWI) * Navigation (NAVCAM) These types are are defined for private users in the `JUICE Core System Configuration Database Instrument Type `_. The available resources categories are divided in rates and in segment values: Data rate (bits per second) and Energy (watt hour) for rates and Data volume (bits) and Power (watts) for values. A Science Target can also be specified in between: * Rings and satellites * Plasma * Callisto * Europa * Ganymede * Jupiter atmosphere * Navigation These targets are are defined for private users in the `JUICE Core System Configuration Database `_. In the last column of the Instrument Area, you can add new rows with the ``Plus`` icon and when you are editing an entry you can save it or delete it. There is also a button to reset to the original entries and a button to ``Compare`` your changes with the original values. Calendar Operations ^^^^^^^^^^^^^^^^^^^ This calendar menu allows you to choose a time range with a calendar where you can select the year and month, click on a start date then on an end date, and finally either filter the segments by the date range or set the view of the SHT dashboard to the selected range. Left Vertical Menu ------------------ The **left vertical menu** is expandable and contains a variable number of elements. The elements available when starting the SHT are: * SHT ``Jupiter`` Icon: Restarts the SHT to the Crema 3.0 instance * Toogle Menu ``Lock`` Icon: Logs out a user and restarts the SHT to the Crema 3.0 SHT instance * Timeline Configuration ``Gear`` Icon: Opens the :ref:`20_timeline_tool:Timeline Configuration` Menu * Geometry Series ``Plot`` Icon: Opens the :ref:`20_timeline_tool:Geometry Series` Menu * CSV Import ``CSV`` icon: Opens the :ref:`20_timeline_tool:CSV Import` Menu * CSV Export ``CSV`` icon: Opens the :ref:`20_timeline_tool:CSV Export` Menu * JSON Import ```` icon: Opens the :ref:`20_timeline_tool:JSON Import` Menu * Segments Definitions ``book`` icon: Opens the :ref:`20_timeline_tool:Segment Definitions` Menu * Local History ``clock`` icon: Opens the :ref:`20_timeline_tool:Local History` Menu * Plans Database ``drives`` icon: Opens the :ref:`20_timeline_tool:Plans Database` * Detailed Scenarios ``microscope`` icon: Opens the :ref:`20_timeline_tool:Detailed Scenarios` Menu If you log in SHT, an additional element is available to log out. Additional elements appear when segments are present in the SHT dashboard, these elements are: * Segments ``bars`` icon: Opens the Segments Browser Menu. * Segment Groups ``book`` icon: Opens the Segment Groups Menu. * Last Verification ``checked notebook`` icon: Opens the Segmentation Plan Verification Menu. * Detail Scenario Integration ``screw`` icon: Opens the Detailed Scenario Integration Menu. * Log Out ``eject`` icon: Appears if you are logged in. Logs your user out of SHT. The following sections provide a detailed description of the menu elements. Timeline Configuration ^^^^^^^^^^^^^^^^^^^^^^ This Menu allows the user to choose generic events to be displayed in the SHT dashboard and then to filter them either by mission phases or by date. The available generic events depend on the SHT instance. Some of the available events are: Downlink, Flyby Ganymede, Flyby Callisto, Sun superior conjunction, Io transit, Ganymede transit, etc. By hovering the over the event name more information about the event definition is provided. Click on the ``Configure`` button to apply the selected configuration. You can also use this menu later on to reset the view of the timeline dashboard by clicking the ``Configure`` button. All the Events are defined in :ref:`20_timeline_tool:Event Definitions`. The Event Definitions are also publicly available from the `JSOC Uplink Core System Event Definitions `_ The definition can also be obtained and updated by private users from the `JUICE Core System Configuration Database Event Definitions `_. The Description -- and other parameters -- can be changed there by users. Geometry Series ^^^^^^^^^^^^^^^ This Menu allows the user to add geometry plots in the SHT dashboard. The plots available are divided in science and operational categories: * Jupiter * General * Ground Stations * Dust * Orbit * Rings Examples or geometry plots are: ``Distance to Jupiter``, ``Angle between S/C Ganymede orbit plane normal vector and Sun direction``, etc. All the available quantities are available at :ref:`20_timeline_tool:Geometry Series Definitions`. In addition these series are publicly available from the `JSOC Uplink Core System Series Definitions `_. The definitions can also be obtained and updated by private users from the `JUICE Core System Configuration Database Event Definitions `_. The Description -- and other parameters -- can be changed there by users. The plots agree with the zoom level of the timeline in the SHT dashboard. The added plots can be removed with the ``Close`` button on the bottom left hand side of the plot. CSV Import ^^^^^^^^^^ This Menu allows the user to import a local segmentation plan that you might have exported from SHT or generated by other means. The import feature accepts CSV files containing three or four columns of data. The first column is the name of the item, the second the start timestamp, the third the end time, the optional subgroup, and finally the optional source group. The Group will group all the time windows of the same group -- or timeline -- in the SHT dashboard row. Subgroups specify the Source of the time window. This Source can have a similar name to the timeline or Group but are meant to specify the originator of the time window, subgroups -- or sources -- also indicate SHT to use a different color for the time window in the dashboard. For example:: EVENT_1,2032-07-08T15:53:52Z,2032-07-08T18:53:52Z,EUROPA_FLYBY # Comment line - Without subgroup EVENT_2,2032-07-10T15:53:52Z,2032-07-10T19:53:52Z, EVENT_3,2032-07-18T15:53:52Z,2032-07-18T18:53:52Z,EUROPA_FLYBY,WG1 EVENT_3,2032-07-18T19:53:52Z,2032-07-18T20:53:52Z,,WG1 The detailed format of the input CSV is as follows: * Header with column names is not expected. * The separator used shall be the comma character ``,``. * The Subgroup is optional. * Comment lines are allowed, they shall start with a ``#`` character. * The tool accept the usual line endings characters (win: ``CRLF``, unix: ``LF``, mac CR). * Dates shall be expressed using ISO format. e.g. ``2032-07-08T15:53:52.350Z``. * To indicate the UTC scale, the ``Z`` time zone marker shall be append. * If the time zone marker is not included, the date will be consider a local time. Only item names already included in the `JUICE SOC Core System Segment definitions database `_ can be imported in csv format. When you import a Segmentation Plan, you can choose the timeline (row in the SHT dashboard) that you want to load it on. CSV Export ^^^^^^^^^^ This menu allows you to export timelines from the SHT. There are four different tabs: All, Visible, Filter by phases, Filter by dates: * All: Export all contents without any time filtering * Visible: Export the contents **completely** visible in the current timeline. * Phases: Filter by mission phase. Mission phases depend on the trajectory in use (Crema) and their definitions are available for registered users in the `JUICE Core System Configuration Database `_. Please note that Phases are also available from the Timeline Configuration and can be displayed in the SHT dashboard. * Date: Export the contents filtered by a start and finish date. You can also choose the timelines (groups) you want to export. The exported CSV has the same format as specified in :ref:`20_timeline_tool:CSV Import`. The exported file name will be:: export__.csv e.g.: ``export_CREMA_5_0_SEGMENTATION_v6_2_2022-08-12T13_19_16.csv`` JSON Import ^^^^^^^^^^^ This menu allows you to upload a local JSON file containing a segmentation. Optionally, the target timeline can be overwritten. By default the segmentation will be added to the timeline that it has been defined and can therefore result into overlapping segments (shown as "Keep original"); you can also choose to overwrite any of the other timelines. Segment Definitions ^^^^^^^^^^^^^^^^^^^ This menu provides a list of all the available segment definitions. The aim is that you are aware of all the information of the available segments. The menu icon has a number with a purple background providing the number of available segment definitions. Segment definitions are provided in a table with their Mnemonic, Prime/Not Prime, Source Group, and Pointing Request information, segments can be sorted by the any of these columns. In addition a ``magnifying glass`` icon allows you to retrieve all the information of the segment which includes a Description, Pointing information and Power and Data profiles. Remember than Prime segments are those that are part of a segmentation plan whereas non prime segments are opportunity segments. You can also filter the segments by name using the top-right Global filter and you can export all the segments in CSV or JSON format or a number of filtered segments. The CSV export corresponds to the fields provided in the menu's segment table. The filename is always: ``download.csv``. The JSON export provides all the available information of the segments. The filename is: ``segment_definitions_.json`` e.g.: ``segment_definitions_2022-08-12T14_48_44.json``. Note that Segments are also available at the SOC Entity Database from the `JUICE SOC Core System Segment definitions database `_ and can be added, deleted, and modified from there. The Segment definition database, or "Segment Library" can also be accessed from the `public JUICE SOC web page `_. Local History ^^^^^^^^^^^^^ The Local History Menu is a very powerful tool that allows you to locally save checkpoints of your progress when working on a segmentation. These checkpoints are temporarily stored in your web browser. The Menu has a button ``Create local version``, by clicking it a new checkpoint line is added. Each line has two buttons, the SHT Crema version, its name (``Checkpoint YYYY-MM-DDTHH:MM:SS.SSSZ``), the date, and three icons. The icons are for deleting the local version (``red cross``), recover the local version (``blue up arrow``), and saving the local version into a file (``green down arrow``). The green button also acts as an "JSON Export" functionality since the downloaded file is a JSON file that contains all the information of the segmentation. When more than one backups are available the buttons on the left can be used to choose two segmentation JSONs and compare them (as with the ``diff`` utility). When you do so a ``Show differences`` button will appear. In addition, there is a ``Load file`` button that allows you to load a plan in JSON format to make it available as a checkpoint. Plans Database ^^^^^^^^^^^^^^ The Plans Database Menu allows you to load an existing Science Segmentation Plan (or simply Plan). The menu icon has a number with a purple background providing the number of available segmentation plans. The plans are listed in a table with the following columns: Name, Author, Is Public?, PTR, Creation Date, Description, and a ``Load`` and ``Show Refine`` buttons. The PTR column indicates whether if a segmentation plan has a Pointing Request timeline associated to it. The other columns are self-explanatory. In the bottom right corner there is a button to synchronise the available plans from the database, in case they have been updated. You can also filter the plans by name using the top-right Global filter and you can export the plans information in CSV or JSON format (all public plans are included) or a number of filtered plans. The CSV export corresponds to the fields provided in the menu's plan table. The filename is always: ``download.csv``. The JSON export provides all the available information of the plan. The filename is: ``plan_list_.json`` e.g.: ``plan_list_2022-08-12T14_48_44.json``. The plan is loaded with the ``Load`` button on the last column of the list. Next to it there is the ``Show Refine`` button that opens a window with a log of all the segment refinements that have been performed with the :ref:`20_timeline_tool:Detailed Scenarios`. When a plan is loaded, a bottom left button will appear to remove the plan from the timeline ``Close ``. Note that the Segmentation Plans are also available for private users at the SOC Entity Database from `JUICE SOC Core System in the Segmentation Plan database `_ and can be added, deleted, and modified from there. Detailed Scenarios ^^^^^^^^^^^^^^^^^^ The Detailed Scenario Menu allows you to load the Science Segmentation refinement resulting from a detailed scenario exercise outcome. The menu icon has a number with a purple background providing the number of available detailed plans for the selected trajectory. Once a plan is loaded, this menu allows you to load a detailed scenario from the list of available detailed scenarios. You can also filter the detailed scenarios by name using the top-right Global filter and you can export all the segments in CSV or JSON format or a number of filtered detailed scenarios. The CSV export corresponds to the fields provided in the menu's plan table. The filename is always: ``download.csv``. The JSON export provides all the available information of the plan. The filename is: ``plan_list_.json`` e.g.: ``plan_list_2022-08-12T14_48_44.json``. The scenario is loaded with the ``Load`` button on the last column of the list. Once a detailed scenario is loaded the Detail Scenario Integration ``screw`` icon appears and is immediately open. See :ref:`20_timeline_tool:Detailed Scenario Integration` for a detailed description of the UI and functionalities of the detailed scenarios. Segments ^^^^^^^^ The Segment menu only appears when segments are defined in the SHT dashboard. The menu icon has a number with a purple background providing the number of segment instances in the current segmentation plan. The segments are provided in a table with Start and End Times, their definition (acronym) and two icons: a ``magnifying glass`` that will center the SHT dashboard on that segment and a ``pencil`` icon to update the segment. You can filter the segments by Segment Definition and/or by segment start and end times. If the segment update option is clicked a new ``Update Segment`` window will appear containing segment information. The information displayed is divided in four areas: Summary, Platform Power, Pointing, and Instrument Resources. The Summary area allows to give a name to the segment instance, to change the segment definition and provides time and duration information. Next to the segment definition drop down menu there is an information icon that provides more detailed information of the segment, including its description. The Platform Power area allows you to either manually set a Platform power value for the segment or to choose a Platform power profile from the ones defined in the `JUICE Core System Configuration Database Power Profile `_. The Pointing area allows you to provide a Pointing snippet (PTR snippet), define a pointing target and choose a Slew Policy. You can Load the PTR snippet, save it or clear it. The Slew Policies are defined for private users in the `JUICE Core System Configuration Database Slew Policy `_ the available policies are the following: * FLEXIBLE BLOCK: The pointing duration will be adapted to optimise the slew * KEEP_BLOCK: The pointing duration is fixed regardless of the slew time * KEEP_START: The pointing start time is fixed and the end time is flexible * KEEP_END: The pointing start time is flexible and the end time is fixed Finally, the Instrument Area allows you to view or update "Instrument Type" (science discipline) or "Instrument" resources (Data and Power). The available types are: * Geophysics * Remote Sensing * In-Situ * Navigation These types are are defined for private users in the `JUICE Core System Configuration Database Instrument Type `_. The available resources categories are divided in rates and in segment values: Data rate (bits per second) and Energy (watt hour) for rates and Data volume (bits) and Power (watts) for values. A Science Target can also be specified in between: * Rings and satellites * Plasma * Callisto * Europa * Ganymede * Jupiter atmosphere * Navigation These targets are are defined for private users in the `JUICE Core System Configuration Database Target `_. In the last column of the Instrument Area, you can add new rows with the ``Plus`` icon and when you are editing an entry you can save it or delete it. There is also a button to reset to the original entries and a button to ``Compare`` your changes with the original values. Finally you can apply all the changes in the "Update Segment" window with the ``Update`` button or cancel the updates with the ``Cancel`` button. Segment Groups ^^^^^^^^^^^^^^ The Segment Groups menu only appears when segments groups are defined in the SHT dashboard. Segment Group creation is described in :ref:`20_timeline_tool:Create a Segment Group`. The menu icon has a number with a purple background providing the number of segment groups in the current segmentation plan. The menu displays the defined groups in a table with a Name, Mnemonic, and Platform Power Profile columns and allows to edit a group or to remove it. You can also filter the groups by name using the top-right Global filter and you can export all the segments in CSV or JSON format or a number of filtered plans. The CSV export corresponds to the fields provided in the menu's plan table. The filename is always: ``download.csv``. The JSON export provides all the available information of the groups contained in the plan. The filename is: ``group_list_.json``, e.g.: ``group_list_2022-08-12T14_48_44.json``. Last Verification ^^^^^^^^^^^^^^^^^ The Last Verification Menu provides you a list/report of the segmentation conflicts, these conflicts are constantly updated and reported immediately. The conflicts are provided in a table with the start and end times, their duration, the conflict type, an icon to move the SHT dashboard to the conflict, and some actions to solve the conflict. In general, Prime Segments cannot overlap, whereas non Prime segments can overlap. When Prime Segments overlap, a conflict is generated. Another type of conflicts are gap conflicts: Segmentation plans should not have segment-less gaps. Gap conflicts can be resolved by either extending the nearest to the right or left. In addition, periods of more than 48 hours without a DL_1 (or a DL_EXT) segment are indicated as well as when a DL_1 or DL_EXT segment duration is less than the minium allowed duration (4 hours). You can also filter the conflicts by name using the top-right Global filter and you can export all the segments in CSV or JSON format or a number of filtered plans. The CSV export corresponds to the fields provided in the menu's plan table. The filename is always: ``download.csv``. The JSON export provides all the available information of the plan. The filename is: ``verification.json``, e.g.: ``verification2022-08-12T14_48_44.json``. Detailed Scenario Integration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When a Detailed Scenario is loaded as indicated in :ref:`20_timeline_tool:Detailed Scenarios`. The window is called ``Detailed Scenario Resolver`` and it allows you to merge the detailed scenario into the plan. The window consists of a table with all the *conflicts* to be resolved which usually are partial overlaps of the plan segments and the *updated* segments. The segments are likely to be very similar and you will see them in the Prime Timeline. In order to distinguish them with the segments (of the same type or not) of the plan, they have a dashed contour, a background colour with transparency, and the segment name in white letters (instead of black). The table provides the information of the: Start Time, End Time, and Duration in hours of the "conflict". The conflcit type (``Partial Overlap``, etc.) and three options for each entry: * Examine ``magnifying glass`` blue icon: Move the timeline to the segment. * Priority to ENHANCED segment ``boxed from arrow`` green: Replace the plan segment by the scenario, or "enchanced" segment. * Priority to PLAN segment ``boxed into arrow`` orange: Keep the plan segment and ignore the scenario segment. There are three buttons at the bottom of the window: * ``Blind Replacement`` in green, to blindly replace all segments by the scenario/enhanced ones. * ``Discard Integration`` in orange, to discard all the scenario/enchanced segments. * ``Close`` in grey, to close the window. While this window is open ou can navigate through the timeline dashboard in the usual way (pan, zoom, etc.) and you can jump to a segment. Please note that unresolved conflicts in between the plan and the detailed scenario will not be saved nor can be exported. Working with SHT ================ Getting Started --------------- When TLT is started or the first time the TimeLine Configuration menu is displayed for the user to setup the initial configuration of the SHT by selecting a number of events to be displayed in the timeline dashboard. The next step is to load a Segmentation Plan. You can do so with the :ref:`20_timeline_tool:Plans Database` Menu. Depending on whether if you are logged in with your private user or not different segmentation plans will be available. There should always be a default segmentation plan called ``juice_sc_sat__spice_segmentation``. If you load this plan, the segments defined by the attitude profile of JUICE are in the generic timeline in the dashboard. The next step is to create or to update a segment but before let's add some geometry series to the SHT dashboard. Geometry series can be added as described in :ref:`20_timeline_tool:Geometry Series` and provide a geometrical context that along with certain events can be really helpful when working on a segmentation plan. E.g.: The ``Jupiter Distance`` plot can help us assess when is reasonable to have certain segments around a perijove event. Working with Segments --------------------- Creating a segment is as easy as double-clicking with the mouse left button the timeline dashboard. By doing so the "Create Segment" window will appear allowing you to choose a segment definition, choosing a timeline and to specify the start time and then either the duration or the end time of the segment. The default values for the start time is where you clicked in the dashboard and one day of duration. Once you created the segment, it will appear along with the defined timeline. You can now select and/or update the segment by clicking the left button of your mouse. By doing so the Segment Context Menu will appear with the following options: * Show in graphs * Display info * Update item * Adjust Time * Clone in ... * Group in ... * Propagate data (only in Detailed Plan segments) The ``Display info`` option will provide you the basic information of the segment: its instance, start and end time, and duration. ``Adjust Time`` will allow you to reset its start and/or end times. ``Update Segment`` allows you to change the segment definition, Platform Power, Pointing information and Instrument Resources. Detailed information on these options is available at :ref:`20_timeline_tool:Segments`. The ``Clone in ...`` option allows to clone the segment in a different timeline and the ``Group in ...`` option allows you to add the segment to an already defined Segment group (more info in :ref:`20_timeline_tool:Create a Segment Group`). With ``Show in graphs`` you can see where the segment is in the geometry series loaded in the dashboard. If you right click and drag the segment, you can move it around the horizontal axis of the timeline and modify its start and end times preserving its duration. A segment can be Prime or Not Prime. Prime segments define the science priority for a time period during the tour and usually define the pointing for the segment duration. Not-Prime segments are *opportunity* segments or segments of a *reference segmentation* and are only based on geometry consideration. Opportunity segments windows can be used to identify the prime segment to be included in the segmentation Finally, the ``Propagate data`` option, that is only available for Detailed Scenario segments (see :ref:`20_timeline_tool:Detailed Scenario Integration`), opens a window to propagate the resources, power and data, from one of the detailed scenario segments (for which the power and data have been thoroughly analysed). This is described in detailed hereunder. Segment Data Propagation ^^^^^^^^^^^^^^^^^^^^^^^^ Segment Data Propagation is only available from Detailed Scenario segments. This window allows you to propagate the resources, power and data, from one of the detailed scenario segments (for which the power and data have been thoroughly analysed). The window provides a table that lists **all** the segments in the segmentation plan, providing the option to select them, their start and end times, their definition and three options: * Display ``magnifying glass`` blue icon: Moves the timeline where the segment is. * Update ``pencil`` blue icon: You can update the segment as indicated in :ref:`20_timeline_tool:Segments`. * Resource Selector ``share`` blue icon: Allows you to select instrument individual power and data profiles to propagate to the segment (instead of propagating all). The menu allows you to filter by selected instrument, resource type, and target. You need to tick the box on the lef most column for each resource entry and then press the blue ``Propagate`` button. The window allows you to filter the segments to propagate the profiles to (top right of the table) by a Starting after date, End before date and by segment definition name (or rather pattern). You can then select a number of segment ticking the boxes on the left of the table of the individual segments. To propagate the profiles you need then to click the bottom right ``Apply to selected`` orange button. You can also click the option to ``Apply to all``. Once choosing either of the options, the same window of the Resource Selector will be displayed allowing you to choose which individual resources to propagate. The menu allows you to filter by selected instrument, resource type, and target. You need to tick the box on the lef most column for each resource entry and then press the blue ``Propagate`` button. Finally an important option of the data propagation is the ``Review`` option which is on the left-most bottom right icon. This option opens the ``Update Segment`` window that is explained in :ref:`20_timeline_tool:Segments`. Segment Definitions ------------------- Segments have a mnenomic, a name, and a description. For most of the semgents the mnemonic and the name are the same; in fact the system assumes so and it is convenient that is like this. It is also common that segments have the Description also set to the name or mnemonic which is less convenient. The segment definition is implicit in the segment name which in fact is an acronym. In general segments will contain one of the following parts in their name: * ``G_GPH``: Ganymede geophysics * ``G_RS``: Ganymede remote sensing * ``G_IS``: Ganymede in-situ * ``G_distant``: Ganymede distant observations * ``E_GPH``: Europa geophysics * ``E_RS``: Europa remote sensing * ``E_IS``: Europa in-situ * ``E_distant``: Europa distant observations * ``C_GPH``: Callisto geophysics * ``C_RS``: Callisto remote sensing * ``C_IS``: Callisto in-situ * ``C_distant``: Callisto distant observations * ``JA_PE``: Jupiter atmosphere perijove segment * ``JA_M``: Jupiter atmosphere monitoring segment * ``JA_PH``: Jupiter atmosphere phase segment * ``JA_INCL``: Jupiter atmosphere inclined segment * ``JM_PE``: Jovian magnetosphere perijove segment * ``JM_INCL`` : Jovian magnetosphere inclined segment * ``JM_GM`` : Jovian magnetosphere global monitoring * ``JM_ENA`` : Jovian magnetosphere ENA imaging * ``JM_CB`` : Jovian magnetosphere co-rotation breakdown * ``J_AURORA``: Jupiter auroral and footprint observations * ``J_SAT`` : Jovian satellites remote sensing * ``STAR_OCC``: Stellar occultation * ``EARTH_OCC``: Earth occultations * ``DL``: Downlink * ``CAL``: Calibration * ``PR``: Public relations images * ``J_RING``: Jovian ring remote sensing * ``TOR_RS``: Remote sensing observation of tori * ``IO_RS``: Io remote sensing observations Characters after these keywords will refer either to the number of perijove, the Crema, the flyby reference number, the minor moon target, etc. For example: * ``JA_PE1``: Jupiter atmosphere Perijove 1 * ``C_GPH_25C18``: Callisto geophysics flyby 25C18 Global Segments ^^^^^^^^^^^^^^^ There is a set of observation definitions that include the ``_OBS`` suffix. These are "global" definitions that are used to propagate information, such as the observations assigned (or linked) to a segment, its resources, etc. These segments are not to be used unless for that specific purpose for which, internally, the Operations Scientist will communicate to the SOC System Engineer to propagate an update on ``JM_PE_OBS`` to all ``JM_PE_*`` segments. Currently the global segment definitions available are: * ``JM_PE_OBS`` * ``JA_PE_OBS`` * ``G_GPH_OBS`` * ``G_RS_OBS`` * ``C_RS_OBS`` * ``C_GPH_OBS`` * ``E_RS_OBS`` * ``E_GPH_OBS`` * ``J_SAT_OBS`` * ``G_IS_OBS`` * ``C_IS_OBS`` * ``E_IS_OBS`` * ``STAR_OCC_OBS`` Segment Parameters ^^^^^^^^^^^^^^^^^^ There is a number of other parameters defined the segments that are described hereunder. If the segment **resources** are known they are included in the definition and associated with a science target and an instrument or an instrument type (IT). In such way you can identify which instrument is riding along (given that the riders will have a different target.) The **pointing** of the segment is another dedicated segment attribute, although currently no prime segment has a Pointing Request (PTR) attached to it, the context menu allows the user to define a PTR snippet for a segment, to define the PRIME and RIDER instruments. The **scheduling rules** are a misleading piece of information because it should be based on the opportunity identification and the opportunity segments (also known as reference segments) are the ones that must carry the scheduling rules information information. Opportunity Segments ^^^^^^^^^^^^^^^^^^^^ Opportunity segments are bare segments that do not have any resource allocation but do have scheduling rules associated with them and are generated and scheduled by the JUICE SOC for every trajectory in order to indicate the opportunity to perform a science observation due to a favorable geometrical or operational condition. These segments are listed as non prime in the `JUICE Core System Segment definition database `_ where segments are filtered ``By Prime Segment`` as ``No``. On top of the pre-defined opportunity segments, instrument teams might request to add additional opportunity segments defined by themselves. Create a Segment Group ---------------------- You can group segments by creating a segment group. This can be useful when a number of segments share the same amount of resources (platform power, data and power envelopes, etc.) or simply in order to group segments with similar science/engineering objectives. To create a segment you need to select multiple segments, by left-clicking the mouse with the Control/Command key pressed. After that the :ref:`20_timeline_tool:Group Segment` will appear in the top horizontal bar and you will be able to create the segment, later on you can modify the group in the same manner as indicated in :ref:`20_timeline_tool:Group Segment`. Grouped segments are displayed in the SHT dashboard in the background with dashed horizontal lines and a light blue background colour. Please note that the modification of the segments of a group does not automatically update the group, E.g.: if a segment start time is modified to be earlier, the group is not expanded. The Segmentation Plan --------------------- The starting point of the segmentation is the `Segmentation Proposal File `_ (accessible only to JUICE SOC users). This file contains a set of non-overlapping segments from a set of opportunity segments by applying a set of simple rules of for merging/cutting segments that are available in SHT and constitutes the basis of the start any segmentation plan. A Segmentation Plan, or simply, a Plan, might take a number of iterations before is ready. Whenever we need to iterate the plan we need to evaluate it and ensure that it complies with a minimum set of requirements. In order to do so we can make use of the :ref:`20_timeline_tool:Verify` functionality, check the conflicts with :ref:`20_timeline_tool:Last Verification`, or evaluate it with EPS or with other JUICE SOC tools. To navigate through the plan it is usually handy to do so by opening the Segments Menu, and chose the option to search for a specific segment with the ``magnifying glass`` icon. Once the plan is ready to be shared we need to save it. Segmentation Plan naming convention ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Although strict rules are not applied to the segmentation plan names, the SOC tries to follow a convention in order to facilitate the segmentation harmonization process. In principle each segmentation plan name consists of: - Crema version, or any other descriptive word or phrase. - Segmentation plan version (v1, v2, etc.): Only updated when the segmentation changes. - Segmentation plan letter (a, b, c, et.): Only updated when resources withing segments are updated. For example the latest version of the Crema 5.0 segmentation might be ``CREMA_5_0_SEGMENTATION_v6_a``. Save a Segmentation Plan ^^^^^^^^^^^^^^^^^^^^^^^^ In order to save a new Segmentation Plan, click on the ``Plans Database`` Icon and then click on the ``Save New Plan`` button. A new window will open providing some fields to fill along with a number of informative tabs. Please follow the Segmentation Plan naming convention described above. You need to provide a ``Name`` and ``Mnemonic`` to the plan. The current recommendation is to use the same and for both and use a mnemonic. A ``description`` can also be provided, and is recommended to do so. Finally choose if the plan will be public or not. The informative tabs provide information on: * Source Distribution (Generic, Prime, etc.) * Segment Definition Distribution * Scenario Detail Integrations If you need to modify a Plan, you can do so from the Plan Database. Only plans that can be shared with the rest of the SGS should be set to ``Public`` Update a Segmentation Plan ^^^^^^^^^^^^^^^^^^^^^^^^^^ The modification of some parameters of a Segmentation Plan is not performed within the timeline tool. If you want to change the Public or Private status, description, Name or Mnemonic you will have to do so from the `JUICE Core System Plan Database Entity Database Plan `_. Please refer to the help of the Plan Database for more information. References ========== There are a number of documents, most of which are only accessible to private users, that provide more information on SHT and that can be useful or that have been used as reference. These are listed hereunder: * `JUI-ESAC-SGS-TN-041 Trajectory Segmentation and Operational Scenario Simulations interface `_ 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, the main tool used is SHT. * `UC-22_1: Top level Create Review and Update SHT Event Definitions `_: Procedure to create or update Event Definitions available to SHT. * `UC-22_1: Top level Create Review and Update SHT Geometry Series Definitions `_: Procedure to create or update the Geometry Series available to SHT. * `UC-21: Top level Review and Update Segment Definitions `_: Procedure to create or update Segment Definitions. * `UC-22: Top level Compute Science Segment Opportunities `_: The Opportunity Segmentation is visualised and evaluated with SHT. * `UC-23: Top level Prepare Skeleton Segmentation Proposal `_: The skeleton segmentation is visualised and evaluated with SHT. Event Definitions ================= .. include:: 21_event_definitions.rst Geometry Series Definitions =========================== .. include:: 22_geometry_series.rst