ArcGIS Help 10.2 - GraduatedSymbolsSymbology (arcpy.mapping)

Summary

The GraduatedSymbolsSymbology class provides access to different properties that allow you to change the appearance of a layer's graduated symbols symbology.

Discussion

The GraduatedSymbolsSymbology class provides access to a limited number of properties and methods that allow you to automate layer symbology in a map document (.mxd) or layer file (.lyr). Basic operations such as changing the number of classes, modifying class break values and labels, or changing the field that the symbology is based on are some of the properties that can be modified. For access to the complete set of layer symbology properties and settings, for example, changing individual symbols for individual classes, it is necessary to author these changes in the ArcMap user interface and then save those changes to a layer file. These custom settings can then be applied to existing layers using the UpdateLayer function.

A layer can use any number of symbologies, but not all of them can be modified. Not all layers will use the GraduatedSymbolsSymbology class, so it is important to first test if the layer is using this symbology class before attempting to make changes to its properties. The symbologyType property on the Layer class was designed for this purpose. First test if the symbologyType for the layer is graduated symbols (if lyr.symbologyType == "GRADUATED_SYMBOLS":), then create a variable reference to the GraduatedSymbolsSymbology class for that layer (lyrSymbolClass = lyr.symbology).

The symbologyType on the Layer object is a read-only property. In other words, you can't change a graduated symbols symbology to a graduated colors or a unique value symbology. You can only change the properties for a specific symbology class on a layer. The only way to change the symbology type is by publishing the desired result to a layer file and using the UpdateLayer function.

The classification method cannot be changed. In cases where you want to use different classification methods, you would need to preauthor layer files and use those to update a layer, then modify the properties than can be changed. The only exception to this rule is when you set classBreakValues. Similar to the ArcMap user interface, explicitly setting classBreakValues will automatically set the classification method to manual. Also similar to the ArcMap user interface, once the classification method is set to manual, you can't change the numClasses parameter.

Unlike the ArcMap user interface, you can set a minimum value when setting the classBreakValues parameter. The first value in the classBreakValues list is the minimum value. All other values are the class break values as they appear in the ArcMap user interface. For this reason, the classBreakValues list will always have one more value than the classBreakLabels and classBreakDescriptions lists.

The classBreakValues, classBreakLabels, and classBreakDescriptions lists must always be sorted from lowest value to highest value. This is also the case for layers that were authored with reversed sorting.

Setting one parameter will often modify other parameters automatically. For example, if you set numClasses, normalization, or the valueField parameters, the classBreakValues, classBreakLabels, and classBreakDescriptions properties will automatically be adjusted based on the current classification method. For this reason, the order in which properties are modified is important.

The reclassify method updates a layer's symbology properties based on the underlying source data. It is useful when a layer's symbology is updated using the UpdateLayer function with symbology stored in another layer or layer file (.lyr). For example, let's say you want to update the color properties of the symbology of a layer in a map document with the symbology stored in a layer file. However, the layer in the map document and the layer file have different data sources. The minimum and maximum values and class breaks in the layer file may be different than the layer in the map document. Updating the symbology of the layer in the map document with the symbology stored in the layer file may produce unintended results (for example, the class break values will match the layer file's data source statistics as opposed to the map document layer's data source statistics. However, if you follow UpdateLayer with the reclassify() method, the end result is like using the color properties from the symbology in the layer file, but other characteristics are based on the map document layer's underlying source data.

If you are making these symbology modifications via the Python window and you are referencing a map document using CURRENT, you may not immediately see the changes in the ArcMap application. To refresh the map document, try using the RefreshActiveView and RefreshTOC functions.

Properties

Property	Explanation	Data Type
classBreakDescriptions (Read and Write)	A sorted list of strings that represent the descriptions for each class break value that can optionally appear in a map document's legend. These values are only accessible in the ArcMap user interface by right-clicking a symbol displayed within the Symbology tab in the Layer Properties dialog box and selecting Edit Description. The number of descriptions in the sorted list must always be one less than the number of classBreakValues. This is because the classBreakValues list also includes a minimum value which you don't see in the user interface. These values are affected by changes to nearly all other class properties, so it is best practice to set these values last.	List
classBreakLabels (Read and Write)	A sorted list of strings that represent the labels for each class break that appear in the map document's table of contents and legend items. The number of labels in the sorted list must always be one less than the number of classBreakValues. This is because the classBreakValues list also includes a minimum value which you don't see in the user interface. These values are affected by changes to nearly all other class properties so it is best practice to set these values last.	List
classBreakValues (Read and Write)	A sorted list of doubles that includes the minimum and maximum values that represent the class breaks. When setting classBreakValues, it will automatically set the numClasses property and will also set the classification method to manual as well as update other properties like classBreakLabels. Unlike the ArcMap user interface, you have the ability to set a minimum value. The first value in the sorted list represents the minimum value and the remaining values are the class breaks that appear in the user interface; therefore, there will always be one more item in the classBreakValues list than in the classBreakLabels and classBreakDescriptions lists. Changing this value will automatically adjust other symbology properties based on the new information.	List
normalization (Read and Write)	A string that represents a valid dataset field name used for normalization. Changing this value will automatically adjust other symbology properties based on the new information. The normalization field can be removed by setting the value to None (for example, lyr.symbology.normalization = None).	String
numClasses (Read and Write)	A long integer that represents the number of classes to be used with the current classification method. Changing this value will overwrite other symbol properties like classBreakValues and classBreakLabels. This value cannot be set if the classification method is manual; therefore, numClasses should not be called after the classBreakValues property because it will automatically set the classification method to manual. Changing this value will automatically adjust other symbology properties based on the new information.	Long
valueField (Read and Write)	A string that represents a valid dataset field name used for the layer's classification symbology. Changing this value will automatically adjust other symbology properties based on the new information.	String

Method Overview

Method	Explanation
reclassify ()	Resets the layer's symbology to the layer's data source information and statistics.

Methods

reclassify ()

Code Sample

GraduatedSymbolsSymbology example 1

The following script modifies the symbology for all layers in a map document. It iterates through each layer, changes the value field, changes the number of classes, and saves the map document.

import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
for lyr in arcpy.mapping.ListLayers(mxd):
  if lyr.symbologyType == "GRADUATED_SYMBOLS":
    lyr.symbology.valueField = "POP2007"
    lyr.symbology.numClasses = 5
del mxd

GraduatedSymbolsSymbology example 2

The following script modifies the symbology for a layer in a map document. It first updates the layer's symbology using a layer file on disk with the UpdateLayer function. Next, it verifies that the layer has graduated symbols symbology. Finally, the script modifies a number of the properties on the GraduatedSymbolsSymbology class and exports the result to PDF.

import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "Census")[0]
lyr = arcpy.mapping.ListLayers(mxd, "StatePopulation", df)[0]
lyrFile = arcpy.mapping.Layer(r"C:\Project\LYRs\Population.lyr")
arcpy.mapping.UpdateLayer(df, lyr, lyrFile, True)
if lyr.symbologyType == "GRADUATED_SYMBOLS":
  lyr.symbology.valueField = "POP2000"
  lyr.symbology.classBreakValues = [250000, 999999, 4999999, 9999999, 35000000]
  lyr.symbology.classBreakLabels = ["250,000 to 999,999", "1,000,000 to 4,999,999", 
                                    "5,000,000 to 9,999,999", "10,000,000 to 35,000,000"]
arcpy.mapping.ExportToPDF(mxd, r"C:\Project\Output\StatePopulation.pdf")
del mxd, lyrFile

3/3/2014