Office of Water Quality Technical Memorandum 2006.03
SUBJECT: National Water Information System-- Notice of enhancements planned for the QWDATA software that will affect NWIS QWDATA batch file
This memo describes enhancements planned for the National Water Information System (NWIS) affecting laboratory and field software that formats data for batch entry into NWIS through the QWDATA subsystem. These enhancements affect the format and content of the batch files used to load laboratory and field data and affect supporting reference tables used in NWIS. The new batch file format will be included in the release of NWIS QWDATA version 4.6, scheduled for September 2006.
Anyone associated with laboratory and field software that formats data for entry into NWIS should understand the upcoming changes and their implications. There are specific tasks that need to be completed prior to installation of the NWIS 4.6 software. Some tasks can be completed by personnel in USGS laboratories that provide NWIS batch files to Water Science Centers (WSC), and other tasks will require assistance from WSC Water-Quality Specialists and/or NWIS database administrators.
Laboratories must be prepared to modify their batch file formats and the file content, and Water-Quality Specialists and NWIS database administrators need to prepare for the installation by cleaning up selected records in the NWIS QWDATA database, and request any new codes that are required.
Brief description of laboratory tasks:
In preparation for the transition from NWIS 4.5 to NWIS 4.6, your assistance is requested in reviewing the contents of the analyzing entity reference table so that we can ensure all laboratories and agencies that provide data to NWIS have codes assigned before the transition. Requests for new codes and updates must be submitted by June 2, 2006.
Laboratories need to make plans to revise their batch file output format
and must coordinate these changes with the NWIS installation plans. Details about the required changes and their implications follow.
Identification of the agency that collected a sample is an important piece of meta data stored in the NWIS database. Sampling protocols are documented by the USGS and other agencies that collect data for the USGS, and storage of collecting agency information in NWIS allows users to infer what protocols were used to collect the data.
The collecting agency is currently (in NWIS 4.5) identified using the fixed-value parameter code 00027 "Collecting Agency". The most common data-collection scenario is: only one agency is associated with the collection of a particular sample; although, a sample may be composed of results that were determined in multiple laboratories. Because collecting agency information usually applies to an entire sample, this information will no longer be stored under parameter code 00027, but instead will be stored in a new sample-level field in QWDATA.
Implications for laboratories: Laboratories are not expected to provide codes for the collecting agency in NWIS batch files. This field will be populated by the WSCs.
Implications for Water Science Centers: If your WSC stores samples in NWIS that are collected by another agency, please review the current list of agency codes for parameter code 00027 in Appendix B of the QWDATA User’s Manual at: http://wwwnwis.er.usgs.gov/currentdocs/qw/QW.user.book.html to determine if an agency code already exists. These codes will be used to populate the new collecting agency reference table. Instructions for requesting new codes are provided below.
Default Setting: A NWIS system file called “qw.conf” must be edited as part of NWIS 4.6 installation to define the default collecting agency. NWIS installation instructions, will be provided when the software is released, and will include details on how to edit this file. The “qw.conf” file will determine the default collecting agency code to be used during interactive and batch updates of water-quality data.
The Office of Water Quality recommends that when QWDATA 4.6 is installed, samples collected by USGS Water Resources Discipline (WRD) personnel be coded with "USGS-WRD" in the collecting agency field. This code corresponds to the current fixed-value result of "1028" for parameter code 00027.
Batch File Format: The new field for collecting agency will be added to the end of the “qwsample” format file and will not be included in the 1 and * card format files.
Reference Lists: Parameter code 00027 will be removed from the Parameter Code Dictionary, the fixed-value table, and the parameter-method table. During transfer of the software from version 4.5 to 4.6, this parameter code will be removed from the “field forms” used within QWDATA.
Analyzing entity information needs to be stored in QWDATA to: (1) retain
meta data that may be helpful in explaining variations in the observed
results; (2) identify possible variations in protocols used by different
analytical laboratories that may help explain differences in results; (3)
give proper credit to non-USGS partners when presenting their data to other
users; (4) provide the basis for retrieving (or excluding) results analyzed
by particular laboratories; (5) count the number of analyses of particular
analytes performed by various laboratories; and/or (6) provide traceability
of results to the analytical source of the data. These meta data also help
make NWIS compliant with USGS information-quality guidelines (section III.5), mandated by the Office of Management and Budget.
Identification of the laboratory (entity) that analyzed a sample and produced a particular result is currently stored in the fixed-value parameter code 00028 "Analyzing Agency". However, more than one laboratory may be used to analyze a sample and the current database design only allows one value for parameter code 00028 per sample. Therefore, in the NWIS 4.6 release of QWDATA, analyzing entity information will be stored in a new field at the result level. This enhancement will allow the identification of all entities that provided results for a sample.
Implications for laboratories: NWIS batch files for laboratory results must include the appropriate new 8-character code for the analyzing entity in the new result-level field for every result analyzed by the laboratory. This new field will be added to the end of the tab-delimited “qwresult” file and will not be included in the 1 and * card format files.
Once the software is released, laboratories should continue to send
parameter code 00028 in the batch files along with the new analyzing entity
codes until all USGS WSCs have installed the NWIS 4.6 software, which is
scheduled to be by the end of October 2006. This will ensure that
analyzing entity information is not lost in the interim period between the
release of the software and its installation at all NWIS locations.
Laboratories must include the new analyzing entity codes in the result
files no later than December 2006.
Please review the current list of agency codes for parameter code 00028 in Appendix B of the QWDATA User’s Manual at http://wwwnwis.er.usgs.gov/currentdocs/qw/QW.user.book.html to determine if an agency code for your laboratory already exists. These codes will be used to populate the new analyzing entity reference table. Instructions for requesting new codes are provided below.
Implications for Water Science Centers: The analyzing entity for field
measurements such as temperature, specific conductance, turbidity, and
bacteria should be “USGS-WRD.” If the WSC also has an analytical
laboratory for non-field measurements, then a unique analyzing entity code
must be requested for that laboratory. If another entity is collecting
field data for entry into NWIS, the WSC must make sure that an appropriate
analyzing entity code is available by reviewing Appendix B of the QWDATA
The one-character method code will be replaced with a 5-character method code to increase the number of possible method codes for a parameter. Also, additional reference tables will be created in NWIS and multiple parameter codes will be able to point to the same method code. The QWDATA software will be revised to store and retrieve additional meta data about each method.
Implications for laboratories: The current field in the “qwresult” file for method code will accept both existing one-character method codes and the new 5-character method codes. The one-character codes will be translated into the new 5-character code by the QWDATA software. Newly-requested codes will be assigned a 5-character code instead of a 1-character code. Laboratories will also be asked to provide additional meta data for new methods, including expanded method citation information and method descriptions.
Implications for Water Science Centers:
Most field methods do not have assigned method codes, but the Office of
Water Quality will begin establishing field method codes for selected
parameters. The format and content of the “field forms” used in QWDATA
will be modified when the software is upgraded, as described in the
transfer section below.
SELECTED ACTIONS TO BE TAKEN DURING TRANSFER FROM NWIS 4.5 TO NWIS 4.6
Early versions of QWDATA did not validate the fixed-value results for parameter codes 00027 and 00028 and invalid fixed-values currently exist in the databases. Some of these codes are obvious coding errors while some codes may have been valid at one time but were somehow deleted from the fixed-value file.
During the transfer from NWIS 4.5 to NWIS 4.6, invalid fixed-values for parameter codes 00027 and 00028 will be removed from results stored in all NWIS databases. To minimize the potential loss of information that may be contained in invalid codes, a pre-transfer software program will be provided to NWIS database administrators and Water-Quality Specialists prior to the release of NWIS 4.6. This program will identify invalid results for parameter codes 00027 and 00028 and, in some cases, suggest alternate valid codes for these results. Output from this program should be used to clean up the results before the transfer so that important sample meta data are not lost. The program and detailed instructions on its use will be provided in a separate communication.
“Field forms” used by the QWDATA software, and located on NWIS servers at
/usr/opt/nwis/data/auxdata/qw_field_forms, will be modified during transfer
to remove parameter codes 00027 and 00028 and to convert the 1-character
method code to the new 5-character code. After the NWIS 4.6 software is
installed, WSCs may add specific analyzing entity codes to the forms, if
desired. Format specifications for the field form can be found at
NEW BATCH FILE FORMAT
The new and modified fields described above result in minor modifications to the existing batch file formats. The revised format for the "qwsample" file is shown at http://phoenix.cr.usgs.gov/mockups/batch_sample4.6.doc. The revised "qwresult" file is at http://phoenix.cr.usgs.gov/mockups/batch_result4.6.doc.
HOW TO REQUEST NEW CODES
The forms for requesting new or modified parameter and method codes, as well as new collecting agency and analyzing entity codes will be modified to accommodate these changes. The Parameter and Method Code Request Form is located at http://water.usgs.gov/usgs/owq/parm_request.html.
Collecting Agency/Analyzing Entity: Provide a suggested name for the entity, using a maximum of 59 characters. An 8-character short code will be assigned to this entity and the code and name will be added to the NWIS reference table. The NWIS reference tables and QWDATA User Documentation will be updated quarterly after the software is initially released.
Detailed requirements documents describing these NWIS QWDATA software changes provide additional information:
Sample collecting agency:
Please contact Yvonne Stoker (email@example.com) for more information or email firstname.lastname@example.org.
Donna Myers /s/ for Timothy L.
Chief, Office of Water Quality
This memorandum does not supersede any other Office of Water Quality Technical Memorandum.
A, B, DC, AO,
WSC and Regional Water-Quality Specialists (email@example.com)
NWIS Water-Quality DBAs (GS-W NWIS DBAS)
Greg Mohrman, Chief, NWQL (firstname.lastname@example.org)
Terry Schertz, Chief, Branch of Quality Systems (email@example.com)
Marina, CA- Allan Mlodnosky (firstname.lastname@example.org)
Vancouver, WA – Dan Gooding (email@example.com)
Iowa City, IA – Pam Smith (firstname.lastname@example.org)
Baton Rouge, LA – Cheryl Joseph (email@example.com)
Louisville, KY – Elizabeth Shreve (firstname.lastname@example.org)
Rolla, MO – Miya Barr (email@example.com)
Helena, MT – Kent Dodge (firstname.lastname@example.org)
Albuquerque, NM – Robert Gold (email@example.com)
Donna Francy, Ohio Microbiology Lab (firstname.lastname@example.org)
Rebecca Bushon, Ohio Microbiology Lab (email@example.com)
Branch of Regional Research, Eastern Region – Pierre Glynn (firstname.lastname@example.org)
Branch of Regional Research, Central Region – Mike Reddy (email@example.com)
Branch of Regional Research, Western Region – Steve Ingebritsen (firstname.lastname@example.org)
Reston Isotope Lab (email@example.com)
National Research Program, Trace Metals, Boulder, CO (firstname.lastname@example.org)
National Research Program, Denver, CO (email@example.com)
National Research Program, Menlo Park, CA (firstname.lastname@example.org,
email@example.com, firstname.lastname@example.org, email@example.com)
National Research Program, Natural Organic Matter (cerostad)
Geologic Discipline, X-ray Diffraction, Denver, CO (firstname.lastname@example.org)
Geologic Discipline, Sulfur Geochemistry, Reston, VA (email@example.com)
Reston Chlorofluorocarbon Lab (firstname.lastname@example.org)
Michael Meyer, Kansas Organic Geochemistry Research Group (email@example.com)
Denver Organic Carbon Lab (firstname.lastname@example.org)
David Krabbenhoft, Wisconsin Mercury Lab (email@example.com)
USGS Albany, New York WSC Lab (firstname.lastname@example.org)
USGS Georgia WSC Lab (email@example.com)
Frank Crenshaw (PCFF), Grand Junction, CO (firstname.lastname@example.org)
Kirby Wynn (PCFF), Grand Junction, CO (email@example.com)
OWQ staff (GS-W OWQ)
(See attached file: OWQ 06.03 NWIS4.6.doc)
Timothy L. Miller, Chief, Office of Water Quality
U.S. Geological Survey
412 National Center
Reston, VA 20192