pieChart

AMD: require(["esri/smartMapping/renderers/pieChart"], (pieChartRendererCreator) => { /* code goes here */ });
ESM: import * as pieChartRendererCreator from "@arcgis/core/smartMapping/renderers/pieChart";
Object: esri/smartMapping/renderers/pieChart
Since: ArcGIS API for JavaScript 4.24

This object contains a helper method for generating a pie chart for every feature.

For example, suppose you have a layer of U.S. counties with fields containing the total sales of various crops: wheat, soybeans, corn, cotton, and vegetables. You can use the createRenderer() method in this module to generate a chart for each feature visualizing the proportion of each crop type for every county.

Known Limitations

  • Only supported in 2D MapView.
  • Only supported in layers with point and polygon geometries.
See also

Method Overview

Name Return Type Summary Object
Promise<RendererResult>

Generates a PieChartRenderer based on a set of numeric fields.

more details
pieChart
Promise<ClusterRendererResult>

Generates a PieChartRenderer to use for a FeatureReductionCluster visualization based off an input layer's UniqueValueRenderer or ClassBreaksRenderer.

more details
pieChart

Method Details

createRenderer(params){Promise<RendererResult>}

Generates a PieChartRenderer based on a set of numeric fields.

Parameters
Specification
params Object

Input parameters for generating a pie chart visualization based on a set of numeric fields. See the table below for details of each parameter.

Specification

The layer for which the visualization is generated.

view MapView

The view instance in which the visualization will be rendered.

attributes Object[]

A set of complementary numeric fields/expressions used to create the charts. For example, if creating an election map, you would indicate the name of each field representing the candidate or political party where their total counts are stored.

Specification
field String
optional

The name of a numeric field.

label String
optional

The label describing the field name (or pie slice) in the legend. This is should be used if the given field doesn't have an intuitive field name or alias. For example, for a field named dem representing the total vote count for the Democratic party, you can set the label to Democrat to clarify the name of the category in the final visualization.

valueExpression String
optional

An Arcade expression following the specification defined by the Arcade Visualization Profile. Expressions may reference field values using the $feature profile variable and must return a number. This property overrides the field property and therefore is used instead of an input field value if both are specified.

valueExpressionTitle String
optional

Text describing the value returned from the valueExpression. This will display in the legend.

shape String
optional
Default Value: "pie"

Determines whether to create a pie chart or a donut chart.

Possible Values:"pie"|"donut"

includeSizeVariable Boolean
optional

Indicates whether to include data-driven size in the final renderer. If true, features will be assigned a sized based on the sum of all values in the attributes param. Features with small total counts will be sized with small charts and features with large total counts will be sized with large charts. Enabling this option is good for visualizing how influential a particular feature is compared to the dataset as a whole. It removes bias introduced by features with large geographic areas, but relatively small data values.

outlineOptimizationEnabled Boolean
optional
Default Value: false

Only for polygon layers. Indicates whether the polygon's background fill symbol outline width should vary based on view scale.

sizeOptimizationEnabled Boolean
optional
Default Value: false

Indicates whether chart sizes should vary based on view scale.

legendOptions Object
optional

Provides options for modifying Legend properties describing the visualization.

Specification
title String
optional

The title used to describe the renderer in the Legend.

pieChartScheme PieChartScheme
optional

In authoring apps, the user may select a pre-defined color scheme. Pass the scheme object to this property to avoid getting one based on the background of the view.

forBinning Boolean
optional

Indicates whether the generated renderer is for a binning visualization. If true, then the input field(s) in this method should refer to aggregate fields defined in the featureReduction property of the layer.

signal AbortSignal
optional

Allows for cancelable requests. If canceled, the promise will be rejected with an error named AbortError. See also AbortController.

Returns
Type Description
Promise<RendererResult> Resolves to an instance of RendererResult.
Example
const layer = new FeatureLayer({
  url: "https://services.arcgis.com/V6ZHFr6zdgNZuVG0/arcgis/rest/services/USA_County_Crops_2007/FeatureServer/0"
});

// will create a visualization of predominant crop by U.S. county

const params = {
  layer: layer,
  view: view,
  attributes: [{
    field: "M217_07",
    label: "Vegetables"
  }, {
    field: "M188_07",
    label: "Cotton"
  }, {
    field: "M172_07",
    label: "Wheat"
  }, {
    field: "M193_07",
    label: "Soybeans"
  }, {
    field: "M163_07",
    label: "Corn"
  }],
  includeSizeVariable: true,
  sizeOptimizationEnabled: true,
  shape: "donut"
};

// when the promise resolves, apply the renderer to the layer
const { renderer } = await pieChartRendererCreator.createRenderer(params);
layer.renderer = renderer;
createRendererForClustering(params){Promise<ClusterRendererResult>}
Since: ArcGIS API for JavaScript 4.25

Generates a PieChartRenderer to use for a FeatureReductionCluster visualization based off an input layer's UniqueValueRenderer or ClassBreaksRenderer. This method also generates aggregate fields that must be provided to the FeatureReductionCluster object to properly render.

Parameters
Specification
params Object

Input parameters for generating a pie chart visualization for clustering. See the table below for details of each parameter.

Specification

The layer for which the visualization is generated. To use the output cluster renderer, you must first enable clustering on the layer.

shape String
optional
Default Value: "pie"

Determines whether to create a pie chart or a donut chart.

Possible Values:"pie"|"donut"

defaultSymbolEnabled Boolean
optional
Default Value: true

Includes the defaultSymbol defined in the input layer's renderer in the output pie chart renderer.

legendOptions Object
optional

Provides options for modifying Legend properties describing the visualization.

Specification
title String
optional

The title used to describe the renderer in the Legend.

signal AbortSignal
optional

Allows for cancelable requests. If canceled, the promise will be rejected with an error named AbortError. See also AbortController.

Returns
Type Description
Promise<ClusterRendererResult> Resolves to an instance of ClusterRendererResult.
Example
const { renderer, fields } = await pieChartRendererCreator.createRendererForClustering({
  layer,
  shape: "donut"
});

const featureReduction = {
  type: "cluster",
  renderer,
  fields
};

layer.featureReduction = featureReduction;

Type Definitions

ClusterRendererResult

The result object of the createRendererForClustering() method. See the table below for details of each property.

Properties
renderer PieChartRenderer

The generated pie chart renderer to use for clustering. Set this on a renderer property of the FeatureReductionCluster instance to update its visualization.

The aggregate fields used by the renderer. Set this on a fields property of the FeatureReductionCluster instance alongside the renderer to update the clustering visualization to pie charts.

RendererResult

The result object of the createRenderer() method. See the table below for details of each property.

Properties
renderer PieChartRenderer

The generated pie chart renderer. Set this on a layer's renderer property to update its visualization.

optional

A size visual variable representing the sum of all attributes included in the pie chart. This is returned if the includeSizeVariable parameter is true.

pieChartScheme PieChartScheme

The color scheme used by the renderer.

basemapId String

The ID of the basemap used to determine the optimal color schemes for the charts.

basemapTheme String

Indicates whether the average color of the input view's basemap is light or dark.

statistics UniqueValuesResult

Contains the total counts of each attribute used in the renderer.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.