Maps

Interactive and static mapping of multiple GeoDataFrames.

The main function is ‘explore’, which displays one of more GeoDataFrames together in an interactive map with layers that can be toggled on and off. The ‘samplemap’ and ‘clipmap’ functions do the same, but displays a random and chosen area respectfully.

The ‘qtm’ function shows a simple static map of one or more GeoDataFrames.

class RasterDataset[source]

Bases: object

Placeholder.

clipmap(*gdfs, column=None, mask=None, explore=True, max_zoom=40, smooth_factor=1.5, browser=False, max_images=10, **kwargs)[source]

Shows an interactive map of a of GeoDataFrames clipped to the mask extent.

It takes all the GeoDataFrames specified, clips them to the extent of the mask, and displays the resulting geometries in an interactive map with a common legends. The layers can be toggled on and off.

For more info about the labeling and coloring of the map, see the explore function.

Note

The maximum zoom level only works on the OpenStreetMap background map.

Parameters:

  • *gdfs (GeoDataFrame) – one or more GeoDataFrames.

  • mask (GeoDataFrame | GeoSeries | Geometry) – the geometry to clip the data by.

  • column (str | None) – The column to color the geometries by. Defaults to None, which means each GeoDataFrame will get a unique color.

  • max_zoom (int) – The maximum allowed level of zoom. Higher number means more zoom allowed. Defaults to 30, which is higher than the geopandas default.

  • smooth_factor (int | float) – How much to simplify the geometries. 1 is the minimum, 5 is quite a lot of simplification.

  • explore (bool) – If True (default), an interactive map will be displayed. If False, or not in Jupyter, a static plot will be shown.

  • browser (bool) – If False (default), the maps will be shown in Jupyter. If True the maps will be opened in a browser folder.

  • max_images (int) – Maximum number of images (Image, ImageCollection, Band) to show per map. Defaults to 10.

  • **kwargs – Keyword arguments to pass to geopandas.GeoDataFrame.explore, for instance ‘cmap’ to change the colors, ‘scheme’ to change how the data is grouped. This defaults to ‘fisherjenkssampled’ for numeric data.

Return type:

Explore | Map

See Also:

explore: same functionality, but shows the entire area of the geometries. samplemap: same functionality, but shows only a random area of a given size.

explore(*gdfs, column=None, center=None, max_zoom=40, browser=False, smooth_factor=1.5, size=None, max_images=10, images_to_gdf=False, **kwargs)[source]

Interactive map of GeoDataFrames with layers that can be toggled on/off.

It takes all the given GeoDataFrames and displays them together in an interactive map with a common legend. If ‘column’ is not specified, each GeoDataFrame is given a unique color.

The ‘center’ parameter can be used to show only parts of large datasets. ‘center’ can be a string of a city or address, a coordinate tuple or a geometry-like object.

Parameters:

  • *gdfs (GeoDataFrame | dict[str, GeoDataFrame]) – one or more GeoDataFrames.

  • column (str | None) – The column to color the geometries by. Defaults to None, which means each GeoDataFrame will get a unique color.

  • center (Any | None) – Geometry-like object to center the map on. If a three-length tuple is given, the first two should be x and y coordinates and the third should be a number of meters to buffer the centerpoint by.

  • max_zoom (int) – The maximum allowed level of zoom. Higher number means more zoom allowed. Defaults to 30, which is higher than the geopandas default.

  • browser (bool) – If False (default), the maps will be shown in Jupyter. If True the maps will be opened in a browser folder.

  • smooth_factor (int | float) – How much to simplify the geometries. 1 is the minimum, 5 is quite a lot of simplification.

  • size (int | None) – The buffer distance. Only used when center is given. It then defaults to 1000.

  • max_images (int) – Maximum number of images (Image, ImageCollection, Band) to show per map. Defaults to 10.

  • images_to_gdf (bool) – If True (not default), images (Image, ImageCollection, Band) will be converted to GeoDataFrame and added to the map.

  • **kwargs – Keyword arguments to pass to geopandas.GeoDataFrame.explore, for instance ‘cmap’ to change the colors, ‘scheme’ to change how the data is grouped. This defaults to ‘fisherjenkssampled’ for numeric data.

Return type:

Explore

See Also:

samplemap: same functionality, but shows only a random area of a given size. clipmap: same functionality, but shows only the areas clipped by a given mask.

Examples:

>>> import sgis as sg
>>> roads = sg.read_parquet_url("https://media.githubusercontent.com/media/statisticsnorway/ssb-sgis/main/tests/testdata/roads_oslo_2022.parquet")
>>> points = sg.read_parquet_url("https://media.githubusercontent.com/media/statisticsnorway/ssb-sgis/main/tests/testdata/points_oslo.parquet")

Explore the area 500 meter around a given point. Coordinates are in UTM 33 format (25833).

>>> sg.explore(roads, points, center=(262274.6528, 6650143.176, 500))

