Unión espacial (Analysis)

Resumen

Une los atributos de una entidad con otra basada en la relación espacial. Las entidades de destino y los atributos unidos de las entidades de unión se escriben en la clase de entidad de salida.

Ejemplos de vista de relación espacial

Uso

• La unión espacial hace coincidir las filas de las Entidades de unión con las Entidades de destino según sus ubicaciones espaciales relativas.

• Por defecto, todos los atributos de las entidades de unión se incorporan a los atributos de las entidades de destino y se copian en la clase de entidad de salida. Puede definir los atributos que se escribirán en la salida al manipularlos en el parámetro Campo del mapa de las entidades de unión.

• Dos nuevos campos, Join_Count y TARGET_FID, se agregan a la clase de entidad de salida. Join_Count indica cuántas entidades de unión coinciden con cada entidad de destino (TARGET_FID).

  Otro campo nuevo, JOIN_FID, se agrega a la salida cuando se especifica Unir uno a muchos (JOIN_ONE_TO_MANY en Python) en el parámetro Operación de unión (join_operation en Python).

• Cuando el parámetro Operación de unión es Unir uno a muchos, puede haber más de una fila en la clase de entidad de salida para cada entidad de destino. Utilice el campo JOIN_FID para determinar qué entidad se une a qué entidad de destino (TARGET_FID). Un valor de -1 en el campo JOIN_FID significa que ninguna entidad cumple la relación espacial especificada con la entidad de destino.

• Todas las entidades de destino de entrada se escriben en la clase de entidad de salida si se cumplen las dos condiciones siguientes:

  • Operación de unión está establecida en Unir uno a uno.
  • Mantener todas las entidades de destino está activada (join_type = "KEEP_ALL" en Python).

• Los campos del dataset de salida y el contenido de esos campos se pueden controlar utilizando el Mapa de campo.

  • Para cambiar el orden de campos, seleccione un nombre de campo y arrástrelo a la posición que prefiera.
  • El tipo de datos predeterminado de un campo de salida coincide con el tipo de datos del primer campo de entrada (de ese nombre) que encuentre. El tipo de datos se puede cambiar por cualquier otro tipo de datos válido de forma manual en cualquier momento.
  • Están disponibles las siguientes reglas de fusión: primero, último, unir, sumar, valor medio, mediana, modo, mínimo, máximo, desviación estándar y recuento.
  • Cuando utiliza la regla de fusión Unir, puede especificar un delimitador como un espacio, una coma, un punto, un guion, etc. Para utilizar un espacio, asegúrese de que el puntero del ratón esté al comienzo del cuadro de entrada y pulse la barra espaciadora una vez.
  • Puede especificar las posiciones inicial y final de los campos de texto usando la opción de formato.
  • No realice la desviación estándar en una sola entrada, ya que los valores no se pueden dividir por cero, por lo que esta no es una opción válida para las entradas individuales.

  Más información sobre la asignación de campos en scripts

• Las reglas de fusión especificadas en el parámetro Mapa de campo de Entidades de unión solo se aplican a los atributos de las entidades de unión y cuando se coteja más de una entidad con una entidad de destino (cuando Join_Count > 1). Por ejemplo, si tres entidades con valores de atributo DEPTH de 15,5; 2,5 y 3,3 se unen, y se aplica una regla de fusión de Valor medio, el campo de salida tendrá un valor de 6,1. Los valores nulos en los campos de unión se ignoran para el cálculo de estadísticas. Por ejemplo, 15,5, <null>, y 2,5 resultará en 9,0 para Valor medio y 2 para Recuento.

• Cuando el parámetro Opción de coincidencia se configura en Más cercano o Geodésico más cercano, es posible que dos o más entidades de unión estén a la misma distancia de la entidad de destino. Cuando ocurre esta situación, una de las entidades de unión se selecciona de forma aleatoria como la entidad coincidente (el Id. de objeto de la entidad de unión no afecta esta selección aleatoria). Si desea encontrar la 2^a, 3^a o enésima entidad más cercana, utilice la herramienta Genera tabla de cercanía.

  Más información acerca del cálculo de la proximidad

• Si una entidad de unión tiene una relación espacial con varias entidades de destino, se cuenta tantas veces como coincidencias con la entidad de destino haya. Por ejemplo, si un punto está dentro de tres polígonos, el punto se cuenta tres veces, una vez por cada polígono.

• Para obtener más información sobre el uso de las relaciones espaciales tridimensionales Intersecar 3D y Dentro de una distancia 3D, consulteSeleccionar por ubicación: relaciones 3D.

Sintaxis

arcpy.analysis.SpatialJoin(target_features, join_features, out_feature_class, {join_operation}, {join_type}, {field_mapping}, {match_option}, {search_radius}, {distance_field_name})

