Chart

Résumé

The Chart class defines an ArcGIS Pro chart. The class allows you to create different types of charts, including bar charts, line charts, scatter plots, scatter plot matrices, QQ plots, histograms, box plots, and data clocks. The class can also be used to define the chart title, axes, and other properties.

Learn more about charts in ArcGIS Pro

Discussion

Charts assist in presenting information about map features and the relationship between them in a visual manner. Charts may also be created for nonspatial tables and can show additional information about the features on the map or the same information in a different way. Charts are complementary to maps in that they visually convey information that would generally be summarized numerically or explored from tables. With a chart, you can quickly compare features to gain insight into the functional relationship between the features and thereby visualize the distribution, trends, and patterns in the data that would otherwise be difficult to see.

Charts can be created using a Chart object and added to a layer or table in an ArcGIS Pro project. To add a chart to a layer in a project, create a Chart object, configure its properties, and associate the Chart object with an arcpy.mp.Layer from an arcpy.mp.ArcGISProject. A chart made in this way can be opened from the Charts section under the layer in the Contents pane when that project is opened in ArcGIS Pro.

The Chart object has a dataSource property that you can use to create a chart for data sources including various feature class and table formats and web layers (feature services). A chart can be exported to an .svg file (.svg) for visualization. Chart objects support rich representation in Notebooks and can be visualized graphically.

An example of arcpy.Chart in a notebook

Syntaxe

 Chart (name)
ParamètreExplicationType de données
name

The name of the chart. A chart must have a unique name per layer. This name is only used for identification; it is not displayed.

String

Propriétés

PropriétéExplicationType de données
bar
(Lecture/écriture)

Sets additional properties that apply to bar charts.

bar propertyDescription

aggregation

The statistical calculation applied to values that occur at the same value along the x-axis. Supported statistics are COUNT, SUM, MEAN, and MEDIAN. No aggregation means that each value will be plotted on the chart regardless of overlap or recurring values.

multiSeriesDisplay

The display type for a bar chart with multiple series. Valid options are sideBySide, stacked, and stacked100.

rotated

Indicates whether bars are viewed vertically or horizontally. Bars display vertically by default. True rotates bars horizontally. False displays bars vertically.

splitCategory

A second categorical field that adds a separate series or bar for each unique value in the field.

Object
boxPlot
(Lecture/écriture)

Sets additional properties that apply to box plots.

boxPlot propertyDescription

rotated

Indicates whether boxes are viewed vertically or horizontally. Boxes are displayed vertically by default. True rotates boxes horizontally. False displays boxes vertically.

showOutliers

Indicates whether outliers are shown as points extending beyond the whiskers. True displays outliers as points. False includes outliers in whiskers.

splitCategory

A second categorical field that adds a separate series or box for each unique value in the field.

splitCategoryAsMeanLine

Multiple-series box plots created with a split field can be displayed as mean lines or as side-by-side boxes. True displays split multiple series as mean lines. False displays split multiple series as side-by-side boxes.

standardizeValues

Box plots created from multiple fields are standardized by default. True displays standardized values. False displays nonstandardized values.

Object
calendarHeatChart
(Lecture/écriture)

Sets additional properties that apply to calendar heat charts.

calendarHeatChart propertyDescription

aggregation

The statistical calculation applied to values aggregated into each cell. Supported statistics are COUNT, SUM, MEAN, and MEDIAN.

classCount

The number of classes used in the classification method.

classificationMethod

The classification method used to visualize cell color. Supported options are equalIntervals, geometricalIntervals, naturalBreaks, and quantiles.

nullPolicy

How summarized cells returning a null value are displayed. Supported options are null and zero.

calendarType

The description for the time-unit pair supported in the data clock chart. Supported options are YEAR_MONTHSDAYS and WEEK_DAYSHOURS.

Object
dataClock
(Lecture/écriture)

Sets additional properties that apply to data clocks.

dataClock propertyDescription

aggregation

The statistical calculation applied to values aggregated into each temporal. Supported statistics are COUNT, SUM, MEAN, and MEDIAN.

classCount

The number of classes used in the classification method.

classificationMethod

The classification method used to visualize bin color. Supported options are equalIntervals, geometricalIntervals, naturalBreaks, and quantiles.

nullPolicy

How summarized bins returning a null value are displayed. Supported options are null and zero.

timeUnitsRingWedge

The description for the time-unit pair supported in the data clock chart. The following options are supported:

  • YEARS_MONTHS
  • YEARS_WEEKS
  • YEARS_DAYS
  • WEEKS_DAYS
  • DAYS_HOURS
Object
dataSource
(Lecture/écriture)

Sets the data source of the chart. When a chart is exported using the exportToSVG method or displayed in an ArcGIS Notebook, the data source is read and rendered on the chart. Valid data sources include paths to datasets, including local datasets, UNC paths, and service URLs, and arcpy.mp Layer objects.

String
description
(Lecture/écriture)

