Class: QgsGraduatedSymbolRenderer

A vector feature renderer which uses numeric attributes to classify features into different ranges.

Class Hierarchy

Base classes

QgsFeatureRenderer

Abstract base class for all 2D vector feature renderers.

Enums

GraduatedMethod

Methods for modifying symbols by range in a graduated symbol renderer.

Methods

addBreak	Add a breakpoint by splitting existing classes so that the specified value becomes a break between two classes.
addClass	Adds a class to the renderer, with the specified symbol.
addClassLowerUpper	Adds a class to the renderer, with the specified lower and upper bounds.
addClassRange	Adds a class to the renderer, with the specified range.
astride	Returns if we want to have a central class astride the pivot value
calculateLabelPrecision	Reset the label decimal places to a numberbased on the minimum class interval
classAttribute	Returns the attribute name (or expression) used for the classification.
classificationMethod	Returns the classification method
dataDefinedSizeLegend	Returns configuration of appearance of legend when using data-defined size for marker symbols.
deleteAllClasses
deleteClass
graduatedMethod	Returns the method used for graduation (either size or color).
labelFormat	Returns the label format used to generate default classification labels
legendKeyForValue	Returns the matching legend key for a value.
maxSymbolSize	Returns the max symbol size when graduated by size
minSymbolSize	Returns the min symbol size when graduated by size
mode
moveClass	Moves the category at index position from to index position to.
rangeForValue	Returns the renderer range matching the provided value, or None if no range matches the value.
ranges	Returns a list of all ranges used in the classification.
rangesHaveGaps	Tests whether classes assigned to the renderer have gaps between the ranges.
rangesOverlap	Tests whether classes assigned to the renderer have ranges which overlap.
setAstride	Set if we want a central class astride the pivot value
setClassAttribute	Sets the attribute name (or expression) used for the classification.
setClassificationMethod	Defines the classification method This will take ownership of the method
setDataDefinedSizeLegend	Configures appearance of legend when renderer is configured to use data-defined size for marker symbols.
setGraduatedMethod	Set the method used for graduation (either size or color).
setLabelFormat	Set the label format used to generate default classification labels
setMode
setSourceColorRamp	Sets the source color ramp.
setSourceSymbol	Sets the source symbol for the renderer, which is the base symbol used for the each classes' symbol before applying the classes' color.
setSymbolSizes	set varying symbol size for classes
setSymmetryPoint	Set the pivot point
setUseSymmetricMode	Set if we want to classify symmetric around a given value
sortByLabel
sortByValue
sourceColorRamp	Returns the source color ramp, from which each classes' color is derived.
sourceSymbol	Returns the renderer's source symbol, which is the base symbol used for the each classes' symbol before applying the classes' color.
symbolForValue	Gets the symbol which is used to represent value.
symmetryPoint	Returns the pivot value for symmetric classification
updateClasses	Recalculate classes for a layer
updateColorRamp	Update the color ramp used.
updateRangeLabel
updateRangeLabels	Updates the labels of the ranges
updateRangeLowerValue
updateRangeRenderState
updateRangeSymbol
updateRangeUpperValue
updateSymbols	Update all the symbols but leave breaks and colors.
useSymmetricMode	Returns if we want to classify symmetric around a given value

Static Methods

calcEqualIntervalBreaks	Compute the equal interval classification
convertFromRenderer	creates a QgsGraduatedSymbolRenderer from an existing renderer.
create	create renderer from XML element
createRenderer	Creates a new graduated renderer.
makeBreaksSymmetric	Remove the breaks that are above the existing opposite sign classes to keep colors symmetrically balanced around symmetryPoint Does not put a break on the symmetryPoint.

Attributes

Custom
EqualInterval
Jenks
Pretty
Quantile
StdDev

class qgis.core.QgsGraduatedSymbolRenderer

Bases: QgsFeatureRenderer

Custom = 5

EqualInterval = 0

class GraduatedMethod(*values)

Bases: IntEnum

Methods for modifying symbols by range in a graduated symbol renderer.

Note

Prior to QGIS 3.26 this was available as QgsGraduatedSymbolRenderer.GraduatedMethod

Added in version 3.26.

• Color: Alter color of symbols

  Available as QgsGraduatedSymbolRenderer.GraduatedColor in older QGIS releases.

• Size: Alter size of symbols

  Available as QgsGraduatedSymbolRenderer.GraduatedSize in older QGIS releases.

Jenks = 2

class Mode

Bases: int

Pretty = 4

Quantile = 1

StdDev = 3

addBreak(self, breakValue: float, updateSymbols: bool = True)

Add a breakpoint by splitting existing classes so that the specified value becomes a break between two classes.

Parameters:

• breakValue (float) – position to insert break

• updateSymbols (bool = True) – set to True to reapply ramp colors to the new symbol ranges

