Hide Table of Contents
esri/dijit/util
esri/layer/pixelFilters
esri/process
esri/workers
Class: SummarizeNearby

require(["esri/dijit/analysis/SummarizeNearby"], function(SummarizeNearby) { /* code goes here */ });

Description

(Added at v3.7)
The FindNearest widget works with two layers: an summarize nearby layer and a summary layer. For each feature on the summarize nearby layer, this widget finds features on the summary layer that are within a given distance to the summarize nearby layer. The output layer contains features from the summarize nearby layer with statistics summary from the summary layer. The distance can be defined by straight-line distance, driving distance, or driving time.

View the ArcGIS REST API documentation for the Summarize Nearby task for more details.

Samples

Search for samples that use this class.

Class hierarchy

esri/dijit/analysis/AnalysisBase
|_esri/dijit/analysis/SummarizeNearby

Constructors

NameSummary
new SummarizeNearby(params, srcNodeRef)Creates a new SummarizeNearby dijit using the given DOM node.

CSS

esri/dijit/analysis/SummarizeNearby | Download source

Properties

NameTypeSummary
analysisGpServerStringThe URL to the analysis service, for example "http://analysis.arcgis.com/arcgis/rest/services/tasks/GPServer".
distancesNumber[]An array of numbers that defines the search distance (for StraightLine or DrivingDistance) or time (for DrivingTime) shown in the distance input in the Find nearest features using a option.
enableTravelModesBooleanWhen true, Travel Modes (Driving Distance, Driving Time) are enabled for sumNearbyLayer with point geometries (esriGeometryPoint).
folderIdStringSets the selected folder of the select folder dropdown, based on the provided folderId, when showSelectFolder is true.
folderNameStringSets the selected folder of the select folder dropdown, based on the provided folderName, when showSelectFolder is true.
groupByFieldStringA field of the summarizeLayer features that you can use to calculate statistics separately for each unique attribute value.
mapMapReference to the map object.
minorityMajorityBooleanWhen true, two fields will be added to your result layer to indicate which attribute values within each group are the minority (least dominant) or the majority (most dominant) within each boundary.
nearTypeStringType of distance measurement shown as the defeault value in the Find nearest features using a option.
outputLayerNameStringThe name of the output layer to be shown in the Result layer name inputbox.
percentPointsBooleanWhen true, a new field will be added to the result table containing the percentages of each attribute value within each group.
portalSelfObjectThe self response of the Portal.
portalUrlStringThe URL to the ArcGIS.com site or in-house portal where the GP server is hosted, for example "http://www.arcgis.com".
returnFeatureCollectionBooleanWhen true, returns the result of analysis as a client-side feature collection.
shapeUnitsStringType of units shown under the Total Area checkbox in the Add statistics from option.
showChooseExtentBooleanWhen true, the choose extent checkbox will be shown.
showCloseIconBooleanIndicates whether to show the close icon on the widget's user interface.
showCreditsBooleanWhen true, the show credit option is visible.
showHelpBooleanWhen true, the help links will be shown.
showReadyToUseLayersBooleanWhen true, adds an option to the UI that allows users to choose ready to use analysis layers from the Living Atlas Analysis Layers.
showSelectAnalysisLayerBooleanIndicates whether to display a drop down menu listing valid input analysis layers.
showSelectFolderBooleanWhen true, the select folder dropdown will be shown.
sumNearbyLayerFeatureLayerThe point, line, or polygon feature layer from which distances will be measured to features in summarizeLayer.
sumShapeBooleanIf true.
summaryFieldsString[]An array of possible statistics attribute field names and summary types that you wish to calculate for all nearby features.
summaryLayerFeatureLayerThe feature layer to be shown selected in the Choose layer to summarize dropdown.
summaryLayersFeatureLayer[]An array of possible feature layers summarizing toward.
titleStringOverrides the default widget title with a custom title.
unitsStringType of units shown as the defeault value in the Find nearest features using a option.

Methods

NameReturn typeSummary
cancel(jobInfo)NoneCancels an analysis job that is being processed.
checkJobStatus(jobId)NoneStarts checking the analysis job status for the given jobId.
execute(params)NoneStarts an analysis tool.
getCreditsEstimate(toolName, jobParams)DeferredGets credits estimate for a specific analysis job.
startup()NoneFinalizes the creation of the widget.

