USGS - science for a changing world

Fundamental Science Practices (FSP)

Maps, Imagery, and Publications Hazards Newsroom Education Jobs Partnerships Library About USGS Social Media
This is a formatting graphic. This is a formatting graphic.

Guidance on Documenting Revisions to USGS Scientific Digital Data Releases

Updated March 28, 2018

Purpose
Reasons for Revisions
Level 1 Revision
Level 2 Revision
Level 3 Revision
More About Version Numbering
Archiving Prior Versions of Data
Examples
Summary Table

Purpose

This guidance describes a formal revision process for scientific digital data and associated metadata that have been released as USGS information products. This guidance supplements U.S. Geological Survey (USGS) Fundamental Science Practices (FSP) requirements in SM 502.7 and SM 502.8.

Data release revisions are characterized as Level 1, Level 2, or Level 3, similarly to the characterization of levels for USGS publication series revisions. The procedures for documenting data release revisions vary depending on the level of revision.

Not covered in this guidance are USGS approved databases or web data services that are intended for datasets that are changed continually or on a schedule, with additions and updates made over time. These systems have approved processes in place for making changes, including data quality evaluation, prior to data being uploaded. Examples of these systems or services include National Water Information System (NWIS-Web), USA National Phenology Network (USA-NPN), and Biodiversity Information Serving Our Nation (BISON).

Reasons for Revisions

The reason for revising a data release will guide the process of review and approval. Although other information products are usually revised only to correct errors, data releases may also be revised for other reasons; in all cases, the intent is to provide data for future use. The revision level (1, 2, or 3) depends on whether the changes could affect outcomes of future data use and on the proportion of the data that needs to be corrected.

  • Changes to the metadata record that do not affect the understanding of the data, changes to data files that do not involve modifying the data itself, and changes to a landing page are considered Level 1 revisions.  
  • Changes to a small number of data values, such as adding negative signs to one or two values or adding five missing values, or corrections to transposed latitude and longitude values in the metadata record, are considered Level 2 revisions. Review and approval not only focuses on the sections of the data release that are corrected but also identifies any inadvertent changes that were made to other sections.
  • Data-appending revisions, for example, the release of data in stages in order to meet project timelines, are done to increase the amount of data provided in an information product. These revisions are considered Level 3. Review and approval focuses on the new data that are added but also identifies any inadvertent changes made to other sections.
  • Changes to the data structure are also considered Level 3. These revisions might add new tables to a data release that is structured as a database or add new columns to a data release structured as a table and are usually combined with adding new data. These revisions are appropriate for data releases that are standalone research products rather than for data that are foundations of associated or companion scientific publications or of a policy decision. Review and approval focuses on the new structure and the new data but also identifies any inadvertent changes made to other sections.

Level 1 Revision

A Level 1 revision does not change the data itself. The following are examples of Level 1 revisions:

  • Changes in the metadata record to add new keywords, contact information, or a link to a new publication.
  • Changes in a data file to correct a misspelling in a data header or in a site location name.
  • Changes in a data landing page to correct a misspelled word in the title or abstract or to revise one of the contacts listed.

These revisions can be done by replacing or updating the erroneous file and updating the metadata record and any additional supporting documentation. The updated metadata record should then be provided to the USGS Science Data Catalog.

Although it is a good practice to have an independent reviewer check to ensure that no errors were introduced during the revision process, review and approval for Level 1 revisions do not need to be documented in the internal USGS Information Product Data System (IPDS).

Level 2 Revision

A Level 2 revision creates a new version of the data release that will normally be used instead of the previous version, except for purposes of repeating analyses that used the uncorrected data. The changes for a Level 2 revision, however, affect only a small number of data values. The following are examples of Level 2 revisions:

  • Negative signs were omitted from one or two data values.
  • Five data values were missing in the original data release.
  • Latitude and longitude were transposed in providing the geospatial footprint in the metadata record.
  • Modification in a polygon shapefile by slightly shifting a line so that a boundary is consistent with another polygon shapefile that was recently released.

Science Center approving officials for data releases should be consulted if help is needed to distinguish between Level 2 and Level 3 error corrections, in recognition of the differences in methods among scientific disciplines.

When a Level 2 revision is needed, the following actions are required:

  1. Create a new data release record in the IPDS and complete the review and approval steps for the new data release version. Review and approval should focus on the new or corrected sections but also identify any inadvertent changes made to other sections. The new IPDS record is used to ensure that requirements of SM 502.7 and SM 502.8 have been met.
  2. Assign a version number to the revised data release product, for example changing version 1.1 to version 1.2, and revise the recommended citation and the metadata file to include the new version number. Refer to the "Examples" section.
  3. Modify the landing page as follows:
    1. Point users to the new version of the data.
    2. Include a list of version numbers and version release dates.
    3. Link to a revision history text file that provides a detailed description of the changes and a justification for making the changes.
  4. Revise the metadata record as follows:
    1. Add processing steps that describe the changes.
    2. Insert the version number and version release date into names and data citations.
    3. Update the metadata revision date.
    4. Add instructions for obtaining prior versions.
    5. Provide the revised metadata record to the USGS Science Data Catalog.
  5. Preserve the previous version of the data in accordance with records management disposition schedules and litigation holds requirements in case that version is needed to understand any information that was based on it. Refer to the "Archiving Prior Versions of Data" section for additional guidance.
  6. Do not create a new Digital Object Identifier (DOI). The existing DOI should be used for the revised data release.
  7. If the revision could affect scientific conclusions in an existing USGS publication, consult your local Bureau Approving Official (BAO) or the BAO Coordinator in the Office of Science Quality and Integrity (OSQI) for guidance.

Level 3 Revision