addClass(self, symbol: QgsSymbol | None)

Adds a class to the renderer, with the specified symbol.

Parameters:

symbol (Optional[QgsSymbol])

addClassLowerUpper(self, lower: float, upper: float)

Adds a class to the renderer, with the specified lower and upper bounds.

Parameters:

• lower (float)

• upper (float)

addClassRange(self, range: QgsRendererRange)

Adds a class to the renderer, with the specified range.

Parameters:

range (QgsRendererRange)

astride(self) → bool

Returns if we want to have a central class astride the pivot value

Added in version 3.4.

Deprecated since version 3.10: Use classficationMethod() instead.

Return type:

bool

static calcEqualIntervalBreaks(minimum: float, maximum: float, classes: int, useSymmetricMode: bool, symmetryPoint: float, astride: bool) → List[float]

Compute the equal interval classification

Parameters:

• minimum (float) – The minimum value of the distribution

• maximum (float) – The maximum value of the distribution

• classes (int) – The number of classes desired

• useSymmetricMode (bool) – A bool indicating if we want to have classes and hence colors ramp symmetric around a value

• symmetryPoint (float) – The point around which we want a symmetry

• astride (bool) – A bool indicating if the symmetry is made astride the symmetryPoint or not ( [-1,1] vs. [-1,0][0,1] )

Deprecated since version 3.10: Use QgsClassificationEqualInterval class instead.

Return type:

List[float]

calculateLabelPrecision(self, updateRanges: bool = True)

Reset the label decimal places to a numberbased on the minimum class interval

Parameters:

updateRanges (bool = True) – if True then ranges currently using the default label will be updated

classAttribute(self) → str

Returns the attribute name (or expression) used for the classification.

See also

setClassAttribute()

Return type:

str

classificationMethod(self) → QgsClassificationMethod | None

Returns the classification method

Added in version 3.10.

Return type:

Optional[QgsClassificationMethod]

static convertFromRenderer(renderer: QgsFeatureRenderer | None) → QgsGraduatedSymbolRenderer | None

creates a QgsGraduatedSymbolRenderer from an existing renderer.

Return type:

Optional[QgsGraduatedSymbolRenderer]

Returns:

a new renderer if the conversion was possible, otherwise None.

Parameters:

renderer (Optional[QgsFeatureRenderer])

static create(element: QDomElement, context: QgsReadWriteContext) → QgsFeatureRenderer | None

create renderer from XML element

Parameters:

• element (QDomElement)

• context (QgsReadWriteContext)

Return type:

Optional[QgsFeatureRenderer]

static createRenderer(vlayer: QgsVectorLayer | None, attrName: str | None, classes: int, mode: QgsGraduatedSymbolRenderer.Mode, symbol: QgsSymbol | None, ramp: QgsColorRamp | None, legendFormat: QgsRendererRangeLabelFormat = QgsRendererRangeLabelFormat(), useSymmetricMode: bool = False, symmetryPoint: float = 0, listForCboPrettyBreaks: Iterable[str | None] = [], astride: bool = False) → QgsGraduatedSymbolRenderer | None

Creates a new graduated renderer.

Parameters:

• vlayer (Optional[QgsVectorLayer]) – vector layer

• attrName (Optional[str]) – attribute to classify

• classes (int) – number of classes

• mode (QgsGraduatedSymbolRenderer.Mode) – classification mode

• symbol (Optional[QgsSymbol]) – base symbol

• ramp (Optional[QgsColorRamp]) – color ramp for classes

• legendFormat (QgsRendererRangeLabelFormat = QgsRendererRangeLabelFormat())

• useSymmetricMode (bool = False) – A bool indicating if we want to have classes and hence colors ramp symmetric around a value

• symmetryPoint (float = 0) – The value around which the classes will be symmetric if useSymmetricMode is checked

• listForCboPrettyBreaks (Iterable[Optional[str]] = []) – The list of potential pivot values for symmetric mode with prettybreaks mode

• astride (bool = False) – A bool indicating if the symmetry is made astride the symmetryPoint or not ( [-1,1] vs. [-1,0][0,1] )

Return type:

Optional[QgsGraduatedSymbolRenderer]

Returns:

new QgsGraduatedSymbolRenderer object

Deprecated since version 3.10.

dataDefinedSizeLegend(self) → QgsDataDefinedSizeLegend | None

Returns configuration of appearance of legend when using data-defined size for marker symbols. Will return None if the functionality is disabled.

Return type:

Optional[QgsDataDefinedSizeLegend]

deleteAllClasses(self)

deleteClass(self, idx: int)

Parameters:

idx (int)

graduatedMethod(self) → Qgis.GraduatedMethod

Returns the method used for graduation (either size or color).

See also

setGraduatedMethod()

Return type:

Qgis.GraduatedMethod

