National Channel Framework (NCF) ChannelReach Changelog

Developed by:
Connor Hicks
Junior Software Engineer, ARA

Magdalena Asborno, PhD
Senior Consultant, ARA
Research Civil Engineer, USACE-ERDC

Jaden Nobles Junior Software Engineers, ARA

The "National Channel Framework ChannelReach Changelog" process tracks changes between any two versions of USACE National Channel Framework ChannelReach polygon layer. The automated process runs in QGIS 3.34.x, as a toolbox script stored in a python file in this repository.

First, the user selects the NCF ChannelReach versions they wish to compare, and choose the properties they want to compare between the two versions. Then, they select the filepath where the output will be saved after the script finishes running. The process runs automatically. After execution, two outputs are produced: a) a .csv file is populated with all notable changes between the two NCF versions, and b) a shapefile includes the polygon geometries with different attributes.

Cite this work

If you use this work, please add this citation:

Asborno, M., C. Hicks, and K. N. Mitchell. 2025. National Channel Framework ChannelReach Changelog. https://github.com/erdc/ncf-channel-reach Vicksburg, MS: US Army Engineer Research and Development Center, Coastal and Hydraulics Laboratory. DOI forthcoming

National Channel Framework ChannelReach Changelog

Prerequisites

1. Install QGIS (3.34.X)

How to run

1. Download the NCFChangelog.py file.
2. Open a QGIS project with the layers you wish to compare between, or add the desired layers.
3. To add the latest version of the NCF: 3.1 In the top menu, click Layer > Add Layer > Add ArcGIS REST Server Layer... 3.2 Click New. Enter a name for this server connection. 3.3 The URL should point to the National Channel Framework API. Usually is [https://services7.arcgis.com/n1YM8pTrFmm7L4hs/ArcGIS/rest/services/National_Channel_Framework/FeatureServer (https://services7.arcgis.com/n1YM8pTrFmm7L4hs/ArcGIS/rest/services/National_Channel_Framework/FeatureServer). 3.4 Click OK. Click Connect. 3.5 Select the ChannelReach polygon layer. Click Add or Add with Filter.
4. Navigate to your Processing Toolbox window. If you do not see this window, in the top menu, click Processing and ensure that Toolbox is enabled.
5. Click the 2nd icon in the top row of the Processing Toolbox window > Add Script to Toolbox...

6. Navigate to your downloaded Toolbox Script file. This adds a shortcut to your QGIS installation to the Toolbox Script file for future use.
7. Scroll down the Processing Toolbox window until you see Scripts. Click Scripts > ChannelReach > ChannelReach Changelog.

8. After clicking the Tool, a ChannelReach Changelog menu will appear for you to enter the desired parameters. The help window to the right provides additional insights about each parameter. Below is an example screenshot of the ChannelReach Changelog menu with completed parameters as an example.

9. The first input prompts you to select the old ChannelReach polygon layer you want to use.
10. The second input prompts you to select the unique ID field of the old ChannelReach layer.
11. The third input prompts you to select the new ChannelReach layer polygon you want to use.
12. The fourth input prompts you to select the unique ID field of the new ChannelReach layer.
13. The fifth and sixth inputs prompt you to enter the fields from the old and new layers that you would like to compare.
    (Note: Both old and new fields must be the same and in identical order.)
14. The final input labeled Tabular Output prompts you to specify the .csv filepath where you would like the data to output after the Process has finished running. All parameters except the Geospatial Output are required.
15. Once all fields are filled out, click Run in the bottom right hand corner.
16. When the script is finished running, the log should look similar to the figure below, and the progress bar at the bottom will say Complete.

How to read the .csv Tabular Output file

The Tabular Output will be written into a .csv file. The .csv file will only contain data for the ChannelReaches that have been added, removed, or changed.

• The left column will have the unique ID ChannelReachIDPK field that have been affected.
• The column titled District will have the district that the ChannelReach is a part of.
• The column title Type contains information on the whether a ChannelReach was added, removed, or changed. If data was changed, it will specify which fields were changed.
  (Note: The Shape__Area fields will only be reported as changed if the absolute difference in areas of a ChannelReach's geometries is greater than 0.0000001 square miles.)

Below is an example screenshot of a .csv file displaying both the old and new data fields for comparison.

How to read the Geospatial Output layer

The Geospatial Output will be automatically added to your Layers in the QGIS project, either as a temporary layer or in the file specified by the user. The Geospatial Output contains the same data as the Tabular Output, with the addition of two new columns and geometries for the ChannelReaches.

• The column titled GeometrySource contains information about the entry's geometry origins.
  • If a ChannelReachIDPK's Shape__Area is reported as changed, two entries and geometries are displayed: one displays geometry from the old ChannelReach layer, the other displays geometry from the new ChannelReach layer.
  • If a ChannelReachIDPK is reported as removed, geometry from the old ChannelReach layer is displayed.
  • Otherwise, geometry from the new ChannelReach layer is displayed for a ChannelReachIDPK.
• The column titled ID is a unique ID field to differentiate between GeometrySources of "New" & "Old" between the same ChannelReachIDPK entry.

Below is an example screenshot of a the Geospatial Output layer displaying the geometry of a removed ChannelReach. Notice how the old ChannelReach polygons are a red outline, the new ChannelReach polygons are a blue outline, and the brown Geospatial Output polygons intersect areas where a red polygon is present without a matching blue polygon.