arcgis.geoanalytics.summarize_data module

This aggregate_points tool works with a layer of point features and a layer of areas. The layer of areas can be an input polygon layer or it can be square or hexagonal bins calculated when the task is run. The tool first determines which points fall within each specified area. After determining this point-in-area spatial relationship, statistics about all points in the area are calculated and assigned to the area. The most basic statistic is the count of the number of points within the area, but you can get other statistics as well.

For example, suppose you have point features of coffee shop locations and area features of counties, and you want to summarize coffee sales by county. Assuming the coffee shops have a TOTAL_SALES attribute, you can get the sum of all TOTAL_SALES within each county, the minimum or maximum TOTAL_SALES within each county, or other statistics like the count, range, standard deviation, and variance.

This tool can also work on data that is time-enabled. If time is enabled on the input points, then the time slicing options are available. Time slicing allows you to calculate the point-in area relationship while looking at a specific slice in time. For example, you could look at hourly intervals, which would result in outputs for each hour.

For an example with time, suppose you had point features of every transaction made at a coffee shop location and no area layer. The data has been recorded over a year, and each transaction has a location and a time stamp. Assuming each transaction has a TOTAL_SALES attribute, you can get the sum of all TOTAL SALES within the space and time of interest. If these transactions are for a single city, we could generate areas that are one kilometer grids, and look at weekly time slices to summarize the transactions in both time and space.

Returns

result_layer : Output Features as FeatureLayer.

# Usage Example: To aggregate number of 911 calls within 1 km summarized by Day count.

agg_result = aggregate_points(calls,
                              bin_size=1,
                              bin_size_unit='Kilometers',
                              time_step_interval=1,
                              time_step_interval_unit="Years",
                              summary_fields=[{"statisticType": "Count", "onStatisticField": "Day"}],
                              output_name='testaggregatepoints01')

The build_multivariable_grid task works with one or more layers of point, line, or polygon features. The task generates a grid of square or hexagonal bins and compiles information about each input layer into each bin. For each input layer, this information can include the following variables:

• Distance to Nearest - The distance from each bin to the nearest feature.

• Attribute of Nearest - An attribute value of the feature nearest to each bin.

• Attribute Summary of Related - A statistical summary of all features within search_distance of each bin.

Only variables you specify in variable_calculations will be included in the result layer. These variables can help you understand the proximity of your data throughout the extent of your analysis. The results can help you answer questions such as the following:

• Given multiple layers of public transportation infrastructure, what part of the city is least accessible by public transportation?

• Given layers of lakes and rivers, what is the name of the water body closest to each location in the U.S.?

• Given a layer of household income, where in the U.S. is the variation of income in the surrounding 50 miles the greatest?

The result of build_multivariable_grid can also be used in prediction and classification workflows. The task allows you to calculate and compile information from many different data sources into a single, spatially continuous layer in one step. This layer can then be used with the Enrich From Multi-Variable Grid task to quickly enrich point features with the variables you have calculated, reducing the amount of effort required to build prediction and classification models from point data.

variable_calculations =
 [
  {
      "layer":<index>,
      "variables":[
          {
              "type":"DistanceToNearest",
              "outFieldName":"<output field name>",
              "searchDistance":<number>,
              "searchDistanceUnit":"<unit>",
              "filter":"<filter>"
          },
          {
              "type":"AttributeOfNearest",
              "outFieldName":"<output field name>",
              "attributeField":"<field name>",
              "searchDistance":<number>,
              "searchDistanceUnit":"<unit>",
              "filter":"<filter>"
          },
          {
              "type":"AttributeSummaryOfRelated",
              "outFieldName":"<output field name>",
              "statisticType":"<statistic type>",
              "statisticField":"<field name>",
              "searchDistance":<number>,
              "searchDistanceUnit":"<unit>",
              "filter":"<filter>"
          },
        ]
      },
    ]

Returns

boolean

# Usage Example: To create multivariable grid by summarizing information such as distance to nearest