labelFormat(self) → QgsRendererRangeLabelFormat

Returns the label format used to generate default classification labels

Deprecated since version 3.10: Use classificationMethod() and QgsClassificationMethod.setLabelFormat instead.

Return type:

QgsRendererRangeLabelFormat

legendKeyForValue(self, value: float) → str

Returns the matching legend key for a value.

Parameters:

value (float)

Return type:

str

static makeBreaksSymmetric(breaks: Iterable[float], symmetryPoint: float, astride: bool) → List[float]

Remove the breaks that are above the existing opposite sign classes to keep colors symmetrically balanced around symmetryPoint Does not put a break on the symmetryPoint. This is done before.

Parameters:

• breaks (Iterable[float]) – The breaks of an already-done classification

• symmetryPoint (float) – The point around which we want a symmetry

• astride (bool) – A bool indicating if the symmetry is made astride the symmetryPoint or not ( [-1,1] vs. [-1,0][0,1] )

Added in version 3.4.

Deprecated since version 3.10: Use QgsClassificationMethod.makeBreaksSymmetric instead.

Return type:

List[float]

maxSymbolSize(self) → float

Returns the max symbol size when graduated by size

Return type:

float

minSymbolSize(self) → float

Returns the min symbol size when graduated by size

Return type:

float

mode(self) → QgsGraduatedSymbolRenderer.Mode

Deprecated since version 3.10.

Use classficationMethod() instead.

Return type:

QgsGraduatedSymbolRenderer.Mode

moveClass(self, from_: int, to: int)

Moves the category at index position from to index position to.

Parameters:

• from (int)

• to (int)

rangeForValue(self, value: float) → QgsRendererRange | None

Returns the renderer range matching the provided value, or None if no range matches the value.

Added in version 3.10.1.

Parameters:

value (float)

Return type:

Optional[QgsRendererRange]

ranges(self) → List[QgsRendererRange]

Returns a list of all ranges used in the classification.

Return type:

List[QgsRendererRange]

rangesHaveGaps(self) → bool

Tests whether classes assigned to the renderer have gaps between the ranges.

Return type:

bool

Returns:

True if ranges have gaps

rangesOverlap(self) → bool

Tests whether classes assigned to the renderer have ranges which overlap.

Return type:

bool

Returns:

True if ranges overlap

setAstride(self, astride: bool)

Set if we want a central class astride the pivot value

Added in version 3.4.

Deprecated since version 3.10: Use classficationMethod() instead.

Parameters:

astride (bool)

setClassAttribute(self, attr: str | None)

Sets the attribute name (or expression) used for the classification.

See also

classAttribute()

Parameters:

attr (Optional[str])

setClassificationMethod(self, method: QgsClassificationMethod | None)

Defines the classification method This will take ownership of the method

Added in version 3.10.

Parameters:

method (Optional[QgsClassificationMethod])

setDataDefinedSizeLegend(self, settings: QgsDataDefinedSizeLegend | None)

Configures appearance of legend when renderer is configured to use data-defined size for marker symbols. This allows configuring for which values (symbol sizes) should be shown in the legend, whether to display different symbol sizes collapsed in one legend node or separated across multiple legend nodes etc.

When renderer does not use data-defined size or does not use marker symbols, these settings will be ignored. Takes ownership of the passed settings objects. None is a valid input that disables data-defined size legend.

Parameters:

settings (Optional[QgsDataDefinedSizeLegend])

setGraduatedMethod(self, method: Qgis.GraduatedMethod)

Set the method used for graduation (either size or color).

See also

graduatedMethod()

Parameters:

method (Qgis.GraduatedMethod)

setLabelFormat(self, labelFormat: QgsRendererRangeLabelFormat, updateRanges: bool = False)

Set the label format used to generate default classification labels

Parameters:

• labelFormat (QgsRendererRangeLabelFormat) – The string appended to classification labels

• updateRanges (bool = False) – If True then ranges ending with the old unit string are updated to the new.

Deprecated since version 3.10: Use classificationMethod() and QgsClassificationMethod.setLabelFormat instead.

setMode(self, mode: QgsGraduatedSymbolRenderer.Mode)

Deprecated since version 3.10.

Use classficationMethod() instead.

Parameters:

mode (QgsGraduatedSymbolRenderer.Mode)

setSourceColorRamp(self, ramp: QgsColorRamp | None)

Sets the source color ramp.

Parameters:

ramp (Optional[QgsColorRamp]) – color ramp. Ownership is transferred to the renderer

setSourceSymbol(self, sym: QgsSymbol | None)

Sets the source symbol for the renderer, which is the base symbol used for the each classes’ symbol before applying the classes’ color.

Parameters:

sym (Optional[QgsSymbol]) – source symbol, ownership is transferred to the renderer

See also