Events

[ On Style Events | Connect Style Event ]
All On Style event listeners receive a single event object. Additionally, the event object also contains a 'target' property whose value is the object which fired the event.

Events

NameEvent ObjectSummary
closeFires when close icon is clicked or when run analysis button is clicked.
job-cancel
{
  response: <Object>
}
Fires when the job in cancelled.
job-fail
{
  error: <Object>
}
Fires when the job fails.
job-result
{
  result: <Object>
}
Fires after the job fetches result data.
job-status
{
  jobInfo: <Object>
}
Fires when the job execution status is received.
job-submit
{
  params: <Object>
}
Fires when the job is submitted to the server for asynchronous processing.
job-success
{
  jobInfo: <Object>
}
Fires when the job succeeds.
start
{
  params: <Object>
}
Fires when the execute method is called.
Constructor Details

new SummarizeNearby(params, srcNodeRef)

Creates a new SummarizeNearby dijit using the given DOM node.
Parameters:
<Object> params Required Various options to configure this dijit. All the properties can be passed into the params object except toolName, helpFileName and resultParameter.
<Node | String> srcNodeRef Required Reference or id of a HTML element that this dijit is rendered into.
params properties:
<String> analysisGpServer Optional The URL to the GPServer used to execute an analysis job.

* Required when portalUrl is not specified.
<Number[]> distance Optional An array of numbers that defines the search distance (for StraightLine or DrivingDistance) or time (for DrivingTime) shown in the distance input in the Find nearest features using a option.
<Boolean> enableTravelModes Optional When true, Travel Modes (Driving Distance, Driving Time) are enabled for sumNearbyLayer with point geometries (esriGeometryPoint). Default is true.
<String> groupByField Optional A field of the summarizeLayer features that you can use to calculate statistics separately for each unique attribute value.
<Map> map Optional Reference to the map object.

* Required when showChooseExtent is true.
<String> nearType Optional Type of distance measurement shown as the defeault value in the Find nearest features using a option. Available values are "StraightLine", "DrivingDistance", "DrivingTime". Default value is "StraightLine".
<String> outputLayerName Optional The name of the output layer to be shown in the Result layer name inputbox. If not specified, "Summarize ${summary_layer_title} in ${sum_nearby_layer_title}" will be shown by default.
<String> portalUrl Optional The url to the ArcGIS.com site or in-house portal where the GP server is hosted.

* Required when analysisGpServer is not specified.
<Boolean> returnFeatureCollection Optional When true, returns the result of analysis as a client-side feature collection. This value determines whether or not the result will be saved and published on a user's arcgis.com account.
<String> shapeUnits Optional Type of units shown under the Total Area checkbox in the Add statistics from option.

When summarizeLayer contains polygons, the value can be "Acres", "Hectares", "SquareMeters", "SquareKilometers", "SquareFeet", or "SquareYards". When summarizeLayer contains lines, the value can be "SquareMiles", "Meters", "Kilometers", "Feet", "Yards", or "Miles".
<Boolean> showChooseExtent Optional When true, the choose extent checkbox will be shown.
<Boolean> showCredits Optional When true, the show credit option is visible.
<Boolean> showHelp Optional When true, the help links will be shown.
<Boolean> showSelectAnalysisLayer Optional Indicates whether to display a drop down menu listing valid input analysis layers.
<Boolean> showSelectFolder Optional When true, the select folder dropdown will be shown. This parameter should be used when you want to allow users to select a folder in their arcgis.com account where the output feature layer will be exported as a service.
<FeatureLayer[]> sumNearbyLayers Required The point, line, or polygon feature layers from which distances will be measured to features in summarizeLayer.

* Required.
<Boolean> sumShape Optional If true. The Total Area checkbox in the Add statistics from option will be checked. Default value is true.
<String[]> summaryFields Optional

An array of possible statistics attribute field names and summary types that you wish to calculate for all nearby features.

