UniqueValueRenderer

Summary

The UniqueValueRenderer class represents a unique value renderer.

Discussion

If you change your current renderer to the UniqueValueRenderer, you first have to set the appropriate fields property value. The property is plural because you can build a set of unique values based on multiple fields. Therefore, the fields property takes a list, even if there is only one field being used. Once you apply your fields, the renderer will automatically generate all the unique values. If, for whatever reason, new values are added to the layer, you will need to reset the renderer so that all the values are added again. You can do this by changing the fields property, or you can use the addValues method.

You need to understand how unique values are managed in the renderer so you can navigate through the class structure to change individual items and their values. The groups property returns a list of ItemGroup objects. Each ItemGroup represents a category of items that each have their own heading. By default, there is one ItemGroup. The items property returns a list of Item objects. Once you have an item, you can change properties such as label and description. You can also modify the symbol for each item. The reason the values property is plural and returns a list is because you can also group items in an ItemGroup. Therefore, each item could have multiple values.

The following is one way to outline the class structure:

  • groups—Returns a list of ItemGroup objects
    • heading
    • items—Returns a list of Item objects
      • description
      • label
      • symbol
      • values

You can also add and remove values from the renderer. Each unique value is actually an item in the object model and each item is associated within an ItemGroup. To addValues or removeValues, you need to work with a Python dictionary. The dictionary key is the name of the group heading, and its value is a list of values based on the fields property. There is also a listMissingValues method that allows you to determine what values are currently missing from the renderer. Values would only be missing if you intentionally called removeValues, because—by default—the renderer automatically creates all unique values when the fields property is set.

If your objective is to create new group headings to organize your unique value items, you must first call removeValues to remove the items, and then use addValues to create a new group with a new heading label.

Properties

PropertyExplanationData Type
colorRamp
(Read and Write)

Provides access to the ColorRamp object.

ColorRamp
defaultSymbol
(Read and Write)

A symbol that can be used as a template to update all the symbols for each class.

Symbol
fields
(Read and Write)

A list of one or more fields that is used by the renderer to determine the unique set of values.

List
groups
(Read and Write)

A list of ItemGroup objects containing unique values. If values have not been added to the renderer, the item group count may be zero.

List
type
(Read Only)

Returns a string that represents the renderer type.

String
useDefaultSymbol
(Read and Write)

A Boolean that controls the display of un-added values. If True, the features are displayed.

Boolean

Method Overview

MethodExplanation
addValues (values_or_items)

addValues provides a mechanism to add missing values to a unique value renderer.

listMissingValues ()

listMissingValues provides a mechanism to identify values missing from a unique value renderer.

removeValues (values_or_items)

removeValues provides a mechanism to remove values in a unique value renderer.

Methods

addValues (values_or_items)
ParameterExplanationData Type
values_or_items

A dictionary based on a key that matches the group heading name and a value that represents a list of values as strings or a list of items to be added to the group.

For example: addValues({"group name" : ["str1", "str2", "str3"]}) or addValues({"group name" : missingVals[0].items})

(The default value is None)

Dictionary

Before executing addValues, it makes sense to first check to see if the renderer is missing any values using the listMissingValues method. If the values you add are not valid, they will simply be ignored. It is important to reset the layer's symbology with the updated information before continuing to process other items in the renderer.

listMissingValues ()
Return Value
Data TypeExplanation
ItemGroup

The ItemGroup provides access to group level information for a UniqueValueRenderer.

Each ItemGroup has a heading and an associate set of item objects that represent the unique values. If you want to add missing items from multiple item groups back into the renderer, you'll need to call addValues multiple times, once for each heading group you want to add values into.

removeValues (values_or_items)
ParameterExplanationData Type
values_or_items

A dictionary based on a key that matches the group heading name and a value that represents a list of values as strings or a list of items to be added to the group.

For example: removeValues({"group name" : ["str1", "str2", "str3"]})

(The default value is None)

Dictionary

After executing removeValues, you can confirm whether the values were removed by using the listMissingValues method. It is important to reset the layer's symbology with the updated information before continuing to process other items in the renderer.

Code sample

UniqueValueRenderer example 1

The following script first changes the renderer to a UniqueValueRenderer. Next, it sets the fields property to use a single field called Percent. It next iterates through each Item in each ItemGroup and sets the RGB color to red and the alpha, or opacity, value to match the Percent value of each feature. Finally, it labels each value, sets the symbology back to the layer, and saves the output.

import arcpy, os, sys
relpath = os.path.dirname(sys.argv[0])

p = arcpy.mp.ArcGISProject(relpath + r'\\UniqueValue.aprx')
m = p.listMaps('Map')[0]
l = m.listLayers('PercentCover*')[0]
sym = l.symbology

sym.updateRenderer('UniqueValueRenderer')
sym.renderer.fields = ['Percent']
for grp in sym.renderer.groups:
    for itm in grp.items:
        transVal = itm.values[0][0] #Grab the first "percent" value in the list of potential values
        itm.symbol.color = {'RGB': [255, 0, 0, int(transVal)]}
        itm.label = str(transVal) + '%'

l.symbology = sym
p.saveACopy(relpath + r'\\SavedOutput.aprx')
UniqueValueRenderer example 2

The following script first shows you two ways to remove and add values into a new group heading. First, it removes four state names and then adds those same items into a new group heading called Pacific Coast. Second, it uses removeValues to remove the six New England states and then uses addValues based on what thelistMissingValues method returns. The [0] on the list is the first and only group of items that is returned.

import arcpy
import os
import sys
relpath = os.path.dirname(sys.argv[0])

p = arcpy.mp.ArcGISProject(relpath + r'\\UniqueValue.aprx')
m = p.listMaps('Map')[0]
l = m.listLayers('State_Polygons_Default')[0]
sym = l.symbology

sym.renderer.removeValues({"STATE_NAME" : ["Alaska", "California", "Oregon", "Washington"]})
l.symbology = sym
sym.renderer.addValues({"Pacific Coast" : ["Alaska", "California", "Oregon", "Washington"]})
l.symbology = sym

sym.renderer.removeValues({"STATE_NAME" : ["Connecticut", "Maine", "Massachusetts", "New Hampshire", "Rhode Island", "Vermont"]})
l.symbology = sym
missList = sym.renderer.listMissingValues()
sym.renderer.addValues({"New England" : missList[0].items})
l.symbology = sym

p.saveACopy(relpath + r'\\SavedOutput.aprx')