sourceSymbol()

See also

setSourceColorRamp()

setSymbolSizes(self, minSize: float, maxSize: float)

set varying symbol size for classes

Note

the classes must already be set so that symbols exist

Parameters:

• minSize (float)

• maxSize (float)

setSymmetryPoint(self, symmetryPoint: float)

Set the pivot point

Added in version 3.4.

Deprecated since version 3.10: Use classficationMethod() instead.

Parameters:

symmetryPoint (float)

setUseSymmetricMode(self, useSymmetricMode: bool)

Set if we want to classify symmetric around a given value

Added in version 3.4.

Deprecated since version 3.10: Use classficationMethod() instead.

Parameters:

useSymmetricMode (bool)

sortByLabel(self, order: Qt.SortOrder = Qt.AscendingOrder)

Parameters:

order (Qt.SortOrder = Qt.AscendingOrder)

sortByValue(self, order: Qt.SortOrder = Qt.AscendingOrder)

Parameters:

order (Qt.SortOrder = Qt.AscendingOrder)

sourceColorRamp(self) → QgsColorRamp | None

Returns the source color ramp, from which each classes’ color is derived.

See also

setSourceColorRamp()

See also

sourceSymbol()

Return type:

Optional[QgsColorRamp]

sourceSymbol(self) → QgsSymbol | None

Returns the renderer’s source symbol, which is the base symbol used for the each classes’ symbol before applying the classes’ color.

See also

setSourceSymbol()

See also

sourceColorRamp()

Return type:

Optional[QgsSymbol]

symbolForValue(self, value: float) → QgsSymbol | None

Gets the symbol which is used to represent value.

Parameters:

value (float)

Return type:

Optional[QgsSymbol]

symmetryPoint(self) → float

Returns the pivot value for symmetric classification

Added in version 3.4.

Deprecated since version 3.10: Use classficationMethod() instead.

Return type:

float

updateClasses(self, vlayer: QgsVectorLayer | None, mode: QgsGraduatedSymbolRenderer.Mode, nclasses: int, useSymmetricMode: bool = False, symmetryPoint: float = 0, astride: bool = False)

Recalculate classes for a layer

Parameters:

• vlayer (Optional[QgsVectorLayer]) – The layer being rendered (from which data values are calculated)

• mode (QgsGraduatedSymbolRenderer.Mode) – The calculation mode

• nclasses (int) – The number of classes to calculate (approximate for some modes)

• useSymmetricMode (bool = False) – A bool indicating if we want to have classes and hence colors ramp symmetric around a value

• symmetryPoint (float = 0) – The value around which the classes will be symmetric if useSymmetricMode is checked

• astride (bool = False) – A bool indicating if the symmetry is made astride the symmetryPoint or not ( [-1,1] vs. [-1,0][0,1] )

Deprecated since version 3.10.

updateClasses(self, vl: QgsVectorLayer | None, nclasses: int) → str

Recalculate classes for a layer

Parameters:

• vl (Optional[QgsVectorLayer]) – The layer being rendered (from which data values are calculated)

• nclasses (int) – the number of classes

Return type:

str

Returns:

Optional parameter for error reporting

updateColorRamp(self, ramp: QgsColorRamp | None = None)

Update the color ramp used. Also updates all symbols colors. Doesn’t alter current breaks.

Parameters:

ramp (Optional[QgsColorRamp] = None) – color ramp. Ownership is transferred to the renderer

updateRangeLabel(self, rangeIndex: int, label: str | None) → bool

Parameters:

• rangeIndex (int)

• label (Optional[str])

Return type:

bool

updateRangeLabels(self)

Updates the labels of the ranges

Added in version 3.10.

updateRangeLowerValue(self, rangeIndex: int, value: float) → bool

Parameters:

• rangeIndex (int)

• value (float)

Return type:

bool

updateRangeRenderState(self, rangeIndex: int, render: bool) → bool

Parameters:

• rangeIndex (int)

• render (bool)

Return type:

bool

updateRangeSymbol(self, rangeIndex: int, symbol: QgsSymbol | None) → bool

Parameters:

• rangeIndex (int)

• symbol (Optional[QgsSymbol])

Return type:

bool

updateRangeUpperValue(self, rangeIndex: int, value: float) → bool

Parameters:

• rangeIndex (int)

• value (float)

Return type:

bool

updateSymbols(self, sym: QgsSymbol | None)

Update all the symbols but leave breaks and colors. This method also sets the source symbol for the renderer.

Parameters:

sym (Optional[QgsSymbol]) – source symbol to use for classes. Ownership is not transferred.

See also

setSourceSymbol()

useSymmetricMode(self) → bool

Returns if we want to classify symmetric around a given value

Added in version 3.4.

Deprecated since version 3.10: Use classficationMethod() instead.

Return type:

bool