Parámetro	Explicación	Tipo de datos
target_features	Los atributos de las entidades de destino y los atributos de las entidades unidas se transfieren a la clase de entidad de salida. Sin embargo, se puede definir un subconjunto de atributos en el parámetro del mapa de campo.	Feature Layer
join_features	Los atributos de las entidades de unión se unen a los atributos de las entidades de destino. Consulte la explicación del parámetro join_operation para obtener detalles sobre cómo la agregación de atributos unidos se ve afectada por el tipo de operación de unión.	Feature Layer
out_feature_class	Una nueva clase de entidad que contiene los atributos de las entidades de unión y de destino. Por defecto, todos los atributos de las entidades de destino y los atributos de las entidades unidas se escriben en la salida. Sin embargo, el conjunto de atributos que se transferirá se puede controlar mediante el parámetro del mapa de campo.	Feature Class
join_operation (Opcional)	Especifica cómo se manejarán las uniones entre las entidades de destino y las entidades de unión en la clase de entidad de salida si se encuentran varias entidades de unión que tengan la misma relación espacial con una sola entidad de destino. JOIN_ONE_TO_ONE —Si se encuentran varias entidades de unión que tengan la misma relación espacial con una sola entidad de destino, se agregarán los atributos de las múltiples entidades de unión mediante una regla de fusión de asignación de campos. Por ejemplo, si se encuentra una entidad de destino de punto dentro de dos entidades de unión de polígono separadas, se agregarán los atributos de los dos polígonos antes de que se transfieran a la clase de entidad de puntos de salida. Si un polígono tiene un valor de atributo de 3 y el otro tiene un valor de 7 y se especifica una regla de fusión de Suma, el valor agregado en la clase de entidad de salida será 10. Esta es la opción predeterminada. JOIN_ONE_TO_MANY —Si se encuentran varias entidades de unión que tengan la misma relación espacial con una sola entidad de destino, la clase de entidad de salida contendrá varias copias (registros) de la entidad de destino. Por ejemplo, si se encuentra una única entidad de destino de un punto dentro de dos entidades de unión de polígonos independientes, la clase de entidad de salida contendrá dos copias de la entidad de destino: un registro con los atributos de un polígono y otro registro con los atributos del otro polígono.	String
join_type (Opcional)	Especifica si todas las entidades de destino se mantendrán en la clase de entidad de salida (conocida como unión externa) o solo se mantendrán aquellas que tengan la relación espacial especificada con las entidades de unión (unión interna). KEEP_ALL —Todas las entidades de destino se mantendrán en la salida (unión externa). Esta es la opción predeterminada. KEEP_COMMON — Sólo se mantendrán en la clase de entidad de salida aquellas entidades de destino que tengan la relación espacial especificada con las entidades de unión (unión interna). Por ejemplo, si se especifica una clase de entidad de puntos para las entidades de destino y una clase de entidad poligonal para las entidades de unión, con match_option = "WITHIN", la clase de entidad de salida solo contendrá aquellas entidades de destino que se encuentren dentro de una entidad de unión de polígono. Las entidades de destino que no estén incluidas en una entidad de unión se excluirán de la salida.	Boolean
field_mapping (Opcional)	Controla qué campos de atributos estarán en la salida. De forma predeterminada se incluirán todos los campos de las entradas. Se puede añadir, eliminar y reordenar los campos, además de cambiar su nombre y sus propiedades. Las reglas de fusión le permiten especificar cómo los valores de dos o más campos de entrada se fusionan o se combinan en un único valor de salida. Hay varias reglas de fusión que puede utilizar para determinan cómo se rellena con valores el campo de salida. Primero: utilizar el primer valor de los campos de entrada. Último: utilizar el último valor de los campos de entrada. Unir: concatenar (unir) los valores de los campos de entrada. Sumar: calcular el total de los valores de los campos de entrada. Valor medio: calcular el valor medio (promedio) de los valores de los campos de entrada. Mediana: calcular el valor de la mediana (mitad) de los valores de los campos de entrada. Modo: utilizar el valor con la mayor frecuencia. Mín.: usar el valor mínimo de todos los valores de los campos de entrada. Máx.: usar el valor máximo de todos los valores de los campos de entrada. Desviación estándar: utilizar el método de clasificación de la desviación estándar en todos los valores de campos de entrada. Conteo: buscar la cantidad de registros incluidos en los cálculos. En Python puede utilizar la clase FieldMappings para definir este parámetro.	Field Mappings
match_option (Opcional)	Especifica los criterios que se utilizan para hacer que concuerden las filas. INTERSECT —Las entidades de las entidades de unión se harán coincidir si se intersecan con una entidad objetivo. Esta es la opción predeterminada. Especifique una distancia en el parámetro search_radius. INTERSECT_3D — Las entidades de las entidades de unión se ajustarán si se intersecan con una entidad objetivo en el espacio tridimensional (x, y, z). Especifique una distancia en el parámetro search_radius. WITHIN_A_DISTANCE —Las entidades en las entidades de unión se harán coincidir si están dentro de una distancia especificada de una entidad objetivo. Especifique una distancia en el parámetro search_radius. WITHIN_A_DISTANCE_GEODESIC —Como WITHIN_A_DISTANCE, excepto que se utiliza una distancia geodésica en vez de una distancia planar. Elija esta opción si los datos cubren una gran extensión geográfica o si el sistema de coordenadas de las entradas no es adecuado para los cálculos de distancia. WITHIN_A_DISTANCE_3D —Las entidades en las entidades de unión se harán coincidir si están dentro a una distancia especificada de una entidad de destino en espacio tridimensional. Especifique una distancia en el parámetro search_radius. CONTAINS —las entidades en las entidades de unión se harán coincidir si una entidad de destino las contiene. Las entidades objetivo deben ser polilíneas o polígonos. Para esta opción, las entidades de destino no pueden ser puntos y las entidades de unión sólo pueden ser polígonos cuando las entidades de destino también son polígonos. COMPLETELY_CONTAINS —Las entidades en las entidades de unión se harán coincidir si una entidad de destino las contiene completamente. El polígono puede contener completamente cualquier entidad. El punto no puede contener completamente cualquier entidad, ni siquiera un punto. La polilínea puede contener completamente solo polilínea y punto. CONTAINS_CLEMENTINI —Esta relación espacial proporciona los mismos resultados que COMPLETELY_CONTAINS con la excepción de que si la entidad de unión está completamente sobre el límite de la entidad objetivo (ninguna parte se encuentra totalmente dentro o fuera), la entidad no se hará coincidir. Clementini define el polígono de límite como la línea que separa el interior del exterior; el límite de una línea se define como sus extremos y el límite de un punto siempre está vacío. WITHIN —Tas entidades en las entidades de unión se harán coincidir si una entidad de destino está dentro de ellas. Es contrario a CONTAINS. Para esta opción, las entidades de destino solo pueden ser polígonos cuando las entidades de unión también son polígonos. El punto solo puede ser entidad de unión si el punto es el objetivo. COMPLETELY_WITHIN —Las entidades en las entidades de unión se harán coincidir si una entidad objetivo las contiene completamente. Esto es contrario a COMPLETELY_CONTAINS. WITHIN_CLEMENTINI —El resultado será idéntico a WITHIN excepto si la totalidad de la entidad de las entidades de unión está sobre el límite de la entidad de destino, la entidad no se hará coincidir. Clementini define el polígono de límite como la línea que separa el interior del exterior; el límite de una línea se define como sus extremos y el límite de un punto siempre está vacío. ARE_IDENTICAL_TO —Las entidades en las entidades de unión se harán coincidir si son idénticas a una entidad objetivo. Tanto la entidad de unión como la de destino deben ser del mismo tipo de forma, punto a punto, línea a línea y polígono a polígono. BOUNDARY_TOUCHES —Las entidades de las entidades de unión se harán coincidir si tienen un límite que toca a una entidad objetivo. Cuando las entidades de unión y de destino son líneas o polígonos, el límite de la entidad de unión solo puede tocar el límite de la entidad de destino y ninguna parte de la entidad de unión puede cruzar el límite de la entidad de destino. SHARE_A_LINE_SEGMENT_WITH —Las entidades de las entidades de unión se harán coincidir si comparten un segmento de línea con una entidad objetivo. Las entidades de unión y de destino deben ser líneas o polígonos. CROSSED_BY_THE_OUTLINE_OF —Las entidades en las entidades de unión se harán coincidir si una entidad de destino está cruzada por su contorno. Las entidades de unión y de destino deben ser líneas o polígonos. Si se utilizan polígonos para las entidades objetivo o de unión, se utilizarán los límites (las líneas) del polígono. Se harán coincidir las líneas que se cruzan en un punto, no las que comparten un segmento de línea. HAVE_THEIR_CENTER_IN —Las entidades en las entidades de unión se harán coincidir si el centro de una entidad objetivo está dentro de las mismas. El centro de la entidad se calcula del modo siguiente: para los polígonos y los multipuntos se utiliza el centroide de la geometría y para la entrada de línea se utiliza el punto medio de la geometría. Especifique una distancia en el parámetro search_radius. CLOSEST —se hace coincidir la entidad en las entidades de unión que está más cerca de una entidad de destino. Consulte la sugerencia de uso para obtener más información. Especifique una distancia en el parámetro search_radius. CLOSEST_GEODESIC —Como CLOSEST, excepto que se utiliza una distancia geodésica en vez de una distancia planar. Elija esta opción si los datos cubren una gran extensión geográfica o si el sistema de coordenadas de las entradas no es adecuado para los cálculos de distancia	String
search_radius (Opcional)	Las entidades de unión que se encuentren dentro de esta distancia de una entidad de destino se considerarán para la unión espacial. El radio de búsqueda solo es válido cuando se especifica la relación espacial (match_option se configura en INTERSECT, WITHIN_A_DISTANCE, WITHIN_A_DISTANCE_GEODESIC, HAVE_THEIR_CENTER_IN, CLOSEST o CLOSEST_GEODESIC). Por ejemplo, si se utiliza un radio de búsqueda de 100 metros con la relación espacial WITHIN_A_DISTANCE, se unirá la entidad que se encuentre dentro de un radio de 100 metros de una entidad de destino. En las tres relaciones WITHIN_A_DISTANCE, si no se especifica ningún valor en search_radius, se utiliza una distancia de 0.	Linear Unit
distance_field_name (Opcional)	Nombre de un campo que se va a agregar a la clase de entidad de salida que contiene la distancia entre la entidad de destino y la entidad de unión más cercana. Este parámetro solo es válido cuando se especifica la relación espacial (match_option se configura en CLOSEST o CLOSEST_GEODESIC). El valor de este campo es -1 si no coincide ninguna entidad dentro de un radio de búsqueda. Si no se especifica ningún nombre de campo, el campo no se agregará a la clase de entidad de salida.	String

