Transfer Attributes (Editing)

Summary

Finds where the source line features spatially match the target line features and transfers specified attributes from source features to matched target features.

Attribute transfer is typically used to copy attributes from features in one dataset to corresponding features in another dataset. For example, it can be used to transfer the names of road features from a digitized and maintained dataset to features in a new dataset that are newly collected and more accurate. The two datasets are usually referred to as source features and target features. This tool finds corresponding source and target line features within the specified search distance and transfers the specified attributes from source lines to target lines.

Illustration

Usage

Caution:

This tool modifies the input data. See Tools that modify or update the input data for more information and strategies to avoid undesired data changes.

Note:

All inputs must be in the same coordinate system.

• The union of input extents is used as the processing extent. The counts of participating source and target features are reported in the processing messages.

• One or more fields in the Transfer Field(s) parameter must be specified. If a transfer field has the same name as a field from the target feature table, the transfer field will be appended with _1 (or _2, or _3, and so on) to make it unique.

  When multiple source features match one or more target features, the field values from only one of the source features are transferred to the target features. If a source field value is missing, no attribute transfer occurs.

• 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.

• The Output Match Table parameter is optional. The 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 aid in postinspection, postediting, and further analysis. See About feature matching and the match table for details.

• Use the Transfer Rule Field(s) parameter to set rules to control attribute transfer for m:n matches in which multiple source features matched one or more target features. If no rules are set, attributes will be transferred from the longest of the matched source features. However, to better guide the transfer, attribute-based rules can be used, and each is defined by a field name and a value.

  The following field types and ruling values are supported:

  Field type	Ruling values
  Text	A string value that may exist in the source features.
  Integer	Either an integer value that may exist in the source features, or MAX or MIN for the maximum or minimum value.
  Date	MAX or MIN for the most recent or oldest date.

  You can specify as many field/ruling value pairs as needed. The rules will be applied in the order they are listed.

  When an m:n match is found, the tool will check the specified fields and ruling values and determine from which of them to transfer attributes in the following ways:

  • If only one of the m source features has the ruling value in the first field in the rule list, that source feature will be used for the transfer.
  • If more than one, or none, of the m source features have the ruling value, it is a tie. If no more rules are specified, the longest of them will be used for the transfer. Otherwise, the next rule in the list will be checked to break the tie.
  • The process continues until all the rules have been evaluated. If no source feature can be determined for the transfer, the longest source feature will be used.

  The following example explains how this process works. The ROAD_NAME field needs to be transferred from source to target for a 3:1 match. By default, source feature 3, the longest of the three source features, would be used for the transfer, and the target feature would receive the ROAD_NAME value of West Ave as shown in table (a) below.

  Now, assume that the following rules are set: the TRAVEL_DIRECTION field with the One way rule and the SPEED_LIMIT field with the MAX rule. To determine the correct source feature for the transfer, the tool first evaluates the TRAVEL_DIRECTION values for all three source features and finds that two have a match for One way. The tool then checks the SPEED_LIMIT values of these two features and uses the OBJECTID field 1, which has a maximum value of 40. That means the ROAD_NAME field value East Ave is transferred from this feature to the target feature as shown in table (b) below.

  

• Feature matching accuracy relies on data quality, complexity, and similarities of the two inputs.

  Minimize data errors and select relevant features as input through preprocessing. In general, it is helpful when the features in an input dataset are topologically correct, have valid geometry, and are singlepart and not duplicate; otherwise, unexpected results may occur.

Parameters

Dialog

Label	Explanation	Data Type
Source Features	The line features from which attributes will be transferred.	Feature Layer
Target Features	The line features to which attributes will be transferred. The transfer fields will be added to the target features.	Feature Layer
Transfer Field(s)	A list of source fields that will be transferred to target features. At least one field must be provided.	Field
Search Distance	The distance that will be 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 (Optional)	Lists of fields from source and target features. If provided, each pair of fields are checked for match candidates to help determine the right match.	Value Table
Output Match Table (Optional)	The output table containing complete feature matching information.	Table
Transfer Rule Field(s) (Optional)	The rules that control which source feature will be used to transfer attributes from when multiple source features matched target features. The source feature that will be used for the transfer is determined by the specified rule fields and the ruling values, which are ranked from high to low priority as they appear in the specified list. If no rules are set, the longest of the multiple matched source features will be used for the transfer. Available rule types are as follows: MIN—The minimum value for an integer or date field. For a date field, use the most recent date. MAX—The maximum value for an integer or date field. For a date field, use the oldest date. A text or integer value that may exist in the source features.	Value Table

Derived Output

Label	Explanation	Data Type
Updated Target Features	The updated target features.	Feature Class

Python

arcpy.management.TransferAttributes(source_features, target_features, transfer_fields, search_distance, {match_fields}, {out_match_table}, {transfer_rule_fields})

Name	Explanation	Data Type
source_features	The line features from which attributes will be transferred.	Feature Layer
target_features	The line features to which attributes will be transferred. The transfer fields will be added to the target features.	Feature Layer
transfer_fields [field,...]	A list of source fields that will be transferred to target features. At least one field must be provided.	Field
search_distance	The distance that will be 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 source and target features. If provided, 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
transfer_rule_fields [[field, rule],...] (Optional)	The rules that control which source feature will be used to transfer attributes from when multiple source features matched target features. The source feature that will be used for the transfer is determined by the specified rule fields and the ruling values, which are ranked from high to low priority as they appear in the specified list. If no rules are set, the longest of the multiple matched source features will be used for the transfer. Available rule types are as follows: MIN—The minimum value for an integer or date field. For a date field, use the most recent date. MAX—The maximum value for an integer or date field. For a date field, use the oldest date. A text or integer value that may exist in the source features.	Value Table