variables = [ { "layer":0,
                "variables":[
                    { "type":"DistanceToNearest",
                      "outFieldName":"road",
                      "searchDistance":10,
                      "searchDistanceUnit":"Kilometers"
                    }
                ]
              },
              { "layer":1,
              "variables":[
                  { "type":"AttributeSummaryOfRelated",
                    "outFieldName":"MeanPopAge",
                    "statisticType":"Mean",
                    "statisticField":"Age",
                    "searchDistance":50,
                    "searchDistanceUnit":"Kilometers"
                  }
              ]
              }
            ]
grid = build_multivariable_grid(input_layers=[lyr0, lyr1],
                                variable_calculations=variables,
                                bin_size=100,
                                bin_unit='Meters',
                                bin_type='Square',
                                output_name="multi_variable_grid")

The describe_dataset task provides an overview of your big data. The tool outputs a feature layer representing a sample of your input features or a single polygon feature layer that represents the extent of your input features. You can choose to output one, both, or none.

For example, imagine you are tasked with completing an analysis workflow on a large volume of data. You want to try the workflow, but it could take hours or days with your full dataset. Instead of using time and resources running the full analysis, first create a sample layer to efficiently test your workflow before running it on the full dataset.

See Describe Dataset for additional information.

Returns

• if return_tuple is True, an tuple with the following keys:

  • ”output_json” : dict

  • ”output” : Layer

  • ”extent_layer” : FeatureLayer

  • ”sample_layer” : FeatureLayer

  • ”process_info” : list

• if return_tuple`` is False:

  • FeatureLayer of the results.

• if future is True:

  • a job object with a result() method to access results

# Usage Example: To get an overview of your big data item

data = describe_dataset(input_layer=big_data_layer,
                        extent_output=True,
                        sample_size=2000,
                        output_name="describe dataset")

Using either feature layers or tabular data, you can join features and records based on specific relationships between the input layers or tables. Joins will be determined by spatial, temporal, and attribute relationships, and summary statistics can be optionally calculated.

For example

• Given point locations of crime incidents with a time, join the crime data to itself specifying a spatial relationship of crimes within 1 kilometer of each other and that occurred within 1 hour of each other to determine if there are a sequence of crimes close to each other in space and time.

• Given a table of ZIP Codes with demographic information and area features representing residential buildings, join the demographic information to the residences so each residence now has the information.

The join_features task works with two layers. join_features joins attributes from one feature to another based on spatial, temporal, and attribute relationships or some combination of the three. The tool determines all input features that meet the specified join conditions and joins the second input layer to the first. You can optionally join all features to the matching features or summarize the matching features.

join_features can be applied to points, lines, areas, and tables. A temporal join requires that your input data is time-enabled, and a spatial join requires that your data has a geometry.

See Join Features for additional information.