Syntax: ["fieldName summaryType","fieldName summaryType", ...]

  • fieldName is the name of one of the numeric fields found in the summarizeLayer.
  • summaryType is one of the following:
    • Sum - Adds the total value of all nearby features.
    • Mean - Calculates the average of all nearby features.
    • Min - Finds the smallest value of all nearby features.
    • Max - Finds the largest value of all nearby features.
    • Stddev - Finds the standard deviation of all nearby features.

<FeatureLayer> summaryLayer Optional The feature layer to be shown selected in the Choose layer to summarize dropdown.
<FeatureLayer[]> summaryLayers Required An array of possible feature layers summarizing toward. Each of these feature layers can be a point, line, or polygon feature layer, where features that are within the specified distance to features in the sumNearbyLayer will be summarized.

* Required.
<String> units Optional Type of units shown as the defeault value in the Find nearest features using a option. Available options are Meters, Kilometers, Feet, Yards, Miles (When nearType is StraightLine or DrivingDistance); Seconds, Minutes, Hours (When nearType is DrivingTime). Default value is Meters.
Sample:
require(["esri/dijit/analysis/SummarizeNearby", ... ], function(SummarizeNearby, ... ){
  var summarizeNearby = new SummarizeNearby({
    sumNearbyLayer: pointlayer,
    summaryLayers: flayers,
    map: map,        
    portalUrl: "http://www.arcgis.com"
  }, "analysis-tool");
});
Property Details

<String> analysisGpServer

The URL to the analysis service, for example "http://analysis.arcgis.com/arcgis/rest/services/tasks/GPServer".

<Number[]> distances

An array of numbers that defines the search distance (for StraightLine or DrivingDistance) or time (for DrivingTime) shown in the distance input in the Find nearest features using a option.
Default value: [ 5 ]
Sample:
[4.0, 5.0, 6.0]

<Boolean> enableTravelModes

When true, Travel Modes (Driving Distance, Driving Time) are enabled for sumNearbyLayer with point geometries (esriGeometryPoint). (Added at v3.10)
Known values: true | false
Default value: true

<String> folderId

Sets the selected folder of the select folder dropdown, based on the provided folderId, when showSelectFolder is true. When folderId and folderName are both provided, folderId has higher precedence. (Added at v3.13)

<String> folderName

Sets the selected folder of the select folder dropdown, based on the provided folderName, when showSelectFolder is true. (Added at v3.13)

<String> groupByField

A field of the summarizeLayer features that you can use to calculate statistics separately for each unique attribute value.

<Map> map

Reference to the map object.

<Boolean> minorityMajority

When true, two fields will be added to your result layer to indicate which attribute values within each group are the minority (least dominant) or the majority (most dominant) within each boundary. If percentPoints is also true, two additional fields will be added to the result layer containing the percentages of the minority and majority attribute values within each group. (Added at v3.12)
Known values: true | false
Default value: false

<String> nearType

Type of distance measurement shown as the defeault value in the Find nearest features using a option.
Known values: "StraightLine" | "DrivingDistance" | "DrivingTime"
Default value: "StraightLine"

<String> outputLayerName

The name of the output layer to be shown in the Result layer name inputbox. If not specified, "Summarize ${summary_layer_title} in ${sum_nearby_layer_title}" will be shown by default.

<Boolean> percentPoints

When true, a new field will be added to the result table containing the percentages of each attribute value within each group. If minorityMajority is also true, two additional fields will be added to the result layer containing the percentages of the minority and majority attribute values within each group. (Added at v3.12)
Known values: true | false
Default value: false

<Object> portalSelf

The self response of the Portal. When set, optimizes performance to reuse self calls made by the widget. For more documentation on the properties of this object, see the Portal Self ArcGIS REST API documentation. (Added at v3.14)

<String> portalUrl

The URL to the ArcGIS.com site or in-house portal where the GP server is hosted, for example "http://www.arcgis.com". (Added at v3.7)

<Boolean> returnFeatureCollection

When true, returns the result of analysis as a client-side feature collection. This value determines whether or not the result will be saved and published on a user's arcgis.com account.
Known values: true | false
Default value: false

<String> shapeUnits

Type of units shown under the Total Area checkbox in the Add statistics from option.
Known values: "Acres" | "Hectares" | "SquareMeters" | "SquareKilometers" | "SquareFeet" | "SquareYards" (When summarizeLayer contains polygons); "SquareMiles" | "Meters" | "Kilometers" | "Feet" | "Yards" | "Miles" (When summarizeLayer contains lines).
Default value:

