Plotting

This module contains plotting methods.

We provide some high-level plotting methods which work on the outputs of different srai components. By default, folium based functions are exposed within plotting module. Additional functions can be found in srai.plotting.plotly_wrapper module.

Functions

srai.plotting.plot_all_neighbourhood(
    regions_gdf,
    region_id,
    neighbourhood,
    neighbourhood_max_distance=100,
    tiles_style="OpenStreetMap",
    height="100%",
    width="100%",
    colormap=px.colors.sequential.Agsunset_r,
    map=None,
    show_borders=True,
)

Plot full neighbourhood on a map using Folium library.

PARAMETER	DESCRIPTION
regions_gdf	Region indexes and geometries to plot. TYPE: gpd.GeoDataFrame
region_id	Center region_id around which the neighbourhood should be plotted. TYPE: IndexType
neighbourhood	Neighbourhood class required for finding neighbours. TYPE: Neighbourhood[IndexType]
neighbourhood_max_distance	Max distance for rendering neighbourhoods. Neighbours farther away won't be coloured, and will be left as "other" regions. Defaults to 100. TYPE: int DEFAULT: 100
tiles_style	Map style background. For more styles, look at tiles param at https://geopandas.org/en/stable/docs/reference/api/geopandas.GeoDataFrame.explore.html. Defaults to "OpenStreetMap". TYPE: str DEFAULT: 'OpenStreetMap'
height	Height of the plot. Defaults to "100%". TYPE: Union[str, float] DEFAULT: '100%'
width	Width of the plot. Defaults to "100%". TYPE: Union[str, float] DEFAULT: '100%'
colormap	Colormap to apply to the neighbourhoods. Defaults to px.colors.sequential.Agsunset_r from plotly library. TYPE: Union[str, List[str]] DEFAULT: px.colors.sequential.Agsunset_r
map	Existing map instance on which to draw the plot. Defaults to None. TYPE: folium.Map DEFAULT: None
show_borders	Whether to show borders between regions or not. Defaults to True. TYPE: bool DEFAULT: True

RETURNS	DESCRIPTION
folium.Map	folium.Map: Generated map.

Source code in srai/plotting/folium_wrapper.py

def plot_all_neighbourhood(
    regions_gdf: gpd.GeoDataFrame,
    region_id: IndexType,
    neighbourhood: Neighbourhood[IndexType],
    neighbourhood_max_distance: int = 100,
    tiles_style: str = "OpenStreetMap",
    height: Union[str, float] = "100%",
    width: Union[str, float] = "100%",
    colormap: Union[str, list[str]] = px.colors.sequential.Agsunset_r,
    map: Optional[folium.Map] = None,
    show_borders: bool = True,
) -> folium.Map:
    """
    Plot full neighbourhood on a map using Folium library.

    Args:
        regions_gdf (gpd.GeoDataFrame): Region indexes and geometries to plot.
        region_id (IndexType): Center `region_id` around which the neighbourhood should be plotted.
        neighbourhood (Neighbourhood[IndexType]): `Neighbourhood` class required for finding
            neighbours.
        neighbourhood_max_distance (int, optional): Max distance for rendering neighbourhoods.
            Neighbours farther away won't be coloured, and will be left as "other" regions.
            Defaults to 100.
        tiles_style (str, optional): Map style background. For more styles, look at tiles param at
            https://geopandas.org/en/stable/docs/reference/api/geopandas.GeoDataFrame.explore.html.
            Defaults to "OpenStreetMap".
        height (Union[str, float], optional): Height of the plot. Defaults to "100%".
        width (Union[str, float], optional): Width of the plot. Defaults to "100%".
        colormap (Union[str, List[str]], optional): Colormap to apply to the neighbourhoods.
            Defaults to `px.colors.sequential.Agsunset_r` from plotly library.
        map (folium.Map, optional): Existing map instance on which to draw the plot.
            Defaults to None.
        show_borders (bool, optional): Whether to show borders between regions or not.
            Defaults to True.

    Returns:
        folium.Map: Generated map.
    """
    if region_id not in regions_gdf.index:
        raise ValueError(f"{region_id!r} doesn't exist in provided regions_gdf.")

    regions_gdf_copy = regions_gdf.copy()
    regions_gdf_copy["region"] = "other"
    regions_gdf_copy.loc[region_id, "region"] = "selected"

    distance = 1
    neighbours_ids = neighbourhood.get_neighbours_at_distance(region_id, distance).intersection(
        regions_gdf.index
    )
    while neighbours_ids and distance <= neighbourhood_max_distance:
        regions_gdf_copy.loc[list(neighbours_ids), "region"] = distance
        distance += 1
        neighbours_ids = neighbourhood.get_neighbours_at_distance(region_id, distance).intersection(
            regions_gdf.index
        )

    if not isinstance(colormap, str):
        colormap = _generate_colormap(
            distance, colormap=_resample_plotly_colormap(colormap, min(distance, 10))
        )

    return regions_gdf_copy.reset_index().explore(
        column="region",
        tooltip=[REGIONS_INDEX, "region"],
        tiles=tiles_style,
        height=height,
        width=width,
        cmap=colormap,
        categorical=True,
        categories=["selected", *list(range(distance))[1:], "other"],
        style_kwds=dict(color="#444", opacity=0.5 if show_borders else 0, fillOpacity=0.8),
        legend=distance <= 11,
        m=map,
    )

