pygmt.Figure.choropleth

Figure.choropleth(data, column, cmap=True, intensity=None, pen=None, no_clip=False, projection=None, region=None, frame=False, verbose=False, panel=False, perspective=False, transparency=None)

Plot a choropleth map.

This method fills polygons based on values in a specified data column. It requires the input data to be a geo-like Python object that implements __geo_interface__ (e.g. a geopandas.GeoDataFrame), or an OGR_GMT file containing the geometry and data to plot.

Aliases:

  • B = frame

  • C = cmap

  • I = intensity

  • J = projection

  • R = region

  • N = no_clip

  • W = pen

  • V = verbose

  • a = column

  • c = panel

  • p = perspective

  • t = transparency

Parameters:

  • data (GeoDataFrame | str | PathLike) – A geo-like Python object which implements __geo_interface__ (e.g. a geopandas.GeoDataFrame or shapely.geometry), or an OGR_GMT file containing the geometry and data to plot.

  • column (str) – The name of the data column to use for the fill.

  • cmap (str | bool, default: True) – The CPT to use for filling the polygons. If set to True, the current CPT will be used.

  • intensity (float | None, default: None) – The intensity (nominally in the ±1 range) to modulate the fill color by simulating illumination [Default is no illumination].

  • no_clip (bool, default: False) – Do not clip polygons that fall outside the frame boundaries.

  • pen (str) – Set pen attributes for lines or the outline of symbols.

  • projection (str | None, default: None) – projcode[projparams/]width|scale. Select map projection.

  • region (str or list) – xmin/xmax/ymin/ymax[+r][+uunit]. Specify the region of interest.

  • frame (Frame | Axis | Literal['none'] | str | Sequence[str] | bool, default: False) – Set frame and axes attributes for the plot. It can be a bool, "none", a pygmt.params.Frame or pygmt.params.Axis object. Raw GMT strings or sequences of strings are also supported for backward compatibility. If frame=True, the frame will be drawn with the default attributes. If frame="none", no frame will be drawn. Use a pygmt.params.Frame or pygmt.params.Axis object for more control over the attributes of the frame and axes. A tutorial is available at frame and axes attributes. Full documentation is at https://docs.generic-mapping-tools.org/6.6/gmt.html#b-full.

  • verbose (bool or str) – Select verbosity level [Full usage].

  • panel (int | Sequence[int] | bool, default: False) –

    Select a specific subplot panel. Only allowed when used in Figure.subplot mode.

    • True to advance to the next panel in the selected order.

    • index to specify the index of the desired panel.

    • (row, col) to specify the row and column of the desired panel.

    The panel order is determined by the Figure.subplot method. row, col and index all start at 0.

  • perspective (float | Sequence[float] | str | bool, default: False) –

    Select perspective view and set the azimuth and elevation of the viewpoint.

    Accepts a single value or a sequence of two or three values: azimuth, (azimuth, elevation), or (azimuth, elevation, zlevel).

    • azimuth: Azimuth angle of the viewpoint in degrees [Default is 180, i.e., looking from south to north].

    • elevation: Elevation angle of the viewpoint above the horizon [Default is 90, i.e., looking straight down at nadir].

    • zlevel: Z-level at which 2-D elements (e.g., the plot frame) are drawn. Only applied when used together with zsize or zscale. [Default is at the bottom of the z-axis].

    Alternatively, set perspective=True to reuse the perspective setting from the previous plotting method, or pass a string following the full GMT syntax for finer control (e.g., adding +w or +v modifiers to select an axis location other than the plot origin). See https://docs.generic-mapping-tools.org/6.6/gmt.html#perspective-full for details.

  • transparency (float) – Set transparency level, in [0-100] percent range [Default is 0, i.e., opaque]. Only visible when PDF or raster format output is selected. Only the PNG format selection adds a transparency layer in the image (for further processing).

Examples

>>> import geopandas
>>> import pygmt
>>> world = geopandas.read_file(
...     "https://naciscdn.org/naturalearth/110m/cultural/ne_110m_admin_0_countries.zip"
... )
>>> world["POP_EST"] *= 1e-6  # Population in millions
>>>
>>> fig = pygmt.Figure()
>>> fig.basemap(region=[-19.5, 53, -38, 37.5], projection="M15c", frame=True)
>>> pygmt.makecpt(cmap="bilbao", series=(0, 270, 10), reverse=True)
>>> fig.choropleth(world, column="POP_EST", pen="0.3p,gray10")
>>> fig.colorbar(frame=True)
>>> fig.show()

Examples using pygmt.Figure.choropleth

Choropleth map

Choropleth map