National Weather Service/Office of Hydrologic Development (OHD) Design Spec Ex1.
0 – 07/31/2008
Example using excerpts from AWIPS OB8.2 IVP Project – Design Specification
NATIONAL WEATHER SERVICE
OFFICE of HYDROLOGIC DEVELOPMENT
EXAMPLE DESIGN SPECIFICATION
Version 1.0
07/31/08
National Weather Service/Office of Hydrologic Development (OHD) Design Spec Ex1.0 – 07/xx/2008
Example using excerpts from AWIPS OB8.2 IVP Project – Design Specification
Revision History
Date Version Description Author
07/28/2008 1.0 Initial Version SISEPG
ii Version X.X
MM/DD/YY
National Weather Service/Office of Hydrologic Development (OHD) Design Spec Ex1.0 – 07/xx/2008
Example using excerpts from AWIPS OB8.2 IVP Project – Design Specification
TABLE OF CONTENTS
Page
REVISION HISTORY...................................................................................................................................................II
TABLE OF CONTENTS...........................................................................................................................................III
DESIGN SPECIFICATION EXAMPLE....................................................................................................................1
1 OVERVIEW.........................................................................................................................................................1
2 ARCHITECTURE...............................................................................................................................................2
2.1 CURRENT OB7.2 DESIGN...............................................................................................................................2
2.2 PROPOSED OB8.2 DESIGN.............................................................................................................................2
3 DESIGN................................................................................................................................................................6
3.1 PAIRING WITH PROCESSED VALUES..............................................................................................................6
3.1.1 Requirements Traceability Matrix or List.................................................................................................6
3.1.2 Software Design........................................................................................................................................6
3.1.3 User Interface Design.............................................................................................................................11
[Link] The Verification Group Manager..................................................................................................................11
3.1.4 Data Design – Archive Database Changes............................................................................................13
4 OTHER INTERFACES.....................................................................................................................................14
4.1 INTERFACE 1................................................................................................................................................14
4.2 INTERFACE 2................................................................................................................................................14
5 OTHER DESIGN FEATURES.........................................................................................................................14
6 REFERENCES...................................................................................................................................................14
7 APPENDICES....................................................................................................................................................14
Appendix A – Design Diagrams...............................................................................................................................14
iii Version X.X
MM/DD/YY
National Weather Service/Office of Hydrologic Development (OHD) Design Spec Ex1.0 – 07/31/2008
Example using excerpts from AWIPS OB8.2 IVP Project – Design Specification
Design Specification Example
This example design specification is a companion to the Design Specification Template and is
not intended to be used alone. The example text was taken from a real project (written prior to
the creation of the template format). Certain sections are used to provide an idea of what should
go into the template sections which may need design dependant subsections. The approach to this
example was to identify a theme and to connect it through the software design, data design, and
interface design sections at a high level. The detail would be left to the developer to establish
subsections as directed in the template. Gray-out text from the source is not further discussed in
this example.
Original text is modified where needed for relativity to this document (e.g., section numbers,
Appendix letters, etc.). When this is done in sentences or text is inserted, it will be italicized and
underlined like this to show it was not part of the original text.
1 Overview
The enhancements to be made to the verification software for OB8.2 are documented in the
HOSIP CONOPS and Requirements Specification Document, and the design components needed
to satisfy these new requirements can be broadly classified into the following groups:
Additional data types
Pairing with processed data
New verification metrics
Special plots
ChartDirector change
Comparison variable
New variables used to select pairs
Confidence intervals
Vfyruninfo Editor enhancements
IVP Batch Builder upgrades
Design improvements
Miscellaneous changes
Section 2.0 provides the general, overall design of the verification software. Sections 3.0 and
later describe the design of software, data, and interface changes to be made for each group of
requirements. The complete design diagrams can be found in Appendix A. [NOTE: Developers
may integrate the diagrams within the document or in an appendix as needed]. In the
following sections, references to the design diagrams will be provided based on their diagram
numbers.
[NOTE: For this example, only the Software Function Category in bolded highlighted text
in the list is the thread or design theme discussed in subsequent sections, (i.e., forecast-
observed pairs at some location which acts as part of a verification group per the
application example.]
1 Version 1.0
07/31/08
National Weather Service/Office of Hydrologic Development (OHD) Design Spec Ex1.0 – 07/31/2008
Example using excerpts from AWIPS OB8.2 IVP Project – Design Specification
2 Architecture
The high-level design of the Interactive Verification Program (IVP) for the AWIPS OB8.2
release does not differ much from that for the AWIPS OB7.2 release. An outline of the designs
for OB7.2 and OB8.2 are provided in the next two sections.
2.1 Current OB7.2 Design
The system design of the OB7.2 verification software includes the following:
Written in Java 1.5
Forecast, observed, and processed data, verification forecast-observed pairs, and some
location parametric information are stored in the archive database on the AWIPS RAX
machines.
o Forecast data is stored in the pedfsep table.
o Observed data is stored in the pecrsep table.
o Processed data is stored in pehpsep table.
o Forecast-observed pairs are stored in the vfypairs table.
o Verification location parametric information is stored in the vfyruninfo table.
o Critical stages are stored in the rivercrit table.
o RFC identity is stored in the location table.
o Verification add-adjustment factors are stored in the vaddadjust table.
Database access is provided by the JDBC API
o Incorporates a postgres driver.
The batch file interface, via the IVP Batch Program, provides the user the ability to (1)
build pairs, (2) set parameters of a verification run, (3) compute verification statistics, and
(4) generate graphics.
o Commands are used to define parameters that specify what data to pair, what data
to verify, how to do the verification, and how to build the graphic.
o Actions are used to perform some kind of action, including building forecast-
observed pairs, calculating statistics, and generating a graphic.
The graphical user interface, via the IVP, provides tools to manage the same parameters
provided in the batch file interface.
o Internally, the GUI defines command token values corresponding to batch file
commands and then executes actions as needed.
o For a particular graphic, the GUI can be used to create a batch file for the IVP
Batch Program that, when executed, will generate the same graphic and save it to
a file.
Chart rendering is done using JClass DesktopViews.
Charts may be saved to files in PNG or JPEG format.
2.2 Proposed OB8.2 Design
The system design of the OB8.2 verification software includes the following (changes from
OB7.2 are in red):
Written in Java 1.5
2 Version 1.0
07/31/08
National Weather Service/Office of Hydrologic Development (OHD) Design Spec Ex1.0 – 07/31/2008
Example using excerpts from AWIPS OB8.2 IVP Project – Design Specification
Forecast, observed, and processed data, verification forecast-observed pairs, and
some location parametric information are stored in the archive database on the
AWIPS RAX machines.
o Forecast data is stored in the pedfsep, pehfsep, and peqfsep tables.
o Observed data is stored in the pecrsep, pedrsep, and peoosep tables.
o Processed data is stored in pehpsep, pedpsep, peqpsep, and peoosep tables.
o Forecast-observed pairs are stored in the vfypairs table.
o Location parametric information is stored in the vfyruninfo table.
o Critical stages are stored in the rivercrit table.
o RFC identity is stored in the location table.
o Verification add-adjustment factors are stored in the vaddadjust table.
Database access is provided by the JDBC API
o Incorporates a postgres driver.
The batch file interface, via the IVP Batch Program, provides the user the ability to
(1) build pairs, (2) set parameters of a verification run, (3) compute verification
statistics, and (4) generate graphics.
o Commands are used to define parameters that specify what data to pair, what
data to verify, and how to do the verification.
o Actions are used to perform some kind of action, including building forecast-
observed pairs, calculating statistics, and generating a graphic.
The graphical user interface, via the IVP, provides tools to manage the same
parameters provided in the batch file interface.
o Internally, the GUI defines command token values corresponding to batch file
commands and then executes actions as needed.
o For a particular graphic, the GUI can be used to create a batch file for the IVP
Batch Program that, when executed, will generate the same graphic and save it
to a file.
Chart rendering is done using ChartDirector Version 4.0.
Charts may be saved to files in PNG or JPEG format.
3 Version 1.0
07/31/08
National Weather Service/Office of Hydrologic Development (OHD) Design Spec Ex1.0 – 07/31/2008
Example using excerpts from AWIPS OB8.2 IVP Project – Design Specification
4 Version 1.0
07/31/08
National Weather Service/Office of Hydrologic Development (OHD) Design Spec Ex1.0 – 07/31/2008
Example using excerpts from AWIPS OB8.2 IVP Project – Design Specification
5 Version 1.0
07/31/08
National Weather Service/Office of Hydrologic Development (OHD) Design Spec Ex1.0 – 07/31/2008
Example using excerpts from AWIPS OB8.2 IVP Project – Design Specification
3 Design
3.1 Pairing With Processed Values
Pairing with processed values refers to forecast-observed data pairs that are generated where the
observation comes from one of the tables accessed by the processed decoder on the RAX
machines. This includes the pehpsep, pedpsep, and peqpsep tables.
Description
For pairing, through the new command OBS_TYPE, the user will be able to specify if pairs are to
be constructed using either raw values, processed values, or both, independently (requiring two
separate executions of the pairing algorithm, with the OBS_TYPE being different).
For statistics computation, both raw and processed pairs can be used independently (by defining
the verification location twice, with the OBS_TYPE being different). However, since each
location can only be defined once within a verification group, raw and processed pairs for one
location may not be grouped or lumped together to compute one set of statistics.
For graphics, because building the plots depend upon identifying a location uniquely by its lid
and SHEF forecast pedtsep, a single graphic built using the GUI cannot display statistics
computed for the raw pairs and the processed pairs for one location simultaneously. Only one or
the other can be used. In batch mode, if the location is defined twice for the different
OBS_TYPE values, then the later definition takes precedence.
3.1.1 Requirements Traceability Matrix or List
The following new or changed requirements are part of this group:
[Link]
3.1.2 Software Design
The following changes will be made to facilitate the software requirement(s):
The PairingProcessor class will be updated so that the insert statement to insert new pairs
will use the appropriate table based on the OBS_TYPE token value.
The PairingBatchProcessor will have the new batch command OBS_TYPE added, which
must be either “PROCESSED” or “RAW”.
The VerificationLocation class will be changed to include a new attribute to be associated
with a verification location. The new attribute is _observationType and will have one of
three values:
o “PROCESSED”
o “RAW”
This field will tell the VerificationProcessor whether to load pairs constructed using processed or
raw table data.
6 Version 1.0
07/31/08
National Weather Service/Office of Hydrologic Development (OHD) Design Spec Ex1.0 – 07/31/2008
Example using excerpts from AWIPS OB8.2 IVP Project – Design Specification
The LocationBatchProcessor will have the new batch command OBS_TYPE added, as
well, which will be used to specify the value of _observationType within the
VerificationLocation class.
The VfypairsDataHandler class will be changed to determine which table to query based
on passed in parameters or the new _observationType attribute of the
VerificationLocation class.
The VerificationLocationJTableRowData classes will have a column added to the table
with the name ‘obstype’. The column will have one of two values, depending on the
location’s _observationType attribute setting: “proc” (for “PROCESSED”) or “raw”.
A new button will be added to VerificationLocationMgr that will spawn a
GenericRadioButtonSubCommandPanel. This panel will be used change the setting of
the obstype column for all of the currently selected rows of the table.
Appendix A: See Refer to the BatchProcessor diagram (Diagram 1), PairingProcessor
diagram (Diagram 2), VerificationProcessor diagram (Diagram 3), and
VerificationLocationMgr diagram below (Diagram 4).
7 Version 1.0
07/31/08
National Weather Service/Office of Hydrologic Development (OHD) Design Spec Ex1.0 – 07/31/2008
Example using excerpts from AWIPS OB8.2 IVP Project – Design Specification
8 Version 1.0
07/31/08
National Weather Service/Office of Hydrologic Development (OHD) Design Spec Ex1.0 – 07/31/2008
Example using excerpts from AWIPS OB8.2 IVP Project – Design Specification
9 Version 1.0
07/31/08
National Weather Service/Office of Hydrologic Development (OHD) Design Spec Ex1.0 – 07/31/2008
Example using excerpts from AWIPS OB8.2 IVP Project – Design Specification
10 Version 1.0
07/31/08
National Weather Service/Office of Hydrologic Development (OHD) Design Spec Ex1.0 – 07/31/2008
Example using excerpts from AWIPS OB8.2 IVP Project – Design Specification
3.1.3 User Interface Design
This document section provides descriptions of how the user interface will change in order to
satisfy the requirements outlined for AWIPS OB8.2 delivery of the RFC verification software
suite. For the OB7.2 software, the user interface is described in the User’s Manuals, found at
[Link]
Each sub-section that follows describes changes required to either a window of the Interactive
Verification Program or the batch language used in the IVP Batch Program. Where possible,
snapshots of a new prototype display will be provided.
[Link] The Verification Group Manager
The Verification Group Manager must change to allow the user to input the following
information:
Issuance time-of-day interval and subinterval
Active/in-active (or both) flag
The issuance time-of-day interval will be specified in a manner analogous to how the lead time
intervals are specified. However, the spinner will only allow values from 0 to 24, and the choice
box will only include NONE or hours (hour and hr, as well). The active/in-active flag, which
restricts which locations are included in the verification group, will be set via radio buttons.
11 Version 1.0
07/31/08
National Weather Service/Office of Hydrologic Development (OHD) Design Spec Ex1.0 – 07/31/2008
Example using excerpts from AWIPS OB8.2 IVP Project – Design Specification
Figure 1a: Screenshot of Verification Group
Managers for OB7.2.
Figure 1b: Prototype screenshot of Verification
Group Manager for OB8.2.
12 Version 1.0
07/31/08
National Weather Service/Office of Hydrologic Development (OHD) Design Spec Ex1.0 – 07/31/2008
Example using excerpts from AWIPS OB8.2 IVP Project – Design Specification
Also, the persistence and physical element parts of the window will be removed. The user will
still be able to specify if persistence forecasts are to be used by including the type source ‘FR’ in
the Forecast Type Sources text field, or setting it to ‘ALL’. As for physical elements, the user
can specify the physical elements by choosing appropriate locations via the Verification Location
Manager.
Screenshots of the OB7.2 Verification Group Manager and a prototype OB8.2 Verification Group
Manager are provided in Figures 1a and 1b.
3.1.4 Data Design – Archive Database Changes
A new table called vfyprocpairs will be added to the archive database. It will have the exact
same schema as vfypairs, but will store only those pairs constructed from processed (as opposed
to raw) values. In other words, it will store pairs when the command OBS_TYPE set to
‘PROCESSED’.
This is being done to address the problem that pairs constructed using observed values must not
overwrite those constructed using processed values in order for requirement [Link] to be
satisfied. However, they still need to be able to overwrite pairs constructed using other observed
values, in case the new observed value is preferable (based on its sensor type) or the old
observed value is removed. There were two identified solutions: (1) add a column to vfypairs
that records if the pair is build using observed or processed values, and (2) create a new table to
store processed values. Option 2 has been selected due to simplicity of development.
The following fields will be added to the vfyruninfo table:
dur: The forecast point’s duration code
extremum: The forecast point’s extremum code
active: A binary field defining if the forecast point is active or not.
national: A binary field defining if the forecast point is to be used in computing national
statistics.
The dur and extremum fields will become part of the primary key, since they, along with the
location id and physical element, uniquely define a forecast point or location. Furthermore, the
forecast type source will also become part of the key, so that it is possible to have different
sensor preferences for each forecast type source. Previously, all forecast type sources for a given
forecast point had to have the same sensor preference list.
Vfyruninfo Table Classes
The VfyruninfoRecord and VfyruninfoTable classes will be enhanced to read in and process the
new dur, extremum, active, and national fields of the vfyruninfo table. The
VfyruninfoTableModel class will be enhanced to display columns for all of the new fields in the
table within the Vfyruninfo Editor. Other classes of the Vfyruninfo Editor will be enhanced, as
needed, to account for the new columns. Lastly, the rows of the VfyruninfoTableModel class
will be defined so that the forecast type source becomes part of the key for a given row, implying
each row will have a single forecast type source.
13 Version 1.0
07/31/08
National Weather Service/Office of Hydrologic Development (OHD) Design Spec Ex1.0 – 07/31/2008
Example using excerpts from AWIPS OB8.2 IVP Project – Design Specification
Other Database Classes - Description and reference to diagram
Data Handler Classes - Description and reference to diagram
Pairing Algorithm Class - Description and reference to diagram
Verification Location Classes- Description and reference to diagram
Other Batch Classes - Description and reference to diagram
GUI Classes
Chart Classes
All drawn charts must be enhanced so that the labels match the data types. Previously, all data
types were assumed to be stage. Now, it must be flexible based on the SHEF physical element of
the data. Additionally, the units must be displayed for all axes. The class ArchiveDataType will
be created which provides unit information based on the physical element of the pairs data.
4 Other Interfaces
4.1 Interface 1
4.2 Interface 2
5 Other Design Features
6 References
Document Document Title Date Author
No.
7 Appendices
Appendix A – Design Diagrams
14 Version 1.0
07/31/08