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.
- S_LD for spatial change as well as opposite line directions.
- SA_LD for spatial and attribute changes as well as opposite line directions.
- 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, as well as line directions 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.
- Within each match group, any portions of the update or base features fall outside the Change Tolerance.
The Change Tolerance serves as the width of a buffer zone around the update features or the base features. For each match group, an update buffer is created around all update features and a base buffer around all base features. Then all the update features are checked against the base buffer and all base features against the update buffer. If any portions of the update features fall outside the base buffer or if any portions of the base features fall outside the update buffer, or if both occur, 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 length percentage values based on match groups.
- LEN_ABS—This field stores absolute length values in feature units based on match groups.
The values of these fields are determined based on the match group that the output feature belongs to, depending on the following conditions:
- If only update features fall outside the base buffer—
- Lu = total length of the outside portions of the update features.
- Pu (the length percentage) = Lu / the total length of all the update features * 100.
- LEN_PCT = Pu
- LEN_ABS = Lu
- If only base features fall outside the update buffer—
- Lb = total length of the outside portions of the base features.
- Pb (the length percentage) = Lb / the total length of all the base features * 100.
- LEN_PCT = Pb
- LEN_ABS = Lb
- If both of the above occur—
- The larger of Lu and Lb and its associated percentage value are written. In case of Lb being the written, a negative sign is added for the same reason mentioned above.
The percentage value ranges from 0 to 100, where 0 means both update and base features in a match group are completely within the change tolerance zones; and 100 means all update or base features are outside the change tolerance zones.
The LEN_PCT and LEN_ABS values can help you determine whether or not a change is significant. The higher the values, the more dramatic the change. Only features with spatial changes get these values; others get -1.
An attribute change (change type A) is detected based on the Compare Fields parameter. If you specify one or more pairs of fields for Compare Fields, 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.
Line direction change (change types with _LD) is considered a spatial change and can be detected as an option.
- The matched update features get change type S_LD if the direction of any of their lines are opposite from one or more matched base features, with or without the spatial changes described above. In other words, they are the S or NC types if line directions are not compared.
- The matched update features get change type SA_LD if the direction of any of their lines are opposite from one or more matched base features, in addition to the attribute change or the spatial and attribute changes described above. In other words, they are the A or SA types if line directions are not compared.
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
arcpy.management.DetectFeatureChanges(update_features, base_features, out_feature_class, search_distance, {match_fields}, {out_match_table}, {change_tolerance}, {compare_fields}, {compare_line_direction})| 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 portions of update or base features fall 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 the 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 |
compare_line_direction (Optional) | Specifies whether or not to compare line directions for matched features.
| Boolean |
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 Meters",
["rdClass", "roadClass"])
DetectFeatureChanges example 2 (stand-alone 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
- Basic: No
- Standard: No
- Advanced: Yes