Same as above, but with coordinates given as WGS84, same as the coordinates displayed in the corner of the map.

>>> sg.explore(roads, points, center_4326=(10.7463, 59.92, 500))

With additional arguments.

>>> roads["meters"] = roads.length
>>> points["meters"] = points.length
>>> sg.explore(roads, points, column="meters", cmap="plasma", max_zoom=60, center_4326=(10.7463, 59.92, 500))
explore_locals(*gdfs, convert=True, crs=None, **kwargs)[source]

Displays all local variables with geometries (GeoDataFrame etc.).

Local means inside a function or file/notebook.

Parameters:

  • *gdfs (GeoDataFrame) – Additional GeoDataFrames.

  • convert (bool) – If True (default), non-GeoDataFrames will be converted to GeoDataFrames if possible.

  • crs (Any | None) – Optional crs if no objects have any crs.

  • **kwargs – keyword arguments passed to sg.explore.

Return type:

None

qtm(*gdfs, column=None, title=None, black=True, size=10, legend=True, cmap=None, k=5, **kwargs)[source]

Quick, thematic map of one or more GeoDataFrames.

Shows one or more GeoDataFrames in the same plot, with a common color scheme if column is specified, otherwise with unique colors for each GeoDataFrame.

The ‘qtm’ name is taken from the tmap package in R.

Parameters:

  • *gdfs (GeoDataFrame) – One or more GeoDataFrames to plot.

  • column (str | None) – The column to color the map by. Defaults to None, meaning each GeoDataFrame is given a unique color.

  • title (str | None) – Text to use as the map’s heading.

  • black (bool) – If True (default), the background color will be black and the title white. If False, it will be the opposite. The colormap will also be ‘viridis’ when black, and ‘RdPu’ when white.

  • size (int) – Size of the plot. Defaults to 10.

  • title_fontsize – Size of the title.

  • legend (bool) – Whether to add legend. Defaults to True.

  • cmap (str | None) – Color palette of the map. See: https://matplotlib.org/stable/tutorials/colors/colormaps.html

  • k (int) – Number of color groups.

  • **kwargs – Additional keyword arguments taken by the geopandas plot method.

Return type:

None

See also

ThematicMap: Class with more options for customising the plot.

samplemap(*gdfs, column=None, size=1000, sample_from_first=True, max_zoom=40, smooth_factor=1.5, explore=True, browser=False, max_images=10, **kwargs)[source]

Shows an interactive map of a random area of GeoDataFrames.

It takes all the GeoDataFrames specified, takes a random sample point from the first, and shows all geometries within a given radius of this point. Otherwise works like the explore function.

To re-use the sample area, use the line that is printed in this function, containing the size and centerpoint. This line can be copypasted directly into the explore or clipmap functions.

Note

The maximum zoom level only works on the OpenStreetMap background map.

Parameters:

  • *gdfs (GeoDataFrame) – one or more GeoDataFrames.

  • column (str | None) – The column to color the geometries by. Defaults to None, which means each GeoDataFrame will get a unique color.

  • size (int) – the radius to buffer the sample point by before clipping with the data. Defaults to 1000 (meters).

  • sample_from_first (bool) – If True (default), the sample point is taken form the first specified GeoDataFrame. If False, all GeoDataFrames are considered.

  • max_zoom (int) – The maximum allowed level of zoom. Higher number means more zoom allowed. Defaults to 30, which is higher than the geopandas default.

  • smooth_factor (int) – How much to simplify the geometries. 1 is the minimum, 5 is quite a lot of simplification.

  • explore (bool) – If True (default), an interactive map will be displayed. If False, or not in Jupyter, a static plot will be shown.

  • browser (bool) – If False (default), the maps will be shown in Jupyter. If True the maps will be opened in a browser folder.

  • max_images (int) – Maximum number of images (Image, ImageCollection, Band) to show per map. Defaults to 10.

  • **kwargs – Keyword arguments to pass to geopandas.GeoDataFrame.explore, for instance ‘cmap’ to change the colors, ‘scheme’ to change how the data is grouped. This defaults to ‘fisherjenkssampled’ for numeric data.

Return type:

Explore

See Also:

explore: Same functionality, but shows the entire area of the geometries. clipmap: Same functionality, but shows only the areas clipped by a given mask.

Examples:

>>> from sgis import read_parquet_url, samplemap
>>> roads = read_parquet_url("https://media.githubusercontent.com/media/statisticsnorway/ssb-sgis/main/tests/testdata/roads_eidskog_2022.parquet")
>>> points = read_parquet_url("https://media.githubusercontent.com/media/statisticsnorway/ssb-sgis/main/tests/testdata/points_eidskog.parquet")

With default sample size. To get a new sample area, simply re-run the line.

>>> samplemap(roads, points)

Sample area with a radius of 5 kilometers.

>>> samplemap(roads, points, size=5_000, column="meters")