<Boolean> showChooseExtent

When true, the choose extent checkbox will be shown.
Known values: true | false
Default value: true

<Boolean> showCloseIcon

Indicates whether to show the close icon on the widget's user interface. (Added at v3.14)
Known values: true | false
Default value: true

<Boolean> showCredits

When true, the show credit option is visible.
Known values: true | false
Default value: true

<Boolean> showHelp

When true, the help links will be shown.
Known values: true | false
Default value: true

<Boolean> showReadyToUseLayers

When true, adds an option to the UI that allows users to choose ready to use analysis layers from the Living Atlas Analysis Layers. (Added at v3.14)
Known values: true | false
Default value: true

<Boolean> showSelectAnalysisLayer

Indicates whether to display a drop down menu listing valid input analysis layers. (Added at v3.14)
Known values: true | false
Default value: true

<Boolean> showSelectFolder

When true, the select folder dropdown will be shown. This parameter should be used when you want to allow users to select a folder in their arcgis.com account where the output feature layer will be exported as a service.
Known values: true | false
Default value: false

<FeatureLayer> sumNearbyLayer

The point, line, or polygon feature layer from which distances will be measured to features in summarizeLayer.

<Boolean> sumShape

If true. The Total Area checkbox in the Add statistics from option will be checked.
Known values: true | false
Default value: true

<String[]> summaryFields

An array of possible statistics attribute field names and summary types that you wish to calculate for all nearby features.

Syntax: ["fieldName summaryType","fieldName summaryType", ...]

  • fieldName is the name of one of the numeric fields found in the summarizeLayer.
  • summaryType is one of the following:
    • Sum - Adds the total value of all nearby features.
    • Mean - Calculates the average of all nearby features.
    • Min - Finds the smallest value of all nearby features.
    • Max - Finds the largest value of all nearby features.
    • Stddev - Finds the standard deviation of all nearby features.

Sample:
"SummaryFields": ["Lot_Value Sum", "Lot_Value Mean"]

<FeatureLayer> summaryLayer

The feature layer to be shown selected in the Choose layer to summarize dropdown.

<FeatureLayer[]> summaryLayers

An array of possible feature layers summarizing toward. Each of these feature layers can be a point, line, or polygon feature layer, where features that are within the specified distance to features in the sumNearbyLayer will be summarized.

<String> title

Overrides the default widget title with a custom title. Set this value in the initial constructor parameters.

For example, instead of using the default title (for example "Find Hot Spots"), you can use this property to change the default to a customized title for the tool (for example "Areas with High Crime"). (Added at v3.14)

<String> units

Type of units shown as the defeault value in the Find nearest features using a option.
Known values: Meters | Kilometers | Feet | Yards | Miles (When nearType is StraightLine or DrivingDistance); Seconds | Minutes | Hours (When nearType is DrivingTime)
Default value: "Meters"
Method Details

cancel(jobInfo)

Cancels an analysis job that is being processed.
Parameters:
<Object> jobInfo Required An object containing job information including job ID, status, message, etc returned by the job-status event.

checkJobStatus(jobId)

Starts checking the analysis job status for the given jobId. (Added at v3.12)
Parameters:
<String> jobId Required Job id of the analysis job to check.

execute(params)

Starts an analysis tool.
Parameters:
<String> params Required See the object specifications table below for the structure of the params object.
Object Specifications:
<params>
<Object> itemParams Optional Parameters for creating the output service item. Refer to the ArcGIS REST API - Add Item help topic for a list of available parameters. Only used when the analysis task creates a hosted service.
<Object> jobParams Required The input job parameters. Required parameters vary from class to class. Refer to the Analysis REST API Documentation for details (Under the Request Parameters section of each task). When creating a hosted service, a layer name is required.
Sample:
var params = {
  itemParams: {
    description: "Item description.",
    snippet: "A short summary about this item.",
    tags: "<tag1>, <tag2>, <tag3>, ... ",
    typeKeywords: "<typeKeyword1>, <typeKeyword2>, <typeKeyword3>, ... "
  },
  jobParams: {
    outputLayerName: "{\"serviceProperties\":{\"name\":\"Name of the output feature service\"},\"itemProperties\":{\"itemId\":\"<itemId>\"}}",
    ...
  }
}