srai.plotting.plot_neighbours(
    regions_gdf,
    region_id,
    neighbours_ids,
    tiles_style="OpenStreetMap",
    height="100%",
    width="100%",
    map=None,
    show_borders=True,
)

Plot neighbours on a map using Folium library.

PARAMETER	DESCRIPTION
regions_gdf	Region indexes and geometries to plot. TYPE: gpd.GeoDataFrame
region_id	Center region_id around which the neighbourhood should be plotted. TYPE: IndexType
neighbours_ids	List of neighbours to highlight. TYPE: Set[IndexType]
tiles_style	Map style background. For more styles, look at tiles param at https://geopandas.org/en/stable/docs/reference/api/geopandas.GeoDataFrame.explore.html. Defaults to "OpenStreetMap". TYPE: str DEFAULT: 'OpenStreetMap'
height	Height of the plot. Defaults to "100%". TYPE: Union[str, float] DEFAULT: '100%'
width	Width of the plot. Defaults to "100%". TYPE: Union[str, float] DEFAULT: '100%'
map	Existing map instance on which to draw the plot. Defaults to None. TYPE: folium.Map DEFAULT: None
show_borders	Whether to show borders between regions or not. Defaults to True. TYPE: bool DEFAULT: True

RETURNS	DESCRIPTION
folium.Map	folium.Map: Generated map.

Source code in srai/plotting/folium_wrapper.py

def plot_neighbours(
    regions_gdf: gpd.GeoDataFrame,
    region_id: IndexType,
    neighbours_ids: set[IndexType],
    tiles_style: str = "OpenStreetMap",
    height: Union[str, float] = "100%",
    width: Union[str, float] = "100%",
    map: Optional[folium.Map] = None,
    show_borders: bool = True,
) -> folium.Map:
    """
    Plot neighbours on a map using Folium library.

    Args:
        regions_gdf (gpd.GeoDataFrame): Region indexes and geometries to plot.
        region_id (IndexType): Center `region_id` around which the neighbourhood should be plotted.
        neighbours_ids (Set[IndexType]): List of neighbours to highlight.
        tiles_style (str, optional): Map style background. For more styles, look at tiles param at
            https://geopandas.org/en/stable/docs/reference/api/geopandas.GeoDataFrame.explore.html.
            Defaults to "OpenStreetMap".
        height (Union[str, float], optional): Height of the plot. Defaults to "100%".
        width (Union[str, float], optional): Width of the plot. Defaults to "100%".
        map (folium.Map, optional): Existing map instance on which to draw the plot.
            Defaults to None.
        show_borders (bool, optional): Whether to show borders between regions or not.
            Defaults to True.

    Returns:
        folium.Map: Generated map.
    """
    if region_id not in regions_gdf.index:
        raise ValueError(f"{region_id!r} doesn't exist in provided regions_gdf.")

    regions_gdf_copy = regions_gdf.copy()
    regions_gdf_copy["region"] = "other"
    regions_gdf_copy.loc[region_id, "region"] = "selected"
    regions_gdf_copy.loc[list(neighbours_ids), "region"] = "neighbour"
    return regions_gdf_copy.reset_index().explore(
        column="region",
        tooltip=REGIONS_INDEX,
        tiles=tiles_style,
        height=height,
        width=width,
        cmap=[
            "rgb(242, 242, 242)",
            px.colors.sequential.Sunsetdark[-1],
            px.colors.sequential.Sunsetdark[2],
        ],
        categorical=True,
        categories=["selected", "neighbour", "other"],
        style_kwds=dict(color="#444", opacity=0.5 if show_borders else 0, fillOpacity=0.8),
        m=map,
    )

