Analysis for feature development questions from Greg Mueller, TVA (3-14-2017 e-mail).
Document Home: R:\doc\sct\2017\TvaEst\TvaSctEstMarch2017Rev2.docx
Phil Weinstein, David Neumann, Edie Zagona, CADSWES, 3-18-2017

Two SCT feature areas are explored in this analysis:

1. Usability Improvements to Series Notes for the SCT.
2. "Undocking" SCT Sheets (tabs).

(1) Usability Improvements to Series Notes for the SCT

Motivation

With an important TVA RiverWare application, there's a problem in using SCT Custom Slot/Timestep Cell Colors for "flagging" special input values. Those annotations can't be conveyed to other RiverWare sessions (of other users) without saving the SCT -- which is infeasible in this particular use.

We considered developing an option of saving the SCT Custom Slot/Timestep Cell Colors in the model file instead of in the SCT configuration. However, this analysis and estimate is for a different approach -- improving the usability of Series Notes for this TVA SCT application.

The screenshot to the right illustrates the application of an SCT Custom Slot/Timestep Cell Color to four timesteps on a series slot.

Note that, currently (in RiverWare 7.0), the "Add Note..." operation is disabled if more than one slot/timestep cell is selected, as depicted in this screenshot.

Series Notes: Current Behavior (RW 7.0)

RiverWare "Series Notes" can be placed on individual timesteps in any series slot. The data for those notes, and for "associations" of notes to particular slot/timesteps, are stored in the RiverWare model file. This is currently available, but the user interface is cumbersome, involving the operation of two complex-looking dialogs just to apply a note to a slot/timestep.

Deficiencies of Series Notes, as currently implemented, are:

1. The process of applying a note to an SCT slot/timestep cell is overly complex (see below).
2. That process doesn't support applying a note to a multiple-cell selection.
3. It's desirable for slot/timestep cells having Series Notes to also, optionally, be displayed with an associated cell background color. (This would override the color associated with the series timestep I/O flag).
4. In time-aggregated SCT views, Series Notes appear only on "Detail" (single timestep) cells, and not in (time aggregation) "Summary" cells:

The following screenshots demonstrate the complexity of the current "Add Note..." implementation. Applying a new note to a timestep involves four operations using four different dialogs, as demonstrated in the following image. Applying an already-defined Series Note to a new slot/timestep cell requires steps (3) and (4) -- using two non-trivial dialogs.

Once a Series Note has been placed on a slot/timestep cell, it can more easily be copied to other cells, as illustrated below.

Proposed SCT / Series Notes Enhancements, Tasks (1-) ...

1. Support Multiple Cells for the existing SCT "Add Note" function. The current process for adding or applying a note to an SCT slot/timestep cell (as outlined above) needs to accommodate multiple-cell selections.
2. New "Apply Note" context-menu-based operation -- a quick way of applying already-defined Series Notes to an arbitrary slot/timestep cell selection. This could be a two-level context menu, showing Note Groups as submenus containing individual Notes.
3. Series Note ornaments in SCT aggregation Summary Cells. This would indicate the presence of notes among the timesteps represented by the summary cell's timestep aggregation. The presence of multiple distinct notes would be indicated with a special hybrid-note ornament.
4. Series Note optional Cell Background Color Override. If present, this would override the background color indicating the slot/timestep's series timestep I/O flag.
5. Optional Development: Provide some way of limiting the note groups presented in the "apply note" context menu tree. (See task 1B, above).

(1A) Support Multiple Cells for the existing SCT "Add Note" function.

The current process for adding or applying a note to an SCT slot/timestep cell (as outlined above) needs to accommodate a multiple-cell selection. (Cell selections will need to be contiguous).

Development tasks:

• Enable the "Add Note..." context menu item for multiple contiguous timestep selections within a single series slot*.
• Instead of operating on the context cell, apply to the current cell selection.
• Extend the NodeGroupMgrDlg's time context to internally and visibly support multiple timesteps.
• Extend the AddSlotNotesDlg's interface to support initialization of "number of timesteps"

*Note: The existing capabilities of the relevant Series Note software readily support applying a note to a "rectangular" slot/timestep selection. (Contiguous timesteps and slot items). We don't need to limit the "Add Note" operation to a timestep selection within only a single series slot.

(1B) New "Apply Note" context-menu-based operation.

