RasterClassifiedSymbology (arcpy.mapping)
Summary
The RasterClassifiedSymbology class provides access to different properties that allow you to change the appearance of a layer's raster classified symbology.
Discussion
The RasterClassifiedSymbology 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 RasterClassifiedSymbology 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 raster classified (if lyr.symbologyType == "RASTER_CLASSIFIED":), then create a variable reference to the RasterClassifiedSymbology 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 raster classified symbology to a raster 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 that 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 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 use interface. For this reason, the classBreakValues list will always have one more value than the classBreakLabels and classBreakDescriptions lists.
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 appears in the map document's table of contents and/or 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 such as 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 |
| excludedValues (Read and Write) | A string that represents values or ranges to exclude from the classification separated by semicolons. For example 1; 3; 5-7; and 8.5-12.1. The values are removed from the classification, and therefore, will not be displayed. | String |
| 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 such as 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
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). This method will automatically update the symbology properties based on the layer's actual data source information and statistics and not the information that is persisted in a layer file. The method needs to be used cautiously because it has the potential to overwrite other symbology properties. The reclassify method will regenerate classBreakValues, classBreakLabels, and classBreakDescriptions. It will not affect numClasses or normalization. The reclassify method has no affect on a manual classification.
Code Sample
The following script modifies the symbology for a layer in the current map document. It first verifies that the layer has raster classified symbology. Finally, it modifies a number of the properties on the RasterClassifiedSymbology class and updates the display.
Since this sample uses the CURRENT keyword to access the map document, it must be executed from within ArcMap. This is because the MapDocument object references the map document that is currently loaded into the ArcMap application. For more information regarding accessing map documents, see the MapDocument class help topic.
import arcpy
mxd = arcpy.mapping.MapDocument("CURRENT")
df = arcpy.mapping.ListDataFrames(mxd, "Lakes")[0]
lyr = arcpy.mapping.ListLayers(mxd, "lakene.tif", df)[0]
if lyr.symbologyType == "RASTER_CLASSIFIED":
lyr.symbology.classBreakValues = [1, 60, 118, 165, 255]
lyr.symbology.classBreakLabels = ["1 to 60", "61 to 118",
"119 to 165", "166 to 255"]
lyr.symbology.classBreakDescriptions = ["Class A", "Class B",
"Class C", "Class D"]
lyr.symbology.excludedValues = '0'
arcpy.RefreshActiveView()
arcpy.RefreshTOC()
del mxd, df, lyr
The following script modifies the symbology for a layer in a map document on disk. It first updates the layer's symbology using a layer file on disk with the UpdateLayer function. The layer file contains a custom color ramp that is applied to the layer. Next, it verifies that the layer has raster classified symbology. The script then calls the reclassify method. This method will update the symbology properties based on the layer's actual data source information and statistics and not the information that is persisted in a layer file. Finally, the result is exported to a PDF file.
import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\StudyArea.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "Lakes")[0]
lyr = arcpy.mapping.ListLayers(mxd, "lakene.tif", df)[0]
lyrFile = arcpy.mapping.Layer(r"C:\Project\Data\Lakes\lake_blue.lyr")
arcpy.mapping.UpdateLayer(df, lyr, lyrFile, True)
if lyr.symbologyType == "RASTER_CLASSIFIED":
lyr.symbology.reclassify()
arcpy.mapping.ExportToPDF(mxd, r"C:\Project\Output\Lakes.pdf")
del mxd, df, lyr, lyrFile