Muestra de código

Ejemplo 1 de SpatialJoin (ventana de Python)

En el siguiente script se muestra cómo utilizar la función SpatialJoin en una ventana de Python.

import arcpy

target_features = "C:/data/usa.gdb/states"
join_features = "C:/data/usa.gdb/cities"
out_feature_class = "C:/data/usa.gdb/states_cities"

arcpy.SpatialJoin_analysis(target_features, join_features, out_feature_class)

Ejemplo 2 de SpatialJoin (script independiente)

El siguiente script independiente muestra cómo utilizar la función SpatialJoin para unir los atributos de las ciudades a los estados.

# Name: SpatialJoin_Example2.py
# Description: Join attributes of cities to states based on spatial relationships.
# Requirements: os module

# Import system modules
import arcpy
import os

# Set local variables
workspace = r"C:\gpqa\mytools\spatialjoin\usa.gdb"
outWorkspace = r"C:\gpqa\mytools\spatialjoin\output.gdb"
 
# Want to join USA cities to states and calculate the mean city population
# for each state
targetFeatures = os.path.join(workspace, "states")
joinFeatures = os.path.join(workspace, "cities")
 
# Output will be the target features, states, with a mean city population field (mcp)
outfc = os.path.join(outWorkspace, "states_mcp2")
 
