UniqueValuesSymbology (arcpy.mapping)

Summary

The UniqueValuesSymbology class provides access to different properties that allow you to change the appearance of a layer's unique value symbology.

Discussion

The UniqueValuesSymbology 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 modifying class 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 UniqueValuesSymbology 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 symbololgyType for the layer is unique values (if lyr.symbologyType == "UNIQUE_VALUES":), then create a variable reference to the UniqueValuesSymbology 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 unique values symbology to a graduated colors or graduated symbols 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 valueField is used to change the field the unique values are based on. After setting the new field it makes sense to immediately call the addAllValues method so that an updated list of classes is automatically generated. Similar to the user interface, calling addAllValues will automatically sort the classes in accending order. If you want to change the order, then use the classValues and classLabels properties.

The addAllValues method is also useful for situations where data is continuously being updated. Layers symbolized using unique values in a map document don't dynamically update when data is changed. The addAllValues method provides a mechanism to automate this process.

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, use the RefreshActiveView and RefreshTOC functions.

Properties

Property	Explanation	Data Type
classDescriptions (Read and Write)	A list of strings or numbers that represent the descriptions for each unique 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 classDescriptions list needs to have the same number of elements and arranged in the same order as the classValues property.	List
classLabels (Read and Write)	A list of strings or numbers that represent the labels for each unique value that appears in the map document's table of contents and/or legend items. The classDescriptions list needs to have the same number of elements and built in the same order as the classValues property. If this property is not set, its values will be the same as classValues.	List
classValues (Read and Write)	A list of strings or numbers that represent the class breaks. Changing this property will automatically adjust other unique value symbology properties based on the new information. It is good practice to always set this value before setting classDescriptions and classLabels.	List
showOtherValues (Read and Write)	Setting this value to True will display a symbol for all values that don't match the current list of classValues.	Boolean
valueField (Read and Write)	A string that represents a valid dataset field name used for the layer's unique value symbology. Changing this value will automatically adjust other symbology properties based on the new information.	String

Method Overview

Method	Explanation
addAllValues ()	Adds all unique values to the symbology.

Methods

addAllValues ()

The addAllValues method updates a layer's symbology so that all values are displayed in the unique value symbology. This method is useful when unique values are added to a layer after the symbology has been authored in ArcMap. Calling the addAllValues method will insert those new values into the list of existing values.

Code Sample

UniqueValuesSymbology example 1

The following script will change the valueField that the unique value symbology is based on. Next, the addAllValues is used to update the class list.

import arcpy
mxd = arcpy.mapping.MapDocument("current")
lyr = arcpy.mapping.ListLayers(mxd, "Population")[0]
if lyr.symbologyType == "UNIQUE_VALUES":
  lyr.symbology.valueField = "SUB_REGION"
  lyr.symbology.addAllValues()
arcpy.RefreshActiveView()
arcpy.RefreshTOC()
del mxd

UniqueValuesSymbology example 2

The following script will update a layer's unique value symbology class list based on the results of an attribute query.

import arcpy
mxd = arcpy.mapping.MapDocument("current")
lyr = arcpy.mapping.ListLayers(mxd, "Population")[0]
arcpy.SelectLayerByAttribute_management(lyr, "NEW_SELECTION", "\"POP2000\" > 20000000")
stateList = []
rows = arcpy.da.SearchCursor(lyr, ["STATE_NAME"])
for row in rows:
  stateList.append(row[0])

if lyr.symbologyType == "UNIQUE_VALUES":
  lyr.symbology.classValues = stateList
  lyr.symbology.showOtherValues = False

arcpy.RefreshActiveView()
arcpy.RefreshTOC()
del mxd