A new context menu-based operation for applying already-defined Series Notes to an arbitrary slot/timestep cell selection. This could be a two-level context menu, showing Note Groups as submenus containing individual Notes.

This feature won't make use of any existing Series Note / Note Group GUI. We just need to build a menu tree of the existing Note Groups and Notes defined in the model, and apply the selected note to the selected slot/timesteps.

See also task (1E), an enhancement to this feature.

(1C) Series Note ornaments in SCT aggregation Summary Cells.

This would indicate the presence of notes among the timesteps represented by the summary cell's timestep aggregation. The presence of multiple distinct notes would be indicated with a special hybrid-note ornament.

The SctTableDelegate::paintSummaryCell() method needs to be enhanced to show a Series Note ornament (icon) if any of the time aggregation's timesteps have one or more notes. This implementation can be adapted from the Icon support at the end of the SctTableDelegate::basicModelPaint() method. The following lower-level methods should be enhanced with an optional int stepCount parameter (default: 1) to indicate the number of timesteps starting at the provided timestep index:

• QPixmap SctTableModel::slotTinxPixmap (int sinx, int tinx);
• const QPixmap* SctModelData::getAnnoIconPtr (int slotInx, int tstepInx);

(1D) Series Note optional Cell Background Color Override.

If present, this would override the background color indicating the slot/timestep's series timestep I/O flag.

Development steps include:

1. Add a "cell background color override" property to the Sim/AnnoNote class, with serialization enhancements in AnnoMgr::dumpNotes() and [AnnoMgr] annoMgrCmd. This should have both a color and an associated (bool) flag indicating that background color override is active.
2. Add editing support for this new property in the Q3GUI/NoteEditDlg.cpp -- the current RiverWare 7.0 version is shown here:

3. Enhance the SCT cell background color computation in method:
   QColor SctTableModel::slotTinxBaseColor (int sinx, int tinx, errstat* colorErrRet /*=NULL*/) const;
   ... this should be tested from both normal single-timestep cells and time-aggregation summary cells.
4. In the Note Group Manager dialog (Q3GUI/NoteGroupMgrDlg), add a column to QTreeWidget* _noteTreeWidget to indicate the cell color override.

Note that the current RiverWare version (7.0) already supports showing the Edit Note dialog (indirectly) via a context menu operation on SCT cells having notes:

(1E) Optional Development: Provide some way of limiting the note groups presented in the "apply note" context menu tree. (See task 1B, above).

We can consider various ways of doing this which would work well for TVA's use. Here are three possibilities:

• Option 1: If there are any Note Groups whose names start with the name of the slot's SimObj, only such groups are shown. (Example: "Ocoee Recreation" note group for series slots on Ocoee).
• Option 2: Associate with each Note Group a Simulation Object for which it is intended. This involves adding a SimObj name property to the Note Group structure and edit interface, mostly analogous to the development steps outlined for task (1D).
• Option 3: Associate with each Slot Item in the SCT, the name of a particular Note Group.

Option 3 would involve adding a Note Group name to each SCT slot item, with both Flex/Bison-parsed serialization, and some way of editing that association, presumably on the Edit Series Slot List, possibly with a new 3rd radio button mode. Here is the current (RW 7.0) Edit Series Slot List tab:

Proposed SCT / Series Notes Enhancements -- Estimates

(2) "Undocking" SCT Sheets (tabs).

Here is Greg Mueller's [TVA] description of a desirable feature. [3-14-2017 e-mail]:

• Is it feasible to change ... worksheets in an SCT such that individual tabs in an SCT can be "undocked" similar to how tabs in Internet Explorer or FireFox can be undocked? (Leads have asked me this question in the past and I am not sure if I have asked it of you). I don’t see us using a “redocking feature to combine individual SCTs in a since SCT but that could be useful from a development stance if a person could swap worksheets in and out. Again... for this, I am just curious about feasibility ....

A simple way of roughly accomplishing the requested behavior would be to create a 2nd SCT from the slots on the selected (possibly dragged) SCT Sheet tab. Any solution which uses that as the basis of the implementation (possibly hiding certain features of the "copy") would be quite easy to develop.

Alternatively, if the torn off sheet is an entirely different sort of thing (not itself actually an SCT, as such), we would need to understand more precisely what we are trying to accomplish.