Sets the description of the chart. The description text appears at the bottom of the chart view.

String
histogram
(Lecture/écriture)

Sets additional properties that apply to histograms.

histogram propertyDescription

binCount

The number of bins to display in the histogram.

dataTransformationType

The data transformation type. Supported transformations are none, logarithmic, and squareRoot.

showComparisonDistribution

Indicates whether the normal distribution comparison line is visible in the histogram. True displays the line. False hides the line.

showMean

Indicates whether the mean statistical line is visible in the histogram. True displays the line. False hides the line.

showMedian

Indicates whether the median statistical line is visible in the histogram. True displays the line. False hides the line.

showStandardDeviation

Indicates whether the standard deviation statistical line is visible in the histogram. True displays the line. False hides the line.

Object
legend
(Lecture/écriture)

Sets properties of the chart legend.

legend propertyDescription

visible

Indicates whether the legend is visible in the chart view. True displays the legend. False hides the legend.

Object
line
(Lecture/écriture)

Sets additional properties that apply to line charts.

line propertyDescription

aggregation

The statistical calculation applied to values aggregated into each temporal bin. Supported statistics are COUNT, SUM, MEAN, and MEDIAN. No aggregation means that each value will be plotted on the chart regardless of overlap or recurring values.

nullPolicy

How summarized bins returning a null value are displayed. Supported options are null, zero, and interpolate.

rotated

Indicates whether lines are viewed horizontally or vertically. Lines display horizontally by default. True rotates lines vertically. False displays lines horizontally.

splitCategory

A second categorical field that adds a separate series or line for each unique value in the field.

timeAggregationType

The time interval alignment type. Valid options include equalIntervalsFromStartTime and equalIntervalsFromEndTime.

timeIntervalSize

The span of time that will be binned or aggregated together. Must be used in conjunction with timeIntervalUnit.

timeIntervalUnits

The time unit that corresponds to the timeIntervalSize. Valid options include SECONDS, MINUTES, HOURS, DAYS, WEEKS, MONTHS, and YEARS.

trimInCompleteTimeInterval

Determines whether incomplete time intervals at the start or end of the data span (depending on the timeAggregationType) will be removed from the chart. Incomplete intervals on a chart can cause misleading results in which the period in question is under or over reported due to a different amount of time in the interval. True indicates to trim these incomplete intervals. False does not trim incomplete intervals.

Object
qqPlot
(Lecture/écriture)

Sets additional properties that apply to QQ plots.

qqPlot propertyDescription

dataTransformationType

Applies a transformation to the data. Valid transformations include none, logarithmic, and squareRoot.

showReferenceLine

Indicates whether the reference line is visible in the QQ plot. True displays the line. False hides the line.

Object
scatter
(Lecture/écriture)

Sets additional properties that apply to scatter plots.

scatter propertyDescription

bubbleMinSize

The minimum size for points in a bubble plot.

bubbleMaxSize

The maximum size for points in a bubble plot.

showTrendLine

Indicates whether the trend line is visible in the scatter plot. True displays the line. False hides the line.

Object
scatterMatrix
(Lecture/écriture)

Sets additional properties that apply to scatter plot matrices.

scatterMatrix propertyDescription

fields

A list of field names to display in the matrix. A minimum of three fields is required.

showAsRSquared

Indicates whether mini-plots are viewed as R2 values. True displays mini-plots as R2 values. False displays mini-plots as scatter plots.

showHistograms

Indicates whether histograms are displayed in the matrix. True displays histograms. False hides histograms.

showTrendLine

Indicates whether trend lines are visible in the scatter plots. True displays the lines. False hides the lines.

Object
title
(Lecture/écriture)

Sets the title of the chart. The title text appears at the top of the chart view and is used as the label in the Contents pane on the List By Drawing Order tab Répertorier par ordre d’affichage.

String
type
(Lecture/écriture)

Sets the type of chart to create. Valid options include the following:

  • bar
  • line
  • scatter
  • scatterMatrix
  • qqPlot
  • histogram
  • boxPlot
  • dataClock
  • calendarHeatChart

String
xAxis
(Lecture/écriture)

Sets properties of the x-axis.

xAxis propertyDescription

field

The name of the field to display on the x-axis.

For data clocks and calendar heat charts, this is where the date field is specified.

logarithmic

Indicates whether the axis is logarithmic. True displays logarithmic axis. False displays linear axis.

This property only applies to scatter plots and line charts.

maximum

The minimum axis bound.

minimum

The maximum axis bound.

sort

The sorting method applied to this axis. ASC for ascending sorting and DESC for descending sorting.

This property applies only to bar charts.

title

The label of the axis that displays on the chart.

Object
yAxis
(Lecture/écriture)

Sets properties of the y-axis.

yAxis propertyDescription

field

The name of the field to display on the y-axis.

For bar or line charts, the property can be specified as a list of field names.

For data clocks and calendar heat charts, this is where the number field is specified.

logarithmic