analysisBase.execute(params);

getCreditsEstimate(toolName, jobParams)

Gets credits estimate for a specific analysis job. This method returns a deferred object. The callback function has an object containing the number of records to be processed and the estimated credit cost for this job.
Return type: Deferred
Parameters:
<String> toolName Required The name of the analysis tool from which a credits estimate will be returned.
<String> jobParams Required The input job parameters. This value should be the same as the jobParams property of an analysis tool dijit. Refer to the jobParams property of this class for detailed syntax.
Sample:
analysisBase.getCreditsEstimate("FindHotSpots",{
  AnalysisLayer: layer._json,
  context: '{"outSR":{"wkid":102100}}',
  isProcessInfo: true,
  returnFeatureCollection: true
}).then(function(result){
  console.log(result);
});

//the "result" argument above:
//{
//  "cost": 1.472,
//  "totalRecords": 1472,
//}

startup()

Finalizes the creation of the widget. (Added at v3.12)
Event Details
[ On Style Events | Connect Style Event ]

close

Fires when close icon is clicked or when run analysis button is clicked. (Added at v3.7)

job-cancel

Fires when the job in cancelled. (Added at v3.7)
Event Object Properties:
<Object> response An GP job object returned by the GP server. Refer to the GP Job and the Checking job status topics in the ArcGIS REST API Documentation for more information and syntax.
{
  "inputs": {},
  "jobId": <job id>,
  "jobStatus": <job status>,
  "messages": <an array of message text>,
  "results": {}
}

job-fail

Fires when the job fails. (Added at v3.7)
Event Object Properties:
<Object> error The error message returned by a failed job.
{
  "analysisReport": <analysis report message>,
  "dataType": <analysis report message>,
  "paramName": < parameter  name >,
  "value": <output item info | feature collection>
}

job-result

Fires after the job fetches result data. The returned argument contains the output value (either a feature collection or a url to the hosted service), which you may add to the map as a feature layer. (Added at v3.7)
Event Object Properties:
<Object> result An object containing the resulted message and value. Based on the GP result object returned by the GP server with the analysisReport property added.

If output is a feature collection, value is a feature collection object; if output is a hosted arcgis.com feature service, value is an object with item information including ID and URL. Refer to the ArcGIS REST API documentation - Feature Output for more information.
{
  "analysisReport": <analysis report message>,
  "dataType": <analysis report message>,
  "paramName": < parameter  name >,
  "value": <output item info | feature collection>
}
Sample:
analysisTool.on("job-result", function(result){
  var featureLayer = new FeatureLayer(result.value['url'] || result.value);
  map.addLayer(featureLayer);
})

job-status

Fires when the job execution status is received. (Added at v3.7)
Event Object Properties:
<Object> jobInfo An object containing job information including job ID, status, message, etc. Based on the GP job object returned by the GP server with the jobParam property attached. Refer to the GP Job and the Checking job status topics in the ArcGIS REST API Documentation for more information and syntax.
{
  "inputs": {},
  "jobParams": <job parameters>,
  "jobId": <job id>,
  "jobStatus": <job status>,
  "messages": <an array of message text>,
  "results": {}
}

job-submit

Fires when the job is submitted to the server for asynchronous processing. (Added at v3.7)
Event Object Properties:
<Object> params The input job parameters.

job-success

Fires when the job succeeds. (Added at v3.7)
Event Object Properties:
<Object> jobInfo An object containing job information including job ID, status, message, etc. Based on the GP job object returned by the GP server with the jobParam property attached. Refer to the GP Job and the Checking job status topics in the ArcGIS REST API Documentation for more information and syntax.

This returned object can be passed into the .cancel(jobInfo) method to terminate a job.
{
  "inputs": {},
  "jobParams": <job parameters>,
  "jobId": <job id>,
  "jobStatus": <job status>,
  "messages": <an array of message text>,
  "results": {}
}

start

Fires when the execute method is called. (Added at v3.7)
Event Object Properties:
<Object> params The input job parameters.