Skip to content

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 

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.

PARAMETER DESCRIPTION
regions_gdf

Region indexes and geometries to plot.

TYPE: 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: Agsunset_r

map

Existing map instance on which to draw the plot. Defaults to None.

TYPE: Map DEFAULT: None

show_borders

Whether to show borders between regions or not. Defaults to True.

TYPE: bool DEFAULT: True

RETURNS DESCRIPTION
Map

folium.Map: Generated map.
Source code in srai/plotting/folium_wrapper.py 
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
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 

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.

PARAMETER DESCRIPTION
regions_gdf

Region indexes and geometries to plot.

TYPE: 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: Map DEFAULT: None

show_borders

Whether to show borders between regions or not. Defaults to True.

TYPE: bool DEFAULT: True

RETURNS DESCRIPTION
Map

folium.Map: Generated map.
Source code in srai/plotting/folium_wrapper.py 
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
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 

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.

PARAMETER DESCRIPTION
regions_gdf

Region indexes and geometries to plot.

TYPE: GeoDataFrame

embedding_df

Region indexes and numerical data to plot. If not provided, will use regions_gdf.

TYPE: Union[DataFrame, 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: Sunsetdark

map

Existing map instance on which to draw the plot. Defaults to None.

TYPE: 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
Map

folium.Map: Generated map.
Source code in srai/plotting/folium_wrapper.py 
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
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 

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.

PARAMETER DESCRIPTION
regions_gdf

Region indexes and geometries to plot.

TYPE: 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: Bold

map

Existing map instance on which to draw the plot. Defaults to None.

TYPE: Map DEFAULT: None

show_borders

Whether to show borders between regions or not. Defaults to True.

TYPE: bool DEFAULT: True

RETURNS DESCRIPTION
Map

folium.Map: Generated map.
Source code in srai/plotting/folium_wrapper.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
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,
    )