Parameter	Description
target_layer	Required layer. The table, point, line, or polygon features to be joined to. See Feature Input.
join_layer	Required layer. The point, line, or polygon features that will be joined to the target_layer. See Feature Input.
join_operation	Optional string. A string representing the type of join that will be applied. Choice list: JoinOneToOne - If multiple join features are found that have the same relationships with a single target feature, the attributes from the multiple join features will be aggregated using the specified summary statistics. For example, if a point target feature is found within two separate polygon join features, the attributes from the two polygons will be aggregated before being transferred to the output point feature class. If one polygon has an attribute value of 3 and the other has a value of 7, and a SummaryField of sum is selected, the aggregated value in the output feature class will be 10. There will always be a Count field calculated, with a value of 2, for the number of features specified. This is the default. JoinOneToMany - If multiple join features are found that have the same relationship with a single target feature, the output feature class will contain multiple copies (records) of the target feature. For example, if a single point target feature is found within two separate polygon join features, the output feature class will contain two copies of the target feature: one record with the attributes of the first polygon, and another record with the attributes of the second polygon. There are no summary statistics calculated with this method. The default value is JoinOneToOne.
join_fields	Optional list of dicts. A list of modifications to field names in the joinLayer to be made before completing analysis. Any field that is removed will not have statistics calculated on it. Syntax: [{ "action" : "action", "field" : "fieldname1"}, { "action" : "action", "field" : "initial_fieldname", "to" : "new_fieldname"}] action can be the following: remove - Remove a field from analysis and output . rename - Rename a field before running analysis.
summary_fields	Optional list of dicts. A list of field names and statistical summary types you want to calculate. Note that the count is always returned. By default, all statistics are returned. Syntax: [{"statisticType" : "<statistic type>", "onStatisticField" : "<field name>" }, ...] onStatisticField is the name of the field in the target layer. statisticType is one of the following: for numeric fields: Count - Totals the number of values of all the points in each polygon. Sum - Adds the total value of all the points in each polygon. Mean - Calculates the average of all the points in each polygon. Min - Finds the smallest value of all the points in each polygon. Max - Finds the largest value of all the points in each polygon. Range - Finds the difference between the Min and Max values. Stddev - Finds the standard deviation of all the points in each polygon. Var - Finds the variance of all the points in each polygon. for string fields: Count - Totals the number of strings for all the points in each polygon. Any - Returns a sample string of a point in each polygon.
spatial_relationship	Optional string. Defines the spatial relationship used to spatially join features. Choice list: Equals Intersects Contains Within Crosses Touches Overlaps Near NearGeodesic
spatial_near_distance (Required if spatial_relationship is Near or NearGeodesic)	Optional float. A float value used for the search distance to determine if the target features are near the join features. Note This is only applied if Near or NearGeodesic is the selected spatial_relationship. You can only enter a single distance value. The unit value is supplied by the spatial_near_distance parameter.
spatial_near_distance_unit (Required if spatial_relationship is Near or NearGeodesic)	Optional string. The linear unit to be used with the distance value specified in spatial_near_distance. Choice list: Feet Yards Miles Meters Kilometers NauticalMiles
temporal_relationship	Optional string. Defines the temporal relationship used to temporally join features. Choice list : Equals Intersects During Contains Finishes FinishedBy Meets MetBy Overlaps OverlappedBy Starts StartedBy Near
temporal_near_distance (Required if temporal_relationship is Near, NearBefore, or NearAfter)	Optional integer. An integer value used for the temporal search distance to determine if the target features are temporally near the join features. Note This is only applied if Near, NearBefore, or NearAfter is the selected temporal_relationship. You can only enter a single value. distance value. The units of the distance values are supplied by the temporal_near_distance_unit parameter.
temporal_near_distance_unit (Required if temporal_relationship is Near, NearBefore, or NearAfter)	Optional string.The temporal unit to be used with the distance value specified in temporal_near_distance. Choice list: Years Months Weeks Days Hours Minutes Seconds Milliseconds
attribute_relationship	Optional list of dicts. A target field, relationship, and join field used to join equal attributes. Syntax: [{ "targetField" : "fieldname1", "joinField" : "fieldname2", "operator" : "operator" }]
join_condition	Optional string. Applies a condition to specified fields. Only features with fields that meet these conditions will be joined. For example, to apply a join to a dataset for only those features where health_spending is greater than 20 percent of income, apply a join condition of target[‘health_spending’] > (join[‘income’] * .20) using the field health_spending from the first dataset (target_layer) and the income field from the second dataset (join_layer).
output_name	Optional string. The task will create a feature service of the results. You define the name of the service.
gis	Optional GIS. The GIS object where the analysis will take place.
context	Optional dict. The context parameter contains additional settings that affect task execution. For this task, there are four settings: extent - A bounding box that defines the analysis area. Only those features that intersect the bounding box will be analyzed. processSR - The features will be projected into this coordinate system for analysis. outSR - The features will be projected into this coordinate system after the analysis to be saved. The output spatial reference for the spatiotemporal big data store is always WGS84. dataStore - Results will be saved to the specified data store. For ArcGIS Enterprise, the default is the spatiotemporal big data store.
future	Optional boolean. If True, a GPJob is returned instead of results. The GPJob can be queried on the status of the execution. The default value is False.
keep_target	Optional boolean. Specifies whether all target features will be maintained in the output feature class (known as a left outer join) or only those that have the specified relationships with the join features (inner join). This option is only available when the join_operation parameter is JoinOneToOne`. False (inner join) is the default. Note This parameter is available at ArcGIS Enterprise 10.9 and later.

return

Output Features as FeatureLayerCollection

# Usage Example: To find power outages in your state that may have been caused by a lightning strike.

output = join_features(target_layer=outages_layer,
                       join_layer=lightning,
                       join_operation="JoinOneToMany",
                       spatial_relationship="Near",
                       spatial_near_distance=20,
                       spatial_near_distance_unit="Miles",
                       temporal_relationship="NearAfter",
                       temporal_near_distance=30,
                       temporal_near_distance_unit="Minutes",
                       output_name="LightningOutages")

The reconstruct_tracks task works with a time-enabled layer of either point or polygon features that represents an instant in time. It first determines which features belong to a track using an identifier. Using the time at each location, the tracks are ordered sequentially and transformed into a line or polygon representing the path of movement over time. Optionally, the input can be buffered by a field, which will create a polygon at each location. These buffered points, or polygons if the inputs are polygons, are then joined sequentially to create a track as a polygon where the width is representative of the attribute of interest. Resulting tracks have start and end times that represent the time at the first and last feature in a given track. When the tracks are created, statistics about the input features are calculated and assigned to the output track. The most basic statistic is the count of points within the area, but other statistics can be calculated as well. Features in time-enabled layers can be represented in one of two ways:

• Instant - A single moment in time

• Interval - A start and end time

For example, suppose you have GPS measurements of hurricanes every 10 minutes. Each GPS measurement records the hurricane name, location, time of recording, and the wind speed. You could create tracks of the hurricanes using the name of the hurricane as the track identification, and all hurricanes’ tracks would be generated. You could calculate statistics such as the mean, maximum, and minimum wind speed of each hurricane, as well as the count of measurements in each track.

Returns

FeatureLayerCollection

# Usage Example: To reconstruct hurricane tracks.

tracks = reconstruct_tracks(input_layer=hurricane_lyr,
                            track_fields='season, trackID',
                            method='Geodesic',
                            buffer_field='size',
                            summary_fields=[{"statisticType" : "Range", "onStatisticField" : "Wind" }],
                            distance_split=1,
                            distance_split_unit='Kilometers',
                            time_boundary_split=1,
                            time_boundary_split_unit='Days',
                            output_name='reconstruct hurricane tracks')

Returns

FeatureLayerCollection

# Usage Example: To summarize similar types of storms to find the sum of property damage.

summarized_result = summarize_attributes(input_layer=storms,
                                         fields="Storm_type",
                                         summary_fields=[{"statisticType" : "Sum", "onStatisticField" : "PropertyDamage"}],
                                         output_name="summarized_storms")

The summarize_within task finds features (and portions of features) that are within the boundaries of areas in the first input layer. The following are examples:

• Given a layer of watershed boundaries and a layer of land-use boundaries, calculate the total acreage of land-use type for each watershed.

• Given a layer of parcels in a county and a layer of city boundaries, summarize the average value of vacant parcels within each city boundary.

• Given a layer of counties and a layer of roads, summarize the total mileage of roads by road type within each county.

You can think of summarize_within as taking two layers and stacking them on top of each other. One of the layers, summary_polygons, must be a polygon layer, and imagine that these polygon boundaries are all colored red. The other layer, summarized_layer, can be any feature type—point, line, or polygon. After stacking these layers on top of each other, you peer down through the stack and count the number of features in summarized_layer that fall within the polygons with the red boundaries (summary_polygons). Not only can you count the number of features, you can calculate simple statistics about the attributes of the features in summarized_layer, such as sum, mean, minimum, maximum, and so on.

Returns

FeatureLayer.

# Usage Example: To calculate the distance and average slope of bike lanes within each city district.

summarize_within_result = summarize_within(summary_polygons=districts,
                                           summarized_layer=bike_lanes,
                                           weighted_summary_fields=[{"statisticType" : "Average","onStatisticField" : "Slope"}],
                                           output_name="summary_of_bike_lanes")

The summarize_center_and_dispersion task finds central features and directional distributions. It can be used to answer questions such as the following:

• Where is the center?

• Which feature is the most accessible from all other features?

• How dispersed, compact, or integrated are the features?

• Are there directional trends?

For an example, suppose you have used the GeoAnalytics tool Find Point Clusters to identify groups of power outages across an entire year. The result will be time enabled point representing cluster locations of power outages. However, you are interested in identifying the center of the power outages for visualization. To do this, you use Summarize Center And Dispersion a group by field of the outage cluster ids.