Summary
Finds where the update line features spatially match the base line features and detects spatial changes, attribute changes, or both, as well as no change, and creates an output feature class containing matched update features with information about their changes, unmatched update features, and unmatched base features.
Illustration
Usage
A typical use case of this tool is that you maintain a set of line features, roads, for example, and receive updates periodically from partners as a new set of road features. You want to know which of the updated features are changes to existing base features or are new features to be added, and which base features are old and should be deleted. This tool finds the matching features between the update and base line datasets, detects spatial changes, attribute changes, or both, as well as no changes, and creates an output feature class containing feature change information.
The output feature class contains all participating update features (matched and unmatched) and any unmatched base features. Information about the detected changes are written to the following fields:
- UPDATE_FID—The feature ID of the update feature. The value is -1 for an unmatched base feature.
- BASE_FID—The feature ID of the base feature. The value is -1 for an unmatched update feature.
- CHANGE_TYPE—The type of change detected, as follows:
- S for spatial, indicating a matched update feature with a spatial change.
- A for attribute, indicating a matched update feature with an attribute change.
- SA for spatial and attribute, indicating a matched update feature with both spatial and attribute changes.
- NC for no change, indicating a matched update feature with no change.
- N for new, indicating an unmatched update feature that is new to the base data.
- D for deletion, indicating an unmatched base feature that might need to be deleted from base data.
The feature matching process is done first based on the Search Distance and the optional Match Fields. An output match table can be produced to store the match information.
The Search Distance parameter is used in finding match candidates. Use a distance large enough to catch most of the shifts between corresponding features, but not too large to cause unnecessary processing of too many candidates and potentially getting wrong matches.
Once match candidates are found, they are further evaluated by a set of geometric measures to determine if they are similar enough to be considered spatially matched.
If you specify one or more pairs of fields for the Match Fields parameter, spatially matched candidates are checked against these field values to help determine the correct match. For example, suppose the update and base features both have a STREET_NAME field containing street names. If an update feature spatially matches two base features but only one base candidate has the same STREET_NAME value as the update feature, it is the better match. The comparison of text strings is case insensitive, meaning that First St is considered the same as first st.
The Output Match Table is optional. This match table provides complete feature matching information, including the source and target FIDs, match groups, match relationships, and the level of confidence of the matching derived from spatial and attribute matching conditions. This information can help you understand the match situations and facilitate postinspection, postediting, and further analysis. See About feature matching and the match table for details.
In the output match table, the values in SRC_FID and TGT_FID fields represent update feature IDs and base feature IDs, respectively.
The process of identifying changes occurs after feature matching. The spatial and attribute conditions of all matched update features are compared with corresponding base features to determine their CHANGE_TYPE values.
A spatial change (change type S) is detected where one or both of the following occur:
- The matched update features differ from their corresponding base features in topology, for example one update feature matches two base features.
- A part of an update feature or a base feature falls outside the Change Tolerance.
The Change Tolerance serves as the width of a buffer zone around the update features and base features. All matched update features and base features are checked against this tolerance. If any parts of an update feature falls outside the zone around the matched base feature, or If any parts of a base feature falls outside the zone around the matched update feature, it is considered a spatial change. When a value greater than 0 is specified, the output will contain two additional fields:
- LEN_PCT—This field stores percentage values, where each is calculated by comparing the length of the portion of an update feature or a base feature that falls outside of the change tolerance zone with its entire length. The value of 0 means the update feature or the base feature is completely within the change tolerance zone; the value of 100 means the entire update or base feature is outside.
- LEN_ABS—This field stores length values in feature units, where each represents the absolute length of the portion of an update feature or a base feature that falls outside the change tolerance.
An attribute change (change type A) is detected based on the Compare Fields, if specified.
If you specify one or more pairs of fields for the Compare Fields parameter, matched features are checked against these fields to determine if there is an attribute change. The comparison of text strings is case insensitive, meaning that First St is considered the same as first st.
If both spatial and attribute changes are detected for a matched update feature, it gets the change type SA. If no spatial and attribute changes are detected for a matched update feature, it is considered no change and gets the change type NC.
The union of input extents is used as processing extent. The counts of participating source and target features are reported in the processing messages.
Feature matching accuracy highly relies on data quality, complexity, and similarities of the two inputs.
You need to minimize data errors and select relevant features as input through preprocessing. In general, it is always helpful that within an input dataset the features are topologically correct, have valid geometry, and are singlepart and nonduplicate; otherwise, unexpected results may occur.
You can review the detected changes in the output feature class. You may find that the spatial differences between the two data sources are significant and decide that one of them should be adjusted to better match the other. You may also want to transfer attributes between update features and base features. The rubbersheeting and attribute transfer tools in Conflation toolset can help you make the changes.
Syntax
DetectFeatureChanges_management (update_features, base_features, out_feature_class, search_distance, {match_fields}, {out_match_table}, {change_tolerance}, {compare_fields})| Parameter | Explanation | Data Type |
update_features | Line features to compare to the base features. | Feature Layer |
base_features | Line features to be compared with update features for change detection. | Feature Layer |
out_feature_class | Output line feature class with change information. The output contains all participating update features (matched and unmatched) and any unmatched base features. | Feature Class |
search_distance | The distance used to search for match candidates. A distance must be specified and it must be greater than zero. You can choose a preferred unit; the default is the feature unit. | Linear unit |
match_fields [[source_field, target_field],...] (Optional) | Lists of fields from update and base features. If specified, each pair of fields are checked for match candidates to help determine the right match. | Value Table |
out_match_table (Optional) | The output table containing complete feature matching information. | Table |
change_tolerance (Optional) | The distance used to determine if there is a spatial change. All matched update features and base features are checked against this tolerance. If any parts of an update feature or base feature falls outside the zone around the matched feature, it is considered a spatial change. A distance can be equal to or greater than zero. The default is 0. When a value greater than zero is specified, the output will include LEN_PCT and LEN_ABS fields. You can choose a preferred unit; the default is the feature unit. | Linear unit |
compare_fields [[source_field, target_field],...] (Optional) |
Fields to determine if there is an attribute change between matched update and base features. | Value Table |
Code sample
DetectFeatureChanges example 1 (Python window)
The following Python window script demonstrates how to use the DetectFeatureChanges function in immediate mode.
import arcpy
arcpy.env.workspace = "C:/data"
arcpy.DetectFeatureChanges_edit("update_Roads.shp",
"base_Roads.shp", "output_changes.shp"
"25 Feet", #, #, "7.6 Meterd",
["rdClass", "roadClass"])
DetectFeatureChanges example 2 (stand-alone Python script)
The following stand-alone script is an example of how to apply the DetectFeatureChanges function in a scripting environment.
# Name: DetectFeatureChanges_example_script2.py
# Description: Perform change detection between newly received road data and
# existing road data and find the number of new roads and the
# total length of them.
# Author: Esri
# -----------------------------------------------------------------------
# Import system modules
import arcpy
from arcpy import env
# Set environment settings
env.overwriteOutput = True
env.workspace = r"D:\conflationTools\ScriptExamples\data.gdb"
# Set local variables
updateFeatures = "updateRoads"
baseFeatures = "baseRoads"
dfcOutput = "dfc_out"
search_distance = "300 Feet"
match_fields = "RD_NAME FULLNAME"
statsTable = "new_roads_stats"
# Perform spatial change detection
arcpy.DetectFeatureChanges_management(updateFeatures, baseFeatures, dfcOutput, search_distance, match_fields)
# ====================================================================================
# Note 1: The result of DetectFeatureChanges may contain errors; see tool reference.
# Inspection and editing may be necessary to ensure correct CHANGE_TYPE N, which
# represents un-matched update feautres, before further calculations.
#
# One of the quick ways of checking whether the CHANGE_TYPE N features have
# matching base features is to find their mid-points and use them to search for
# features in base data, as processed below.
# ====================================================================================
# ======== Check update roads with CHANGE_TYPE N for potential match
# Make Feature Layer with selection of CHANGE_TYPE = 'N' (un-matched update features)
arcpy.MakeFeatureLayer_management(dfcOutput, "sel_N_layer", "CHANGE_TYPE = 'N'")
# Get mid-points of the selected features; the mid-points carry all the attributes.
arcpy.FeatureVerticesToPoints_management("sel_N_layer", "in_memory\midPts", "MID")
# Find nearest base features from the mid-points
arcpy.Near_analysis("in_memory\midPts", baseFeatures, "300 Feet")
# ====================================================================================
# Note 2: At this point you can manually inspect the midPts by the NEAR_DIST values;
# the lower the values, the higher chance (not always) a match was missed in the
# dfc process. Delete features from midPts that have found matching base features
# before further process.
# ====================================================================================
# Transfer CHANGE_TYPE values from features of midPts to update features
arcpy.JoinField_management(updateFeatures, "OBJECTID", "in_memory\midPts", "UPDATE_FID", "CHANGE_TYPE")
# Get the count of new roads and the total length; the remaining roads have
# Null values for CHANGE_TYPE.
arcpy.Frequency_analysis(updateFeatures, statsTable, "CHANGE_TYPE", "Shape_Length")
Environments
Licensing information
- ArcGIS for Desktop Basic: No
- ArcGIS for Desktop Standard: No
- ArcGIS for Desktop Advanced: Yes