require(["esri/dijit/analysis/AggregatePoints"], function(AggregatePoints) { /* code goes here */ });
Description
(Added at v3.6)
The AggregatePoints widget works with point feature layer and a polygon feature layer. It first figures out which points fall within each polygon's area. After determining this point-in-polygon spatial relationship, statistics about all points in the polygon are calculated and assigned to the area. These statistics include count, sum, mean, minimum, maximum and standard deviation.
View the
ArcGIS REST API documentation for the
Aggregate Points task for more details.
Samples
Search for
samples that use this class.
Class hierarchy
esri/dijit/analysis/AnalysisBase
|_esri/dijit/analysis/AggregatePoints
Constructors
CSS
esri/dijit/analysis/AggregatePoints | Download source
Properties
analysisGpServer | String | The URL to the analysis service, for example "http://analysis.arcgis.com/arcgis/rest/services/tasks/GPServer". |
folderId | String | Sets the selected folder of the select folder dropdown, based on the provided folderId , when showSelectFolder is true. |
folderName | String | Sets the selected folder of the select folder dropdown, based on the provided folderName , when showSelectFolder is true. |
groupByField | String | A field name from pointLayer based on which the points will be grouped. |
keepBoundariesWithNoPoints | Boolean | When true, the polygons that have no points within them will be returned in the output. |
map | Map | Reference to the map object. |
minorityMajority | Boolean | 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. |
outputLayerName | String | The name of the output layer to be shown in the Result layer name inputbox. |
percentPoints | Boolean | When true, a new field will be added to the result table containing the percentages of each attribute value within each group. |
pointLayer | FeatureLayer | The point feature layer that will be aggregated into the polygons in the polygon feature layer. |
polygonLayer | FeatureLayer | The polygon layer to be shown selected in in the Choose area menu. |
polygonLayers | FeatureLayer[] | An array of feature layer candidates to be selected as the input polygon layer. |
portalSelf | Object | The self response of the Portal. |
portalUrl | String | The URL to the ArcGIS.com site or in-house portal where the GP server is hosted, for example "http://www.arcgis.com". |
returnFeatureCollection | Boolean | When true, returns the result of analysis as a client-side feature collection. |
showChooseExtent | Boolean | When true, the choose extent checkbox will be shown. |
showCloseIcon | Boolean | Indicates whether to show the close icon on the widget's user interface. |
showCredits | Boolean | When true, the show credit option is visible. |
showHelp | Boolean | When true, the help links will be shown. |
showReadyToUseLayers | Boolean | When true , adds an option to the UI that allows users to choose ready to use analysis layers from the Living Atlas Analysis Layers. |
showSelectAnalysisLayer | Boolean | Indicates whether to display a drop down menu listing valid input analysis layers. |
showSelectFolder | Boolean | When true, the select folder dropdown will be shown. |
summaryFields | String[] | An array of attribute field names and statistic types that you would like to aggregate for all points within each polygon. |
title | String | Overrides the default widget title with a custom title. |
Methods
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
close | | Fires 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
Creates a new AggregatePoints 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. |
<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. |
<String > groupByField |
Optional |
A field name from pointLayer based on which the points will be grouped. This will be shown selected in the Choose field to group by (optional) menu by default. If not specified, users can still select a field. |
<Boolean > keepBoundariesWithNoPoints |
Optional |
When true, the polygons that have no points within them will be returned in the output. |
<Map > map |
Optional |
Reference to the map object.
* Required when showChooseExtent is true . |
<String > outputLayerName |
Optional |
The name of the output layer to be shown in the Result layer name inputbox. If not specified, "Aggregation of ${point_layer_title} to ${polygon_layer_title}" will be shown by default. |
<FeatureLayer > pointLayer |
Required |
The point feature layer that will be aggregated into the polygons in the polygon feature layer.
* Required. |
<FeatureLayer > polygonLayer |
Required |
The polygon layer to be shown selected in in the Choose area menu. Must be one of the layers specified in polygonLayers .
* Required. |
<FeatureLayer[] > polygonLayers |
Required |
An array of feature layer candidates to be selected as the input polygon layer. When a layer is selected by user, the AggregatePoints dijit will summarize points based on polygons on this polygon layer. These layer candidate will be shown in the Choose area menu.
* Required. |
<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. |
<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 > 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. |
<String[] > summaryFields |
Optional |
An array of attribute field names and statistic types that you would like to aggregate for all points within each polygon. The field names and statistic types your specify will be listed in the Add statistic (optional) menu. Note that even if you do not specify any, the default dropdown list will still allow users to select field names and statistic types.
Syntax: ["fieldName summaryType","fieldName summaryType", ...]
fieldName is the name of one of the numeric fields found in the input point layer.
summaryType is one of the following:
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.
Stddev - Finds the standard deviation of all the points in each polygon.
Note that the count of points within each polygon is always returned. |
Sample: require(["esri/dijit/analysis/AggregatePoints", ... ], function(AggregatePoints, ... ){
var aggregatePoints = new AggregatePoints({
pointLayer: pointlayer,
polygonLayers: polygonLayers,
portalUrl: "http://www.arcgis.com"
}, "analysis-tool");
});
Property Details
The URL to the analysis service, for example "http://analysis.arcgis.com/arcgis/rest/services/tasks/GPServer".
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)
Sets the selected folder of the select folder dropdown, based on the provided folderName
, when showSelectFolder
is true. (Added at v3.13)
A field name from pointLayer
based on which the points will be grouped. This will be shown selected in the Choose field to group by (optional) menu by default. If not specified, users can still select a field.
Sample: "groupByField": "Crime_type"
When true, the polygons that have no points within them will be returned in the output.
Known values: true | false
Default value: true
Reference to the map object.
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
The name of the output layer to be shown in the Result layer name inputbox. If not specified, "Aggregation of ${point_layer_title} to ${polygon_layer_title}"
will be shown by default.
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
The point feature layer that will be aggregated into the polygons in the polygon feature layer.
The polygon layer to be shown selected in in the Choose area menu. Must be one of the layers specified in polygonLayers
.
An array of feature layer candidates to be selected as the input polygon layer. When a layer is selected by user, the AggregatePoints
dijit will summarize points based on polygons on this polygon layer. These layer candidate will be shown in the Choose area menu.
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)
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)
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. (Added at v3.7)
Known values: true | false
Default value: false
When true, the choose extent checkbox will be shown.
Known values: true | false
Default value: true
Indicates whether to show the close icon on the widget's user interface. (Added at v3.14)
Known values: true | false
Default value: true
When true, the show credit option is visible.
Known values: true | false
Default value: true
When true, the help links will be shown.
Known values: true | false
Default value: true
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
Indicates whether to display a drop down menu listing valid input analysis layers. (Added at v3.14)
Known values: true | false
Default value: true
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
An array of attribute field names and statistic types that you would like to aggregate for all points within each polygon. The field names and statistic types your specify will be listed in the
Add statistic (optional) menu. Note that even if you do not specify any, the default dropdown list will still allow users to select field names and statistic types.
Syntax:
["fieldName summaryType","fieldName summaryType", ...]
fieldName
is the name of one of the numeric fields found in the input point layer.
summaryType
is one of the following:
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.
Stddev
- Finds the standard deviation of all the points in each polygon.
Note that the count of points within each polygon is always returned.
Sample: "summaryFields": ["Annual_Sales Sum", "Annual_Sales Mean"]
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)
Method Details
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. |
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. |
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);
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.
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,
//}
Finalizes the creation of the widget. (Added at v3.12)
Event Details
[ On Style Events | Connect Style Event ]
Fires when close icon is clicked or when run analysis button is clicked. (Added at v3.7)
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": {}
} |
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>
} |
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);
})
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": {}
} |
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. |
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": {}
} |
Fires when the execute method is called. (Added at v3.7)
Event Object Properties:
<Object > params |
The input job parameters. |
Fires when the job is closed.
Fires when the job is submitted after createservice is called.
Event Object Properties:
<Object > params |
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. |
Fires when the job in cancelled.
Event Object Properties:
<Object > response |
An response object returned by a GP server.{
"inputs": {},
"jobId": "j04c9eb46b5fd442ba93001a8682d551c",
"jobStatus": "esriJobCancelled",
"messages": <an array of message text>,
"results": {}
} |
Fires when the job fails.
Event Object Properties:
<Error > error |
The error message returned by a failed job. |
Fires after the job fetches result data.
Event Object Properties:
<Object > result |
An object containing the following properties:{
"_ssl": false,
"analysisReport": "report message",
"dataType": "GPString",
"paramName": "hotSpotsResultLayer",
"value": <a feature collection object>
} |
Fires when the job execution status is received.
Event Object Properties:
<Object > jobInfo |
An object containing job ID, job status, and the initial input parameters.{
jobId: "jf07254b24ffb4e67ba4daa311de45f00",
jobStatus: "esriJobSubmitted",
jobParams: <the jobParams property of this analysis tool>
} |
Fires when a job is submitted to the server for asynchronous processing.
Event Object Properties:
<Object > params |
The input job parameters. 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. |
Fires when the job succeeds.
Event Object Properties:
<Object > jobInfo |
An object containing job ID, job status, the initial input parameters, messages and result info.{
"inputs": {},
"jobId": "j00177ce97f8a4d01b0e8a44d735f5667",
"jobParams": <the jobParams property of this analysis tool>,
"jobStatus": "esriJobSucceeded"
"messages": <an array of message text>,
"results": {
"hotSpotsResultLayer": {
"paramUrl": "results/hotSpotsResultLayer"
},
"processInfo": {
"paramUrl": "results/processInfo"
}
}
} |
Fires when the job is saved.