Indicates whether the axis is logarithmic. True displays logarithmic axis. False displays linear axis.

This property applies only to scatter plots and line charts.

maximum

The minimum axis bound.

minimum

The maximum axis bound.

sort

The sorting method applied to this axis. ASC for ascending sorting and DESC for descending sorting.

This property applies only to bar charts.

title

The label of the axis that displays on the chart.

Object

Vue d’ensemble des méthodes

MéthodeExplication
addToLayer (layer)

Adds the chart class to a layer.

exportToSVG (path, width, height)

Exports the chart to SVG format.

updateChart ()

Updates chart properties to sync changes between the class and the chart previously added to a layer.

Méthodes

addToLayer (layer)
ParamètreExplicationType de données
layer

The chart will be added to this target Layer object.

Layer
Valeur renvoyée
Type de donnéesExplication
Object

The Chart class will be unchanged, but the class' properties will be set into the layer definition and a new chart will be created.

After defining chart properties in the Chart class, the final step typically is to add the chart to a layer. Use the addToLayer method to accomplish this.

Set chart properties and add the chart to an existing layer.

import arcpy

aprx = arcpy.mp.ArcGISProject("current")
map = aprx.listMaps()[0]
censusLayer = map.listLayers('Census Block Groups')[0]

c = arcpy.Chart('MyChart')
c.type = 'bar'
c.title = 'Population by State'
c.xAxis.field = 'StateName'
c.yAxis.field = 'Population'
c.bar.aggregation = 'SUM'
c.xAxis.title = 'State'
c.yAxis.title = 'Total Population'
c.addToLayer(censusLayer)
exportToSVG (path, width, height)
ParamètreExplicationType de données
path

The path where the chart will be exported in SVG format.

String
width

The width of the output graphic.

Integer
height

The height of the output graphic.

Integer

In some cases, you may wish to save the chart as a graphic that can be shared and viewed outside of ArcGIS Pro. Exporting to the SVG graphic format is beneficial, as the chart elements and text are stored as vector elements that can be independently modified in a vector graphics software. An SVG graphic can also be resized to any scale without pixelation or loss in quality.

Create a chart based on a project layer and export to a local disk.

import arcpy

aprx = arcpy.mp.ArcGISProject('current')
censusLayer = aprx.listMaps()[0].listLayers('Census Block Groups')[0]

c = arcpy.Chart('Population By State')
c.type = 'bar'
c.title = 'Population by State'
c.xAxis.field = 'StateName'
c.xAxis.title = 'State'
c.yAxis.field = 'Population'
c.yAxis.title = 'Total Population'
c.bar.aggregation = 'SUM'

# Set data source to a layer within current project
c.dataSource = censusLayer

# Save the chart to file with dimensions width=500, height=500
c.exportToSVG('populationByState.svg', 500, 500)

Create a chart based on a feature service layer and export to a local disk.

import arcpy

featureServiceURL = r'https://services1.arcgis.com/hLJbHVT9ZrDIzK0I/arcgis/rest/services/CrimesChiTheft/FeatureServer/0'

c = arcpy.Chart('Chicago Thefts')
c.type = 'bar'
c.title = 'Chicago Thefts by Police Beat'
c.xAxis.field = 'BEAT'
c.bar.aggregation = 'COUNT'

# Set data source to a feature service URL
c.dataSource = featureServiceURL

# Save the chart to file with dimensions width=800, height=600
c.exportToSVG('theftsPerBeat.svg', 800, 600)
updateChart ()
Valeur renvoyée
Type de donnéesExplication
Object

The Chart class is not modified in any way. Rather the settings from the class are synced to the chart previously added to a layer.

After defining chart properties in the Chart class, the final step is typically to add the chart to a layer. Use the addToLayer method to accomplish this. However, you may wish to further modify the chart properties. Instead of starting from scratch with a new chart, you can modify the properties of the original Chart class, then use updateChart to sync any changes into the chart added to the layer. This will allow the changes you make to be presented in the Chart properties pane and chart view.

Use updateChart to sync chart property changes into a layer.

chart.addToLayer(myLayer)

# Further modification is necessary
chart.description = "Data from the U.S. Census Bureau"
chart.updateChart()

Exemple de code

Chart example

Add a Chart object to an arcpy.mp Layer object to add the chart to the layer.

import arcpy

aprx = arcpy.mp.ArcGISProject("current")
map = aprx.listMaps()[0]
censusLayer = map.listLayers('Census Block Groups')[0]
c = arcpy.Chart('MyChart')

c.type = 'scatter'
c.title = 'Relationship between Percent Vacant (Housing) and Population Density'
c.description = 'This chart examines the relationship between housing vacancy and population density.'
c.xAxis.field = 'Per_Vacant'
c.yAxis.field = 'Pop_Density'
c.xAxis.title = 'Vacant Housing %'
c.yAxis.title = 'Population Density (per Sq. Mile)'
c.addToLayer(censusLayer)