reVReports.utilities.maps.map_geodataframe_column#

map_geodataframe_column(data_df, column, color_map='viridis', breaks=None, map_title=None, legend_title=None, background_df=None, boundaries_df=None, extent=None, boundaries_kwargs=None, layer_kwargs=None, legend_kwargs=None, projection=<geoplot.crs.AlbersEqualArea object>, legend=True, ax=None)[source]#

Create a cartographic quality map

The map symbolizes the values from an input geodataframe, optionally including a background layer (e.g., CONUS landmass), a boundary layer (e.g., state boundaries), and various map style elements.

Parameters:

  • data_df (geopandas.geodataframe.GeoDataFrame) – Input GeoDataFrame with values in column to map. Input geometry type must be one of: Point, Polygon, or MultiPolygon. If background_df and extent are both None, the extent of this dataframe will set the overall map extent.

  • column (str) – Name of the column in data_df to plot.

  • color_map (str or matplotlib.colors.Colormap, default "viridis") – Colors to use for mapping the values of column. This can either be the name of a colormap or an actual colormap instance. By default, the color_map will be "viridis".

  • breaks (list, optional) – List of value breaks to use for classifying the values of column into the colors of color_map. Break values should be provided in ascending order. Values of column that are below the first break or above the last break will be shown in the first and last classes, respectively. If not specified, the map will be created using a Quantile classification scheme with 5 classes.

  • map_title (str, optional) – Title to use for the map, by default None.

  • legend_title (str, optional) – Title to use for the legend, by default None.

  • background_df (geopandas.geodataframe.GeoDataFrame, optional) –

    Geodataframe to plot as background, behind data_df. Expected to have geometry type of Polygon or MultiPolygon. A common case would be to provide polygons representing the landmass, country, or region that you are mapping as the background.

    Providing this layer has the side-effect of creating a dropshadow for the whole map, so is generally recommended for nicer styling of the output map. Configuration of the display of this layer is not currently available to the user.

    If set to None (default), no background layer will be plotted.

    If specified and extent is None, the extent of this dataframe will set the overall map extent.

  • boundaries_df (geopandas.geodataframe.GeoDataFrame, optional) –

    Geodataframe to plot on the map data_df as boundaries. Expected to have geometry type of Polygon or MultiPolygon. A common case would be to provide polygons for states or other sub-regions of interest.

    If set to None (default), no background layer will be plotted.

  • extent (list or array-like, optional) – Extent to zoom to for displaying the map. Should be of the format: [xmin, ymin, xmax, ymax] in the CRS units of data_df. By default, this is None, which will result in the extent of the map being set based on background_df (if provided) or data_df.

  • boundaries_kwargs (dict, optional) – Keyword arguments that can be used to configure display of the boundaries layer. If not specified (=None), it will default to use {"linewidth": 0.75, "zorder": 1, "edgecolor": "white"}, which will result in thin white boundaries being plotted underneath the data layer. To place these on top, change zorder to 2. For other options, refer to https://residentmario.github.io/geoplot/user_guide/Customizing_Plots.html and https://matplotlib.org/stable/api/_as_gen/matplotlib.patches.Polygon.html#matplotlib.patches.Polygon.

  • layer_kwargs (dict, optional) – Optional styling to be applied to the data layer. By default None, which results in the layer being plotted using the input breaks and colormap and no other changes. As an example, you could change the edge color and line width of a polygon data layer using by specifying layer_kwargs={"edgecolor": "gray", "linewidth": 0.5}. Refer to https://residentmario.github.io/geoplot/user_guide/Customizing_Plots.html#Cosmetic-parameters for other options.

  • legend_kwargs (dict, optional) – Keyword arguments that can be used to configure display of the legend. If not specified (=None), it will default to use (legend_kwargs={"marker": "s", "frameon": False, "bbox_to_anchor": (1, 0.5), "loc": "center left"}). For more information on the options available, refer to https://residentmario.github.io/geoplot/user_guide/ Customizing_Plots.html#Legend.

  • projection (Projections, optional) – Projection to use for creating the map. Default is geoplot.crs.AlbersEqualArea(). For names of other options, refer to https://scitools.org.uk/cartopy/docs/v0.15/crs/projections.html.

  • ax (cartopy.mpl.geoaxes.GeoAxes, optional) – If specified, the map will be added to the specified existing GeoAxes. If not specified (default), a new GeoAxes will be created and returned.

Returns:

cartopy.mpl.geoaxes.GeoAxes – Plot object of the map.

Raises:

NotImplementedError – A NotImplementedError will be raised if data_df does not have a geometry type of Point, Polygon, or MultiPolygon.