skip to main content
User Interface : Slots : Notes on Series Slots
Notes on Series Slots
Annotation of series slots using Notes allows you to comment on data in a RiverWare model. For example, you may use notes for any of the following actions:
• Document certain characteristics of input data such as filled values, storm events, etc.
• Provide metadata on the source of the input data.
• Call attention to specific operations, decisions, or outcomes for a model run.
Notes are for documentation purposes; they do not affect the solution and they cannot be accessed (read or assigned) via rules or other RPL sets. In general, notes are available for all types of series (Series, Multi, Agg, Series with Expression) and can be edited via the Open Slot dialogs, the SCT, and the Edit Account dialogs.
Notes Overview
Notes are short text strings that are associated with one or more timesteps. Each note belongs to a Note Group. Each Note Group contains a list of associated slots and the timesteps to which they apply. The Note Group Manager utility dialog facilitates creation and management of Note Groups. The display icon for each group can be assigned a color.
Notes can be imported and exported as follows:
• From/to text files using the Control File-Executable (non-direct-to-database) DMI functionality; see Exporting Notes Using DMIs.
• From/to an external XML file using the Note Group Manager; see Importing and Exporting Notes Using Text Files.
Note:  Support for text Notes on series slot timesteps (“Annotations” or just “Notes”) was redesigned in RiverWare 5.2. Notes are still organized within Note Groups, but notes are now directly applied to individual series slot timesteps rather than by associating their containing Note Groups with whole series slots. Additionally, multiple notes can be associated with a timestep on an individual series slot.
Notes
A Note is a text string that is associated with a series slot at a timestep and each note belongs to a Note Group. A Note has the following properties:
• Note text. The text string that makes up the Note.
• Note group membership. A note belongs to exactly one Note Group.
• Slots and timesteps. A note is applied to one or more series slots at specified timesteps
Note Groups
A Note Group is composed of the following properties:
• Name. a name is generally provided by the user.
• Icon Color. A note group has one of eight basic colors.
• Set of Notes. A Note Group has a set of one or more text Notes.
Displaying and Editing Notes
Note text can be seen and reviewed in the series slot dialogs. In the series slot dialogs (for Series Slots, Agg Series Slots, Multi Slots, Table Series Slots and Edit Account dialogs), the presence of a note is shown by a small icon to the left of the value. The color of the icon is defined for the Note Group. Hovering over the icon displays a tooltip with the Note text.
Cells having more than one note have a special icon suggesting one note stacked on the other. The tooltip lists each note, one per line. That icon is always yellow and does not reflect the color of any of the corresponding Note Groups.
The note text can be shown in a separate column using the View, then Show Notes Column toggle menu item.
Note:  You can configure your preferences on whether or not to show the Notes column using Slot Dialog Display Preferences; see Slot Dialog Display Preferences.
If the Notes Column is visible and the open slot belongs to one and only one Note Group, a new note can be created by simply typing in the Notes Column. The Note will be created as a member of the slot’s Note Group.
When one or more notes exist on a particular Slot/Timestep, the context menu (right-click) on the cell includes a menu for each note; see Figure 5.45. The title of the menu shows the Note Group icon and the Note Text. The menu contains the following operations:
• Copy Note. The Copy Note menu item copies a Note reference to the Note Copy Buffer. In Figure 5.45, the “Max Flow in Run” note would be copied to the buffer. The note can then be pasted in one or more cells using the Paste Note operations.
• Edit Note. The Edit Note menu item shows the Note Group Manager Dialog, with the indicated Note preselected. You may change the note text, or move the note to a different Note Group (potentially having a different Note Group icon).
• Remove Note. The Remove Note menu item removes the indicated note from the selected Slot/Timestep (only). This does not effect the appearance of the same note at other timesteps on the same Slot, or on any other Slot.
Figure 5.45   
The dialog can be scrolled to the timestep of a note on the Slot using the Note Navigation menu button; see Figure 5.46. Items in the Note Navigation menu having a bullet indicate that the timestep of the note matches that of the timestep selector.
Figure 5.46   
Pressing the Shift key while selecting an item causes a Global Time Scroll (scrolling all open series-related dialogs to the corresponding timestep).
Creating Notes
Following are three ways to create a note:
• In an open series slot dialog, edit account dialog or SCT:
– Right-click a cell.
– Select Add Note from the context-sensitive pop-up menu. This will open the Note Group Manager; see Note Group Manager Dialog for details.
– Choose or create a Note Group.
– Choose or create the Note text.
– Choose the slots and timesteps to which the note should apply by selecting the Add Entry Using Context button. This opens the Apply Notes to Slots dialog; see Apply Note to Slots Dialog for details. The slot and timestep from which this right-click operation began are selected.
– Change/add slots or timesteps (if necessary) and select Ok to associate the Note with the slot/timestep.
• From the main workspace:
– Choose the Utilities, then Note Group Management menu. This opens the Note Group Manager dialog; see Note Group Manager Dialog.
– Choose or create a Note Group.
– Choose or create the Note text.
– Select the Add Slot Entries button to open the Apply Notes to Slots dialog; see Apply Note to Slots Dialog.
– Select the Add Slots button and choose the slots to which the note applies.
– Specify the timestep or range of timesteps to which the note applies.
• To create a note based upon an existing note (copy/paste of note). In an open series slot dialog, edit account dialog or SCT:
– Right-click in a cell that has the desired noted.
– Select the note from the context-sensitive menu and choose Copy Note.
– Go to the destination slot and timestep and right-click in the cell.
– Choose Paste Note: Name.
Note Group Manager Dialog
The Note Group Manager and supporting dialogs are used to maintain the set of notes on series slots.
This dialog is arranged vertically in three hierarchically defined panels as shown in the following figure: Note Groups, Notes, and Slots. The first two panels can show either a list or a menu, controlled by the triangle arrow button in each panel. The combo boxes allow for the selection of a single item (Note Group or Note), or “All” items.
The panels are used in a top to bottom order. First you select (highlight) one or more Note Groups. Then the member Notes are displayed in the Notes panel. Then you select one or more Notes in the Notes panel and the member slots and timesteps are displayed in the Slots panel.
Following is a description of these three panels.
Figure 5.47   
Note Groups Panel
The Note Groups panel shows all the defined Note Groups and supports the following operations (buttons):
• Create Group
• Edit Selected Group
• Delete Selected
The first three buttons bring up dialogs for creating (define the name and icon color) or editing (changing the name and icon color), or confirming deletion of Note Groups.
Notes Panel
For the selected Note Group in the above panel, the Notes panel shows the notes that are a member of that group. It supports three operations (buttons):
• Create Note. Enter a new Note text and choose the Note Group to which it belongs.
• Edit Selected Note. Edit existing Note text or change the Note Group to which it belongs.
• Delete Selected Notes. Delete the selected Note after confirmation.
Slots Panel
For the selected Notes in the middle panel, the Slots panel shows the slots and timesteps to which the note has been applied.
Both the Add Slot Entries and Add Entry Using Context buttons bring up the Apply Notes to Slots dialog described in the next section. These differ only in the initial selections used in that dialog. The Add Entry Using Context button is available when the manager dialog is shown from the context of a particular slot and timestep, i.e. right-clicking a cell in a slot or SCT then choosing Add (or Edit) Note. The current context (Object.Slot and Timestep) is listed on the same line as the button.
Apply Note to Slots Dialog
The Apply Note to Slots dialog allows the user to associate a particular note with one or more Slots at one or more contiguous timesteps.
The list of slots and the timestep selections are sometimes preselected, depending on how the Apply Note to Slots dialog is shown. These selections can be modified before creating the new Note/Slot/Timestep associations.
The Group and Note combo boxes can be modified to select a different note. Only one note can be selected at any one time.
Additional Slots can be added to the Slot List by selecting the Add Slots button. This brings up the RiverWare Slot Selector.
Slots can be removed from the Slot List by selecting items in the list and selecting the “Remove Selected Slots” button. Doing so has no effect on any existing Note/Slot/Timestep associations.
In the Timesteps section, the user can choose one timestep or range of timesteps (continuous only) to which the note will apply.
The OK or Apply buttons are enabled only if the inputs specify a valid state representing Note/Slot/Timestep associations that are not yet existing. For one thing, all of the Slots in the Slot list must have the same timestep size. If enabled, the OK and Apply buttons create a Note/Slot/Timestep association for all of the Slots in the list (i.e. not just the selected Slot items).
Status lines under the Slot List and above the bottom buttons indicate the state of the inputs. Examples of the various messages shown in the bottom status line are as follows. (The OK and Apply buttons are enabled only in the 4th example):
• No defined Note is selected.
• The Slot list is empty.
• The Slot list includes Slots having different timestep sizes.
• Apply selected note to 6 Slot/Timesteps [enabled state]
• The selected note has been applied to 6 Slot/Timesteps.
Collected Notes on Expression Slots
Collected notes are a special type of note associated with series expression slots (i.e. Series Slot with Expression). When the expression slot is evaluated, notes from the series slots referenced in its expression (“source” slots) are copied to corresponding timesteps in the expression slot. The source slots for providing notes are an accumulated list of the source slots referenced across the expression slot’s evaluations at all timesteps. The notes from the source slots are collected and copied once at the end of the expression slot’s evaluation. The collected notes are removed and re-collected each time the expression slot evaluates. In the context of a run, they are removed at the beginning of the run and collected at the end of the run, so if the run is paused or aborts in the middle, the collected notes will be absent.
The collection of notes for series with expressions is optional and is controlled on a model-wide basis by a parameter selection in the RPL Parameters dialog. This dialog is available from the RiverWare workspace under the Policy menu.
In the places where notes for series can be displayed (Series Slot, SCT and Notes Group Manager dialogs), collected notes are differentiated by having a C in their icon; see Figure 5.48. The text of a collected note, where displayed in the notes column or in a tool tip when mousing over a note icon, will show the text of the note followed by the source slot name in parentheses.
Note:  If a note is propagated through a number of expression slots, the slot where the note originated is maintained as the source slot for the note, even though one expression slot may be picking it up from another expression slot that referred to the source slot.
The context menu (right-click) on a cell for a collected note in the series slot and SCT dialogs will have an additional menu entry showing the source slot of the collected note. Select the item to open the source slot’s dialog. If a source slot is deleted from the model, the collected notes that refer to that source slot will also be deleted.
Figure 5.48   
Accounting Multi Slot Notes
Accounting multi slots, such as storage account inflow or outflow, have a subslot for each supply linked to the multi slot. You can add a note to the multi slot or the supply/subslot.
Note:  It is good practice to add the note to one of the linked supplies.
When you add a note to a multi slot that has one or more subslots or supplies, a confirmation asks you which you would like to use.
When a note is added to a linked supply, the note is automatically propagated to the multi slots on either end of the supply. Notes propagated in this way are assigned a source slot corresponding to the supply. The display of the propagated note is similar to collected notes (see Collected Notes on Expression Slots), where the source slot name is displayed in parentheses after the note text in the notes column, and the right-click context menu contains an item for the source slot that, when selected, will open the source supply’s slot dialog. When a note on the supply is deleted, or the supply itself is deleted, propagated notes will be removed from the corresponding accounting multi slots.
Importing and Exporting Notes Using Text Files
Notes can be imported or exported to a text (xml) file. The export/import functionality allows notes made in a copy of a model to be transferred back into the original.
Selecting the Import or Export Selected buttons brings up a file selector to specify an import or export file for Note Groups. These operation are also available from menu items in the File menu at the top of the dialog. Exporting one or more selected Note Groups will write information to the file for the group, its notes, and the slot associations for those notes. On import from a file, a Note Group is created if it does not already exist, notes in the group are created if they do not already exist, and slot associations for the notes are created if they do not already exist. A feedback dialog will indicate if note associations with slots cannot be made (i.e. if the slot is not in the new model).
Exporting Notes Using DMIs
Notes can be output from RiverWare slots to data files using control file-executable DMIs. The control file keyword used to specify notes is as follows:
slot_anno = true
The default value for slot_anno (i.e. slot annotations) is false, meaning no Notes will be written.
A line in RiverWare time series format (for DMI import or from DMI export) containing a note will be formatted as:
<value> anno {Storm Events} {4.3 Inches}
where <value> will be a numeric value, “anno” is a keyword, Storm Events defines the Note Group to which the note belongs and 4.3 Inches is the note itself. The “<“a “>” will not exist in actual output. The “{” and “}” do exist, delimiting the Note Group name from the note text itself.
Note:  In the external RiverWare time series format, only one Note will be supported at one given timestep on any one SeriesSlot. That is, if a given SeriesSlot is a member of more than one (say, two) Note Groups, and if both of those Note Groups have a Note at the same timestep (say, 2-13-2007), then only ONE of those Notes will be preserved in the DMI operation.
Revised: 07/17/2020