srai.plotting.plot_numeric_data(
    regions_gdf,
    data_column,
    embedding_df=None,
    tiles_style="CartoDB positron",
    height="100%",
    width="100%",
    colormap=px.colors.sequential.Sunsetdark,
    map=None,
    show_borders=False,
    opacity=0.8,
)

Plot numerical data within regions shapes using Folium library.

PARAMETER	DESCRIPTION
regions_gdf	Region indexes and geometries to plot. TYPE: gpd.GeoDataFrame
embedding_df	Region indexes and numerical data to plot. If not provided, will use regions_gdf. TYPE: Union[pd.DataFrame, gpd.GeoDataFrame] DEFAULT: None
data_column	Name of the column used to colour the regions. TYPE: str
tiles_style	Map style background. For more styles, look at tiles param at https://geopandas.org/en/stable/docs/reference/api/geopandas.GeoDataFrame.explore.html. Defaults to "CartoDB positron". TYPE: str DEFAULT: 'CartoDB positron'
height	Height of the plot. Defaults to "100%". TYPE: Union[str, float] DEFAULT: '100%'
width	Width of the plot. Defaults to "100%". TYPE: Union[str, float] DEFAULT: '100%'
colormap	Colormap to apply to the regions. Defaults to px.colors.sequential.Sunsetdark. TYPE: Union[str, List[str]] DEFAULT: px.colors.sequential.Sunsetdark
map	Existing map instance on which to draw the plot. Defaults to None. TYPE: folium.Map DEFAULT: None
show_borders	Whether to show borders between regions or not. Defaults to False. TYPE: bool DEFAULT: False
opacity	Opacity of coloured regions. TYPE: float DEFAULT: 0.8

RETURNS	DESCRIPTION
folium.Map	folium.Map: Generated map.

Source code in srai/plotting/folium_wrapper.py

def plot_numeric_data(
    regions_gdf: gpd.GeoDataFrame,
    data_column: str,
    embedding_df: Optional[Union[pd.DataFrame, gpd.GeoDataFrame]] = None,
    tiles_style: str = "CartoDB positron",
    height: Union[str, float] = "100%",
    width: Union[str, float] = "100%",
    colormap: Union[str, list[str]] = px.colors.sequential.Sunsetdark,
    map: Optional[folium.Map] = None,
    show_borders: bool = False,
    opacity: float = 0.8,
) -> folium.Map:
    """
    Plot numerical data within regions shapes using Folium library.

    Args:
        regions_gdf (gpd.GeoDataFrame): Region indexes and geometries to plot.
        embedding_df (Union[pd.DataFrame, gpd.GeoDataFrame], optional): Region indexes and numerical
            data to plot. If not provided, will use regions_gdf.
        data_column (str): Name of the column used to colour the regions.
        tiles_style (str, optional): Map style background. For more styles, look at tiles param at
            https://geopandas.org/en/stable/docs/reference/api/geopandas.GeoDataFrame.explore.html.
            Defaults to "CartoDB positron".
        height (Union[str, float], optional): Height of the plot. Defaults to "100%".
        width (Union[str, float], optional): Width of the plot. Defaults to "100%".
        colormap (Union[str, List[str]], optional): Colormap to apply to the regions.
            Defaults to px.colors.sequential.Sunsetdark.
        map (folium.Map, optional): Existing map instance on which to draw the plot.
            Defaults to None.
        show_borders (bool, optional): Whether to show borders between regions or not.
            Defaults to False.
        opacity (float, optional): Opacity of coloured regions.

    Returns:
        folium.Map: Generated map.
    """
    if embedding_df is None:
        embedding_df = regions_gdf

    regions_gdf_copy = regions_gdf[[GEOMETRY_COLUMN]].copy()
    regions_gdf_copy = regions_gdf_copy.merge(embedding_df[[data_column]], on=REGIONS_INDEX)

    if not isinstance(colormap, str):
        colormap = _generate_linear_colormap(
            colormap,
            min_value=regions_gdf_copy[data_column].min(),
            max_value=regions_gdf_copy[data_column].max(),
        )

    # Jinja2 rendering issue whne column is number-like. Workaround by using str column name.
    # TypeError: '<' not supported between instances of 'float' and 'str'
    regions_gdf_copy.rename(columns={data_column: "value"}, inplace=True)

    return regions_gdf_copy.reset_index().explore(
        column="value",
        tooltip=[REGIONS_INDEX, "value"],
        tiles=tiles_style,
        height=height,
        width=width,
        legend=True,
        cmap=colormap,
        categorical=False,
        style_kwds=dict(color="#444", opacity=0.5 if show_borders else 0, fillOpacity=opacity),
        m=map,
    )

