add_gdf

MapsGrid.add_gdf(gdf, picker_name=None, pick_method='contains', val_key=None, layer=None, temporary_picker=None, clip=False, reproject='gpd', verbose=False, only_valid=False, set_extent=False, permanent=True, **kwargs)

This will execute the corresponding action on ALL Maps objects of the MapsGrid!

Plot a geopandas.GeoDataFrame on the map.

Parameters:

  • gdf (geopandas.GeoDataFrame, str or pathlib.Path) –

    A GeoDataFrame that should be added to the plot.

    If a string (or pathlib.Path) is provided, it is identified as the path to a file that should be read with geopandas.read_file(gdf).

  • picker_name (str or None) –

    A unique name that is used to identify the pick-method.

    If a picker_name is provided, a new pick-container will be created that can be used to pick geometries of the GeoDataFrame.

    The container can then be accessed via: >>> m.cb.pick__<picker_name> or >>> m.cb.pick[picker_name] and it can be used in the same way as m.cb.pick…

  • pick_method (str or callable) –

    if str :

    The operation that is executed on the GeoDataFrame to identify the picked geometry. Possible values are:

    • ”contains”: pick a geometry only if it contains the clicked point (only works with polygons! (not with lines and points))

    • ”centroids”: pick the closest geometry with respect to the centroids (should work with any geometry whose centroid is defined)

    The default is “centroids”

    if callable :

    A callable that is used to identify the picked geometry. The call-signature is:

    >>> def picker(artist, mouseevent):
>>>     # if the pick is NOT successful:
>>>     return False, dict()
>>>     ...
>>>     # if the pick is successful:
>>>     return True, dict(ID, pos, val, ind)

    The default is “contains”

  • val_key (str) – The dataframe-column used to identify values for pick-callbacks. The default is the value provided via column=… or None.

  • layer (int, str or None) –

    The name of the layer at which the dataset will be plotted.

    • If “all”: the corresponding feature will be added to ALL layers

    • If None, the layer assigned to the Maps-object is used (e.g. m.layer)

    The default is None.

  • temporary_picker (str, optional) – The name of the picker that should be used to make the geometry temporary (e.g. remove it after each pick-event)

  • clip –

    This feature can help with re-projection issues for non-global crs. (see example below)

    Indicator if geometries should be clipped prior to plotting or not.

    • if “crs”: clip with respect to the boundary-shape of the crs

    • if “crs_bounds” : clip with respect to a rectangular crs boundary

    • if “extent”: clip with respect to the current extent of the plot-axis.

    • if the ‘gdal’ python-bindings are installed, you can use gdal to clip the shapes with respect to the crs-boundary. (slower but more robust) The following logical operations are supported:

      • ”gdal_SymDifference” : symmetric difference

      • ”gdal_Intersection” : intersection

      • ”gdal_Difference” : difference

      • ”gdal_Union” : union

    If a suffix “_invert” is added to the clip-string (e.g. “crs_invert” or “gdal_Intersection_invert”) the obtained (clipped) polygons will be inverted.

reprojectstr, optional

Similar to “clip” this feature mainly addresses issues in the way how re-projected geometries are displayed in certain coordinate-systems. (see example below)

  • if “gpd”: re-project geometries geopandas

  • if “cartopy”: re-project geometries with cartopy (slower but more robust)

The default is “gpd”.

>>> mg = MapsGrid(2, 1, crs=Maps.CRS.Stereographic())
>>> mg.m_0_0.add_feature.preset.ocean(reproject="gpd")
>>> mg.m_1_0.add_feature.preset.ocean(reproject="cartopy")
verbosebool, optional

Indicator if a progressbar should be printed when re-projecting geometries with “use_gpd=False”. The default is False.

only_validbool, optional

  • If True, only valid geometries (e.g. gdf.is_valid) are plotted.

  • If False, all geometries are attempted to be plotted (this might result in errors for infinite geometries etc.)

The default is True

set_extent: bool, optional

  • if True, set map extent to the extent of the geometries with +-5% margin.

  • if float, use the value as margin (0-1).

The default is True.

permanentbool, optional

If True, all created artists are added as “permanent” background artists. If False, artists are added as dynamic artists. The default is True.

kwargs :

all remaining kwargs are passed to geopandas.GeoDataFrame.plot(**kwargs)

Returns:

new_artists – The matplotlib-artists added to the plot

Return type:

matplotlib.Artist