Currently (RW 7.0), the contents of an SCT Sheet tab can be copied to another SCT, using context menu operations on the "Edit Series Slot List" tab. This is illustrated below. This does provide a way of recombining several separate SCTs into a single SCT.

Also, the SCT's File menu has a "New SCT ..." operation; this creates a new SCT, opened to the Edit Series Slot Tab. So the behavior we are considering here is currently doable, with basically ten (10) clicks. (And, not much new software development is needed for the basic feature).

We could also provide higher level operations for that work flow, i.e. copying or moving sheets directly using context menu or drag operations directly on SCT Sheet tabs.

Estimates (Phil, 3-16-2017):

• 8.0 Hours -- Basic operation -- using context menu operations of an SCT Sheet tab -- of copying or moving the contents of an SCT Sheet tab to a new SCT. The new SCT would have the same configuration and state of the original SCT except for the list of series slots. (We would probably also erase the content of the ancillary SCT tabs from the new SCT: Scalar Slots, Object Grid, and such).
• 12.0 Hours (additional) -- Drag and Drop of SCT Sheet tabs between SCTs. (some tricky Qt coding).

See illustration below.

Appendices

Original Slot Text Annotations (Series Notes) Documentation:

• Slot Text Annotations in RiverWare 5.2 -- User Notes (June 2009)
  R:\doc\guiGeneral\Annotations\SlotAnnotations2009UserNotes.fm [PDF]
• Slot Text Annotations in RiverWare 5.2 -- Internal Design (May 2009)
  R:\doc\guiGeneral\Annotations\SlotAnnotations2009UserNotes.fm [PDF]

SCT Custom Slot/Timestep Cell Colors Documentation:

• SCT Custom Slot/Timestep Cell Colors / RiverWare 6.8 (Sept 2015)
  R:\doc\sct\2015\SctCustomColors-2015-Sep.docx [PDF]
• SCT Series Value Threshold Exceedance Cell Color Alerts / RW 6.9 (Jan 2016)
  R:\doc\sct\2016\SctValueAlerts\SctValueAlertColors-Jan2016.docx [PDF]

Sample UserFlagSet and SlotUserFlagMap in SCT Config serialization:

User Flag XML in Flex/Bison-parsed SCT grammar. [RiverWare 7.0]
Related Images (http://cadswes2.colorado.edu/~philw/2017/SCT/CustCellColors/).

USER_FLAG_SET XML-UFLAG-SET-BEG
<UserFlagSet>
 <UserFlagDef bgEna="1" fgEna="1" fgColor="#000000" label="E-Mergen-C" bgColor="#ff8074"/>
 <UserFlagDef bgEna="1" fgEna="0" fgColor="#000000" label="Potato" bgColor="#aaaa7f"/>
</UserFlagSet>
XML-UFLAG-SET-END

SLOT_USER_FLAG_MAP XML-UFLAG-MAP-BEG
<SlotUserFlagMap slotRecCnt="2">
 <UserFlagSlotRecord slotName="Mead.Inflow" cellCnt="2" slotCol="-1" slotRecInx="0">
  <UFS-Cell flag="Potato" dt="11-01-1993 00:00:00"/>
  <UFS-Cell flag="Potato" dt="12-01-1993 00:00:00"/>
 </UserFlagSlotRecord>
 <UserFlagSlotRecord slotName="Mead.Outflow" cellCnt="2" slotCol="-1" slotRecInx="1">
  <UFS-Cell flag="Potato" dt="11-01-1993 00:00:00"/>
  <UFS-Cell flag="Potato" dt="12-01-1993 00:00:00"/>
  <ThresholdSpec valType="N" threshInx="0" intervalName="Normal">
   <NumValue unitType="Flow" scale="1" unit="acre-feet/month" val="800000"/>
  </ThresholdSpec>
  <ThresholdSpec valType="N" threshInx="1" intervalName="Oops" flag="E-Mergen-C">
   <NumValue unitType="Flow" scale="1" unit="acre-feet/month" val="0"/>
  </ThresholdSpec>
 </UserFlagSlotRecord>
</SlotUserFlagMap>
XML-UFLAG-MAP-END

Prior analysis featuring adjustment to SCT Custom Slot/Timestep Colors:

• notes1.html (First iteration, 3-16-2017)
  http://cadswes2.colorado.edu/~philw/2017/SCT/TvaMarch/notes1.html

--- (end) ---