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:

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 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:

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:

A Note Group is composed of the following properties:

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.

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:

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.

Pressing the Shift key while selecting an item causes a Global Time Scroll (scrolling all open series-related dialogs to the corresponding timestep).

Following are three ways to create a note:

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.

The Note Groups panel shows all the defined Note Groups and supports the following operations (buttons):

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.

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):

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.

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):

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.

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.

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.

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.

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).

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:

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: