**************************
Segmentation Coverage Tool
**************************
Overview
========
The Segmentation Coverage tool (SCV) is a tool to explore the coverage of a given
segmentation in the geometry space of interest and compare it to theoretical
opportunities.
This tool is extremely useful to assess the status or quality of a segmentation
plan with respect to the available segmentation opportunities during the science
segmentation process.
Context
=======
SCV 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
<https://juicesoc.esac.esa.int/tm/?trajectory=CREMA_5_0>`_. 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 SCV are the instrument teams members involved in the
trajectory science segmentation process. In addition, the Operations Scientists
serve as first users of the functionalities developed by the SOC such as the SCV.
Accessibility
=============
The Segmentation Coverage tool is accessible from the
`JUICE SOC Website <https://www.cosmos.esa.int/web/juice>`_
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 <https://juicesoc.esac.esa.int/event_tool/>`_
and then you need to select the Crema instance of the ``Segmentation coverage
tool``. E.g.: `Crema 5.0
<https://juicesoc.esac.esa.int/event_tool/segmentref/segmentref_catalogue_CREMA_5_0>`_.
Segmentation Plan and Reference Opportunities
=============================================
Reference Opportunities
-----------------------
Reference Opportunity segments (or simply opportunity segments) are bare
segments that do not have any resource allocation and are automatically
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
<https://juicesoc.esac.esa.int/readonly_admin/core/segmentdefinition/?prime_segment__exact=0>`_
where segments are filtered ``By Prime Segment`` as ``No``.
Segmentation Plan
-----------------
A Segmentation Plan, or simply, a Plan, is the outcome of any iteration of
:ref:`20_timeline_tool:The Segmentation Process`. This process might take a
number of iterations before is ready and can be checked or validated at any
time.
Ultimately the segmentation plan is a number of continuous segments with full
coverage that divide the JUICE Jupiter Tour by science objectives.
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
<https://juicesoc.esac.esa.int/entity_admin/core/plan/>`_ and can
be added, deleted, and modified from there.
Tool's Utility
--------------
The SCV allows you This tool to assess the status of a segmentation plan
with respect to the available segmentation opportunities during the science
segmentation process by comparing the implemented segments with respect to the
opportunity or reference segments.
User Interface
==============
SCV consists of a top bar and an event display dashboard with two columns: the
**Filter Menu** and the **Segmentation and Reference Timelines and Tables**.
These elements are described in detail hereunder.
The user interface is similar to the one of the
:ref:`32_opportunity_segments:Opportunity Segments Coverage Tool` but it is
*duplicated* given that it displays opportunity segments (reference segments)
and the segments of a segmentation plan.
Top bar
-------
The top bar is divided in three sections. From left to right, the first section
is the tool icon; by clicking it you go back to the ESVCT suite tool selection
menu. The next section is displays the Crema version for the Segmentation Plan
and the Segment Opportunities, and the last one allows you to choose the
Segmentation.
Filter Menu
-----------
The filter Menu is on the left of the dashboard and allows you to filter both
the segments in the Segmentation and Reference Tables and timelines.
You can either filter the segments by definition or by date.
When filtering the segments by definition, you have three tabs with
different options:
* ``Definition``: Simply filter by segment name, when typing it a number
of suggested segments will be displayed. You can introduce
several definitions at once. You can also remove selected segments by
clicking on the cross over their icon.
* ``Pattern``: By using a certain number of characters, all the segments that
contain these characters will be selected.
* ``WG``: Filter the segments by Working Group.
In order to filter by dates you can either enter a date manually in ``yyyy-mm-dd``
format or you can select the date from the calendar using the ``calendar`` icon
both for the ``Start After`` and ``End Before`` entries.
Please note that you **must** define both Segmentation and Reference filters in
order to be able to apply the filter.
Finally apply the filter clicking the blue ``Filter`` button.
You can clear all the filters by cliking the turquoise ``Clear`` button.
When at lesat a filter is applied the ``Explore Graphs`` (or ``Explore Plots``)
blue icon is displayed. This functionality is described later in this document.
When at lesat an opportunity is selected, an ``Export`` blue icon is displayed with
the number of opporunities in parenthesis. This functionality is described later
in this document.
Segment Timelines and Tables
----------------------------
The Segment Timeline allows you to dynamically display the Opportunity/References
Segmentation across time, you can **pan** the timeline left to right to move in time
and up to down to display all the segments, you can also scroll up and down to move
vertically across the timeline. Finally, you can **zoom** in and out by pressing
the ``control`` button and scrolling up and down.
The first timeline (row) is the reference segmentation whereas the second one is
the Segmentation plan itself. Segments have a light-blue background by default.
By left clicking in one of the segments a context menu will appear with the
following options:
* ``Mark as Selected``: Checks the Segment as ``To Be Exported``
in the Segmentation or Reference table. When doing so the opportunity
background changes to green.
* ``Explore Plots``: also known as ``Explore Graphs``, this
functionality is described later in this document.
The Segmentation and Reference tables consists of the following seven columns:
* ``Id``: Segment id staring from ``1``. The Id is ordered first by Source (WG) and then
by time.
* ``To be Exported``: Indicates whether if the segment is selected to be exported.
* ``Start``: Start time of the opportunity segment.
* ``End``: End time of the opportunity segment.
* ``Name``: Segment name, e.g.: ``CALLISTO_FLYBY``.
* ``Source``: Segment source: ``WG1``, ``WG2``, ``WG3``, ``WG4``.
* ``Type``: Opportunity segment type, e.g.: ``CALLISTO_FLYBY``.
By double clicking an segment in a table, the timeline will be
automatically centered on it.
The number of total or filtered opportunity segments is provided at the end of
the table.
Explore Graphs
--------------
This is a very powerful feature of the SCV that allows you to compare the
reference/opportunity segments with the segmentation plan segments in the
geometrical space in order to be able to assess if the science opportunities
are considered in the segmentation plan by plotting different quantities for the
time span of one or multiple opportunity/reference segments and overlaying on
top of them the span covered by the segments of the segmentation plan.
This option is activated either when a filter is applied or from the context menu
of a segment from a timeline. From the timeline, the plots will correspond
to a *single* segment whereas if done from the Filter Menu, the plots will be
shown for all *filtered segments* and for both segmentation and reference
segments.
In either way when the ``Explore Graphs`` option is selected a window is expanded
from the right side of the dashboard on top of the timelines and the tables. This
window provides different information messages, either green for information or
yellow for a warning concerning the number of segments selected.
You can then add a number of plots that will be displayed in different tabs.
The plots are added after choosing a parameter for the X axis and another one
for the Y axis and then clicking the green button ``Add new plot``. If you are
using the functionality from the Filter Menu, a third drop down menu
will appear for the Reference segmentation Y parameter ``Ref. Y Parameter`` and
instead of one plot per tab, two plots will be displayed, one on top of the
other.
By having the two plots available you can compare how the segmentation is
distributed with respect to the reference segmentation. In this particular
case, using the Toogle Spike Lines plot option described below is very useful.
The available parameters depend of the segment type. The parameters are
described in :ref:`33_segmentation_coverage:Segment Parameters`.
The parameters are also defined and are available for private users at the
`JUICE Gitlab event-tool repository
<https://juigitlab.esac.esa.int/core-system/uplink/event-tool/-/blob/develop/backend/opp_discover/data/segment_parameters.json>`_.
The mapping of the parameters to the different opportunity segments are described in
:ref:`33_segmentation_coverage:Segment Mapping`.
The mapping is also defined and is available for private users at
the `JUICE Gitlab event-tool repository
<https://juigitlab.esac.esa.int/core-system/uplink/event-tool/-/blob/develop/backend/opp_discover/data/segment_map.json>`_.
When clicking on a plot its options are activated. When hoovering the mouse
over 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.
* Zoom in ``plus box`` icon: Zoom in the plot.
* Zoom out ``minus box`` icon: Zoom out the plot.
* Autoscale ``arrows box`` icon: Scale the plot appropriately for the shown data.
* Reset axes ``home`` icon: Reset a zoomed and/or panned plot view.
* Toogle Spike Lines ``corner lines`` icon: Activate/Deactivate dashed lines
intersecting the X and Y axis from the plot data points.
* Show closest data on hover ``box arrow`` icon: Show the plot data only when
hovering over the plot. Deactivates "Compare data on hover".
* Compare data on hover ``double box arrow`` icon: Show the plot data
continuously corresponding to the X axis coordinate. Deactivates "Show
closest data on hover".
These actions are triggered with a left click with the mouse and apply to both
plots. Please note that zooming in one of them will also apply the zoom to the
other. Same thing when panning, auto scaling, etc.
Finally, there is a legend with the plotted segments, if you right
click on them, a context menu will appear with ``Mark as Selected`` allowing you
to select them in the segments table to export them. By doing so,
the plot will change the format of the line to a line with dots. If you right
clik on a selected segment the context menu will show the option ``Unmark as
Selected`` to de-select it.
Working with SCV
================
Getting Started
---------------
When SCV is started the default Science Study case with the latest segmentation
plan and reference segmentation are displayed.
Working Example
---------------
Say that we want to assess whether if we the latest segmentation plan agrees with
our expectation of all the Jupiter Monitoring during a Perijove for a given period
of time. We start applying a filter to display the segments that we are interested in
by typing ``JM_P`` (for Jupiter Perijove) in the Segmentation Filter and
``JUPITER_PERIJOVE`` in the Reference Filter. We then select the dates we are interested
``Start after: 2033-01-08``, ``End Before: 2033-01-14``.
With this filter for Crema 5.0 we obtain a total of 5 segmentation segments and 1
opportunity (reference) segments. In order to assess the "coverage" of these observations
we click on the ``Explore Graphs`` button.
For the ``X Parameter`` we choose ``Time`` and for the ``Y Parameter`` and ``Ref. Y Parameter``
we choose ``Distance to Jupiter``, then we click on ``Add new plot``.
With the plot we can see that around ~60% of the Perijove opportunity is covered by perijove
specific segments ``JM_PE19``, and that the closest approach time is also included.
References
==========
Associated SOC Use Cases
------------------------
These SOC Use Cases might not be available if you do not have a JUICE Confluence
account.
* `UC-39: Top level Segmentation Coverage Analysis
<https://issues.cosmos.esa.int/juicewiki/display/SOCDEV/UC_39_Top_level_Segmentation_Coverage_Analysis>`_:
Steps 30 and 40 provide instructions on how to load and then be able to
visualize a segmentation with SCV.
* `UC-21: Top level Review and Update Segment Definitions
<https://issues.cosmos.esa.int/juicewiki/display/SOCDEV/UC_21_Top_level_Review_and_Update_Segment_Definition>`_:
Procedure to create or update Segment Definitions.
* `UC-24: Top_level_Harmonize Segmentation
<https://issues.cosmos.esa.int/juicewiki/display/SOCDEV/UC_24_Top_level_Harmonize+Segmentation>`_:
Procedure for SOC to iterate a segmentation with PIs, the main tool used is TLT. SCV can help this process.
* `UC-22_4: Top_level_Create_Review_and_Update_Event-Tool_Segment_Mapping
<https://issues.cosmos.esa.int/juicewiki/display/SOCDEV/UC_22_4_Top_level_Create_Review_and_Update_Event-Tool_Segment_Mapping>`_:
Procedure to create or update the Segment mapping available to SCV.
* `UC-22_5: Top_level_Create_Review_and_Update_Event-Tool_Segment_Parameters
<https://issues.cosmos.esa.int/juicewiki/display/SOCDEV/UC_22_5_Top_level_Create_Review_and_Update_Event-Tool_Segment_Parameters>`_:
Procedure to create or update the Segment parameters available to SCV.
Segment Parameters
==================
.. include:: 34_segment_parameters.rst
Segment Mapping
===============
.. include:: 35_segment_map.rst