For a Level 3 revision, the data are significantly and substantially changed, as shown in the following examples:

  • Corrections to a large number of data values when an error was discovered in an algorithm used for calculating a column of numbers.
  • Updating a data release to include data from a new time period, place, or field activity.
  • Modification of a data structure to allow inclusion of a new table or column of values.
  • A new data release of a bathymetry grid after an error was detected in the processing step that applied tide corrections in the previously released version.

When a Level 3 revision is needed, the following actions are required:

  1. Create a new data release record in the IPDS and complete the review and approval steps for the new data release version. Review and approval should focus on the new or corrected sections but also identify any inadvertent changes made to other sections. The new IPDS record is used to ensure that requirements of SM 502.7 and SM 502.8 have been met.
  2. Assign a version number to the revised data product and update the recommended citation and the metadata file to include the new version number. The change in the version number for Level 3 revisions is usually done by changing the number before the decimal point, for example, changing version 1.1 to version 2.0. Refer to the "Examples" section.
  3. Modify the landing page as follows:
    1. Point users to the new version of the data.
    2. Include a list of version numbers and version release dates.
    3. Link to a revision history text file that provides a detailed description of the changes and a justification for making the changes.
  4. Revise the metadata record as follows:
    1. Add processing steps that describe the changes.
    2. Insert the version number and version release date into names and data citations.
    3. Update the metadata revision date.
    4. Add instructions for obtaining prior versions.
    5. Provide the revised metadata record to the USGS Science Data Catalog.
  5. Preserve the previous version of the data in accordance with records management disposition schedules and litigation holds requirements in case that version is needed to understand any information that was based on it. Refer to the "Archiving Prior Versions of Data" section for additional guidance.
  6. Do not create a new DOI. The existing DOI should be used for the revised data release.
  7. If the revision could affect scientific conclusions in an existing USGS publication, consult your local BAO or the BAO Coordinator in the OSQI for guidance.

More About Version Numbering

Version numbers consist of two parts, a major and a minor component, separated by a period. The original release is considered version 1.0, although the version annotation is not used if no subsequent versions are released. Either the major component or the minor component of the version number will be incremented when a new version is released.

In the example “version 1.2,” the number to the left of the period, “1,” is the major component and the number to the right of the period, “2,” is the minor component and represents the number of separate Level 2 revisions. Level 2 revisions, regardless of how many, do not initiate a change in the major component of the version number. For example, if the data release was revised on seven separate occasions for Level 2 revisions, the new version will be numbered “version 1.7.”

For the example “version 2.0,” a Level 3 revision was completed, and thus the major component number (“2”) was increased by one number and the minor component was reset to zero (“0”).

Archiving Prior Versions of Data

When data are replaced with a new version, the previous versions are not publicly offered but may be made available to users on request. Because previous versions may have been used to support scientific conclusions in a publication or a policy decision, it is essential to preserve them, for example in a dark archive (an offline location for preservation). The file name and accompanying documentation for previous versions should make clear that the data have been superseded. If frequent small revisions of large data files are anticipated, the science center or program should consider investing in an automated version management system that can automatically recreate each prior version by processing a standard revision history file rather than manually archiving each version.

Examples

The following examples show various notations for documenting data revision changes on the data release landing page.

Examples of citation changes:

Original citation:

Klunk, O.T., 2012, Bathymetry of the Bermuda Triangle: U.S. Geological Survey data release, https://doi.org/10.5066/XXXXXXXX.

Revised citations:

Klunk, O.T., 2012, Bathymetry of the Bermuda Triangle (ver. 1.1, July 2012): U.S. Geological Survey data release, https://doi.org/10.5066/XXXXXXXX.

Klunk, O.T., 2013, Bathymetry of the Bermuda Triangle (ver. 2.0, May 2013): U.S. Geological Survey data release, https://doi.org/10.5066/XXXXXXXX.

Note that the data product title and DOI do not change but that version information is added. Additionally, the publication year should reflect the year that the new version is released.

Examples of version release dates and version numbers:

First release: 2012
Revised: July 2012 (ver. 1.1)
Revised: May 2013 (ver. 2.0)

Example of revision history:

A revision history text file that concisely describes what changed in each revision is needed. For an example, refer to Pendleton, E.A., Ackerman, S.D., Baldwin, W.E., Danforth, W.W., Foster, D.S., Thieler, E.R., and Brothers, L.L., 2016, High-resolution geophysical data collected along the Delmarva Peninsula, 2014, USGS Field Activity 2014-002-FA (ver. 4.0, October 2016): U.S. Geological Survey data release, https://doi.org/10.5066/F7MW2F60.

Summary Table

The table below summarizes actions required depending on the nature of the revision.

Action Level 1 Revision Level 2 Revision Level 3 Revision
Change in data release No changes to the data values, only changes such as a misspelling in a data header, attribute, or a site location name Corrections to the data or metadata that might affect outcomes of future data use Changes in the data structure or updates that add or modify substantial amounts of data in an existing data release
Document changes in metadata record Yes Yes Yes
Document changes in revision history file No Yes Yes
Change revision list on web landing page No Yes Yes
Archive prior versions of data No Yes Yes
Change version number No change Increment minor component number (no number to 1.1, 1.1 to 1.2, 1.2 to 1.3, 1.3 to 1.4, and so on) Increment major component number (1.1 to 2.0, 2.2 to 3.0, 3.1 to 4.0,  and so on)
Complete FSP review (with a new IPDS record) Not required Required Required
Create a new DOI No No No


Accessibility FOIA Privacy Policies and Notices

USA.gov logo U.S. Department of the Interior | U.S. Geological Survey
URL: http://www.usgs.gov/fsp/data_versioning.asp
Page Contact Information: Ask USGS
Page Last Modified: Wednesday, March 28, 2018