Derived Output

Name	Explanation	Data Type
out_feature_class	The updated target features.	Feature Class

Code sample

TransferAttributes example 1 (Python window)

The following Python window script demonstrates how to use the TransferAttributes function in immediate mode.

import arcpy
arcpy.env.workspace = "C:/data"
arcpy.edit.TransferAttributes("source_Roads.shp", "target_Roads.shp", 
                              [["RoadName", "PaveType"]], "25 Feet")

TransferAttributes example 2 (stand-alone script)

The following stand-alone script is an example of how to apply the TransferAttributes function in a scripting environment.

"""
Name:        TransferAttributes_example_script2.py
Description: Perform attribute transfer from newly updated roads (source) to existing
             base roads (target). When the source and target features are matched in
             many-to-one or many-to-many (m:n) relationships, attributes are transferred 
             from only one of the m source features to the n target features. This script
             includes a postprocess that flags resulting target features with the m:n
             match relationship. You can inspect the flagged features and retrieve the
             attributes from the desired source features if necessary.
"""

# Import system modules
import arcpy

# Set environment settings
arcpy.env.overwriteOutput = True
arcpy.env.workspace = r"D:\conflationTools\ScriptExamples\data.gdb"

# Set local variables
sourceFeatures = "updateRoads"
targetFeatures = "baseRoads"
transfer_fields = [["RD_NAME", RD_ID"]]

search_distance = "300 Feet"
match_fields = [["RD_NAME", "FULLNAME"]]

outMatchTable = "ta_mtbl"

# Make a copy of the targetFeatures for attribute transfer
targetCopy = targetFeatures + "_Copy"
arcpy.management.CopyFeatures(targetFeatures, targetCopy)

# Performs attribute transfer
arcpy.edit.TransferAttributes(sourceFeatures, targetCopy, transfer_fields, search_distance, match_fields, outMatchTable)

"""
Note 1:  The result of TransferAttributes may contain errors; see the tool reference.
         Additional analysis steps may be necessary to check the results. These steps
         are not included in this script.

         The following process identifies m:n matches between source and target features 
         and flags features in targetCopy for inspection.
"""

# Add a field srcM_inMN to the match table to store the m count of source features in m:n relationship
field_srcM_inMN = "srcM_inMN"
arcpy.management.AddField(outMatchTable, field_srcM_inMN)

codeblock = """
def getM(fld):
    x = fld.split(\":\")[0]
    if x.isnumeric():
        if int(x) > 0:
            return int(x)
    return -1
"""

# Calculate values for srcM_inMN
arcpy.management.CalculateField(outMatchTable, field_srcM_inMN, "getM(!FM_MN!)", "PYTHON_9.3", codeblock)

# Make a table view of the match table, selecting srcM_inMN values greater than 1 
# (excluding 1:n relationships which don't need to be inspected)
arcpy.management.MakeTableView(outMatchTable, "mtable_view", field_srcM_inMN + "> 1")

# For the selected records, transfer srcM_inMN and SRC_FID fields and values to the targetCopy
arcpy.management.JoinField(targetCopy, "OBJECTID", "mtable_view", "TGT_FID", [["field_srcM_inMN", "SRC_FID"]])

"""
Note 2:  Now the fields srcM_inMN and SRC_FID are in the copy of the target features.
         The srcM_inMN values are the counts of matched source features. The SRC_FID
         values indicate the source feature IDs from which the transferred attributes
         originated.

         You can interactively review the transferred attributes for the
         flagged features. To replace any of them with those from a different
         source feature, make the edits as needed.
"""

TransferAttributes example 3 (stand-alone script)

The following stand-alone script is an example of how to apply the TransferAttributes function using transfer rules in a scripting environment.

"""
Name:        TransferAttributes_example_script3.py
Description: Perform attribute transfer from newly updated roads (source) to
             existing base roads (target). When the source and target
             features are matched in many-to-one or many-to-many (m:n)
             relationships, attributes can be transferred based on transfer
             rules. This script shows how transfer rules are set.
"""

# Import system modules
import arcpy

# Set environment settings
arcpy.env.overwriteOutput = True
arcpy.env.workspace = r"D:\conflationTools\ScriptExamples\data.gdb"

# Set local variables
sourceFeatures = "updateRoads"
targetFeatures = "baseRoads"
transfer_fields = "RD_NAME"

search_distance = "300 Feet"
match_fields = ""
outMatchTable = ""
transfer_rules = [["TRAVEL_DIRECTION", "One-Way"], ["SPEED_LIMIT", "MAX"]]

# Make a copy of the targetFeatures for attribute transfer
targetCopy = targetFeatures + "_Copy"
arcpy.management.CopyFeatures(targetFeatures, targetCopy)

# Perform attribute transfer
arcpy.edit.TransferAttributes(sourceFeatures, targetCopy, transfer_fields,
                              search_distance, match_fields, outMatchTable,
                              transfer_rules)

Environments

Current Workspace, Extent