srai.plotting.plot_regions(
    regions_gdf,
    tiles_style="OpenStreetMap",
    height="100%",
    width="100%",
    colormap=px.colors.qualitative.Bold,
    map=None,
    show_borders=True,
)

Plot regions shapes using Folium library.

PARAMETER	DESCRIPTION
regions_gdf	Region indexes and geometries to plot. TYPE: gpd.GeoDataFrame
tiles_style	Map style background. For more styles, look at tiles param at https://geopandas.org/en/stable/docs/reference/api/geopandas.GeoDataFrame.explore.html. Defaults to "OpenStreetMap". TYPE: str DEFAULT: 'OpenStreetMap'
height	Height of the plot. Defaults to "100%". TYPE: Union[str, float] DEFAULT: '100%'
width	Width of the plot. Defaults to "100%". TYPE: Union[str, float] DEFAULT: '100%'
colormap	Colormap to apply to the regions. Defaults to px.colors.qualitative.Bold from plotly library. TYPE: Union[str, List[str]] DEFAULT: px.colors.qualitative.Bold
map	Existing map instance on which to draw the plot. Defaults to None. TYPE: folium.Map DEFAULT: None
show_borders	Whether to show borders between regions or not. Defaults to True. TYPE: bool DEFAULT: True

RETURNS	DESCRIPTION
folium.Map	folium.Map: Generated map.

Source code in srai/plotting/folium_wrapper.py

def plot_regions(
    regions_gdf: gpd.GeoDataFrame,
    tiles_style: str = "OpenStreetMap",
    height: Union[str, float] = "100%",
    width: Union[str, float] = "100%",
    colormap: Union[str, list[str]] = px.colors.qualitative.Bold,
    map: Optional[folium.Map] = None,
    show_borders: bool = True,
) -> folium.Map:
    """
    Plot regions shapes using Folium library.

    Args:
        regions_gdf (gpd.GeoDataFrame): Region indexes and geometries to plot.
        tiles_style (str, optional): Map style background. For more styles, look at tiles param at
            https://geopandas.org/en/stable/docs/reference/api/geopandas.GeoDataFrame.explore.html.
            Defaults to "OpenStreetMap".
        height (Union[str, float], optional): Height of the plot. Defaults to "100%".
        width (Union[str, float], optional): Width of the plot. Defaults to "100%".
        colormap (Union[str, List[str]], optional): Colormap to apply to the regions.
            Defaults to `px.colors.qualitative.Bold` from plotly library.
        map (folium.Map, optional): Existing map instance on which to draw the plot.
            Defaults to None.
        show_borders (bool, optional): Whether to show borders between regions or not.
            Defaults to True.

    Returns:
        folium.Map: Generated map.
    """
    return regions_gdf.reset_index().explore(
        column=REGIONS_INDEX,
        tooltip=REGIONS_INDEX,
        tiles=tiles_style,
        height=height,
        width=width,
        legend=False,
        cmap=colormap,
        categorical=True,
        style_kwds=dict(color="#444", opacity=0.5 if show_borders else 0, fillOpacity=0.5),
        m=map,
    )