# Create a new fieldmappings and add the two input feature classes.
fieldmappings = arcpy.FieldMappings()
fieldmappings.addTable(targetFeatures)
fieldmappings.addTable(joinFeatures)
 
# First get the POP1990 fieldmap. POP1990 is a field in the cities feature class.
# The output will have the states with the attributes of the cities. Setting the
# field's merge rule to mean will aggregate the values for all of the cities for
# each state into an average value. The field is also renamed to be more appropriate
# for the output.
pop1990FieldIndex = fieldmappings.findFieldMapIndex("POP1990")
fieldmap = fieldmappings.getFieldMap(pop1990FieldIndex)
 
# Get the output field's properties as a field object
field = fieldmap.outputField
 
# Rename the field and pass the updated field object back into the field map
field.name = "mean_city_pop"
field.aliasName = "mean_city_pop"
fieldmap.outputField = field
 
# Set the merge rule to mean and then replace the old fieldmap in the mappings object
# with the updated one
fieldmap.mergeRule = "mean"
fieldmappings.replaceFieldMap(pop1990FieldIndex, fieldmap)
 
# Delete fields that are no longer applicable, such as city CITY_NAME and CITY_FIPS
# as only the first value will be used by default
x = fieldmappings.findFieldMapIndex("CITY_NAME")
fieldmappings.removeFieldMap(x)
y = fieldmappings.findFieldMapIndex("CITY_FIPS")
fieldmappings.removeFieldMap(y)
 
#Run the Spatial Join tool, using the defaults for the join operation and join type
arcpy.SpatialJoin_analysis(targetFeatures, joinFeatures, outfc, "#", "#", fieldmappings)

Entornos

Valor Z de salida predeterminado, Resolución M, Tolerancia M, Palabra clave CONFIG de salida, Dominio M de salida, Dominio XY de salida, Dominio Z de salida, Sistema de coordenadas de salida, Extensión, La salida tiene valores M, La salida tiene valores Z, Resolución XY, Tolerancia XY, Resolución Z, Tolerancia Z

Información de licenciamiento

• Basic: Sí
• Standard: Sí
• Advanced: Sí