Chart

Summary

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 can 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 for visualization. Chart objects support rich representation in Notebooks and can be visualized graphically.

Syntax

 Chart (name)

Parameter	Explanation	Data Type
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

Properties

Property	Explanation	Data Type
bar (Read and Write)	Sets additional properties that apply to bar charts. aggregation—The statistical calculation applied to values that occur at the same value along the x-axis. Supported statistics are COUNT, SUM, MEAN, MEDIAN, MIN, and MAX. No aggregation means that each value will be plotted on the chart regardless of overlap or recurring values. movingAveragePeriod—The size of the moving average period. 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. showMovingAverage—Indicates whether the moving average is displayed. splitCategory—A second categorical field that adds a separate series or bar for each unique value in the field.	Object
boxPlot (Read and Write)	Sets additional properties that apply to box plots. 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 (Read and Write)	Sets additional properties that apply to calendar heat charts. aggregation—The statistical calculation applied to values aggregated into each cell. Supported statistics are COUNT, SUM, MEAN, MEDIAN, MIN, and MAX. 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 (Read and Write)	Sets additional properties that apply to data clocks. aggregation—The statistical calculation applied to values aggregated into each temporal. Supported statistics are COUNT, SUM, MEAN, MEDIAN, MIN, and MAX. 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 (Read and Write)	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 (Read and Write)	Sets the description of the chart. The description text appears at the bottom of the chart view.	String
histogram (Read and Write)	Sets additional properties that apply to histograms. 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 (Read and Write)	Sets properties of the chart legend. visible—Indicates whether the legend is visible in the chart view. True displays the legend. False hides the legend. title—The title to display for the legend.	Object
line (Read and Write)	Sets additional properties that apply to line charts. aggregation—The statistical calculation applied to values aggregated into each temporal bin. Supported statistics are COUNT, SUM, MEAN, MEDIAN, MIN, and MAX. 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 overreported due to a different amount of time in the interval. True indicates to trim these incomplete intervals. False does not trim incomplete intervals.	Object
matrixHeatChart (Read and Write)	Sets additional properties that apply to matrix heat charts. aggregation—The statistical calculation applied to values aggregated into each cell. Supported statistics are COUNT, SUM, MEAN, MEDIAN, MIN, and MAX. 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.	Object
qqPlot (Read and Write)	Sets additional properties that apply to QQ plots. 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 (Read and Write)	Sets additional properties that apply to scatter plots. 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 (Read and Write)	Sets additional properties that apply to scatter plot matrices. fields—A list of field names to display in the matrix. A minimum of three fields is required. showAsRSquared—Indicates whether miniplots are viewed as R2 values. True displays miniplots as R2 values. False displays miniplots 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 (Read and Write)	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 .	String
type (Read and Write)	Sets the type of chart to create. Valid options include the following: bar line scatter scatterMatrix qqPlot histogram boxPlot dataClock calendarHeatChart matrixHeatChart	String
xAxis (Read and Write)	Sets properties of the x-axis. field—The name of the field to display on the x-axis. logarithmic—Indicates whether the axis is logarithmic. True displays the logarithmic axis. False displays the linear axis. This property only applies to scatter plots and line charts. minimum—The minimum axis bound. maximum—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 (Read and Write)	Sets properties of the y-axis. 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. For scatter plots, the field optionally accepts two-item list, where the first item is the y-axis field and the second item is the proportional symbol field. For matrix heat charts, the field optionally accepts a two-item list, where the first item is the y-axis field and the second item is the numeric field that will be aggregated. 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 is for ascending sorting and DESC is for descending sorting. This property applies only to bar charts. title—The label of the axis that displays on the chart.	Object

Method Overview

Method	Explanation
addToLayer (layer_or_layerfile)	Adds the Chart class to a layer or stand-alone table.
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.

Methods

addToLayer (layer_or_layerfile)

Parameter	Explanation	Data Type
layer_or_layerfile	The chart will be added to the target object. The layer_or_layerfile argument can be a Layer or a Table object.	Object

Return Value

Data Type	Explanation
Object	The Chart class will be unchanged, but the class's properties will be set into the layer or table definition and a new chart will be created.

After defining chart properties in the Chart class, typically the final step is to add the chart to a layer or table. Use the addToLayer method to do 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]

chart = arcpy.Chart('MyChart')
chart.type = 'bar'
chart.title = 'Population by State'
chart.xAxis.field = 'StateName'
chart.yAxis.field = 'Population'
chart.bar.aggregation = 'SUM'
chart.xAxis.title = 'State'
chart.yAxis.title = 'Total Population'
chart.addToLayer(censusLayer)

exportToSVG (path, width, height)

Parameter	Explanation	Data Type
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 ()

Return Value

Data Type	Explanation
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()

Code sample

Chart example 1

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]
chart = arcpy.Chart('MyChart')

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

Chart example 2

Create and export a chart based on values in a list. The example demonstrates how the list can be written to disk as a CSV file, and this file can then be used to create the chart by setting the dataSource property.

import arcpy
import csv

temp_csv_file = r'c:\temp\data.csv'
out_svg_file = r'c:\temp\chart.svg'
# Data for automobile miles per gallon (MPG) and horsepower 
columns = ['mpg', 'horsepower'] 
data = [
    [18, 130], 
    [15, 165], 
    [26, 113],
    [18, 150],
    [28, 90], 
    [32, 61],
    [16, 150],
    [17, 140]
]

# Write this list to a CSV file
with open(temp_csv_file, 'w', newline='') as csvfile:
    writer = csv.writer(csvfile, delimiter=',')

    # Write column headers
    writer.writerow(columns)
    
    # Write data rows
    writer.writerows(data)

chart = arcpy.Chart('MyChart')
chart.type = 'scatter'
chart.title = 'Relationship between MPG and Horsepower'
chart.xAxis.field = 'mpg'
chart.yAxis.field = 'horsepower'
chart.dataSource = temp_csv_file
chart.exportToSVG(out_svg_file, width=750, height=400)