maps

Classes

Map

A specialized Subplot for plotting geospatial data.

Module Contents

class maps.Map(*args, domain=None, crs=None, **kwargs)

Bases: earthkit.plots.components.subplots.Subplot

A specialized Subplot for plotting geospatial data.

Parameters:

  • row (int, optional) – The row index of the subplot in the figure.

  • column (int, optional) – The column index of the subplot in the figure.

  • figure (Figure, optional) – The Figure to which the subplot belongs.

  • domain (str, tuple, list or Domain, optional) – The domain of the map. Can be a string, a tuple or a list of coordinates, or a Domain object. This is used to set the extent and projection of the map.

  • crs (cartopy.crs.CRS, optional) – The CRS of the map. If not provided, it will be inferred from the domain or set to PlateCarree.

  • **kwargs – Additional keyword arguments to pass to the matplotlib Axes object.

administrative_areas(*args, **kwargs)

Add country boundary polygons from Natural Earth.

Parameters:

resolution ((str, optional)) – One of “low”, “medium” or “high”, or a named resolution from the Natrual Earth dataset.

property ax

The matplotlib Axes object of the subplot.

borders(*args, **kwargs)

Add country boundary polygons from Natural Earth.

Parameters:

resolution ((str, optional)) – One of “low”, “medium” or “high”, or a named resolution from the Natrual Earth dataset.

cities(density=None, labels=True, capital_cities=False, capital_cities_kwargs=None, medium_cities_kwargs=None, small_cities_kwargs=None, adjust_labels=False, **kwargs)

Add city markers to the map.

Parameters:

  • density (str or int, optional) – The resolution of the Natural Earth dataset to use. Can be one of “low”, “medium” or “high”.

  • labels (bool, optional) – Whether to add city names as labels. Default is True.

  • capital_cities (bool, optional) – Whether to include capital cities only. Default is False.

  • capital_cities_kwargs (dict, optional) – Keyword arguments to pass to the scatter method for capital cities.

  • medium_cities_kwargs (dict, optional) – Keyword arguments to pass to the scatter method for medium cities.

  • small_cities_kwargs (dict, optional) – Keyword arguments to pass to the scatter method for small cities.

  • adjust_labels (bool, optional) – Whether to adjust the positions of city labels to avoid overlap. Default is False. Note that this adjustment can be slow for large numbers of labels.

  • **kwargs – Additional keyword arguments to pass to the scatter method.

coastlines(*args, **kwargs)

Add country boundary polygons from Natural Earth.

Parameters:

resolution ((str, optional)) – One of “low”, “medium” or “high”, or a named resolution from the Natrual Earth dataset.

countries(*args, **kwargs)

Add country boundary polygons from Natural Earth.

Parameters:

resolution ((str, optional)) – One of “low”, “medium” or “high”, or a named resolution from the Natrual Earth dataset.

property crs

The CRS of the map.

property crs_name

The human-readable name of the CRS of the map.

disputed_boundaries(*args, **kwargs)

Add country boundary polygons from Natural Earth.

Parameters:

resolution ((str, optional)) – One of “low”, “medium” or “high”, or a named resolution from the Natrual Earth dataset.

property domain_name

The human-readable name of the domain of the map.

property fig

The matplotlib Figure object to which the subplot belongs.

grid_points(*args, **kwargs)

Plot gridpoint centroids on the map.

Parameters:

  • data (xarray.DataArray or earthkit.data.core.Base, optional) – The data source for which to plot grid_points.

  • x (str, optional) – The name of the x-coordinate variable in the data source.

  • y (str, optional) – The name of the y-coordinate variable in the data source.

  • **kwargs – Additional keyword arguments to pass to matplotlib.pyplot.scatter.

gridlines(*args, xstep=None, xref=0, ystep=None, yref=0, **kwargs)

Add gridlines to the map.

Parameters:

  • *args – Positional arguments to pass to cartopy.mpl.gridliner.Gridliner.

  • xstep (float, optional) – The step size for the x-axis gridlines. Default is None.

  • xref (float, optional) – The reference point for the xstep. Default is 0.

  • ystep (float, optional) – The step size for the y-axis gridlines. Default is None.

  • yref (float, optional) – The reference point for the ystep. Default is 0.

  • **kwargs – Additional keyword arguments to pass to cartopy.mpl.gridliner.Gridliner.

image(img, extent, origin='upper', transform=ccrs.PlateCarree())

Add an image to the map.

Parameters:

  • img (str or PIL.Image) – The image to add to the map.

  • extent (tuple) – The extent of the image in the form (xmin, xmax, ymin, ymax).

  • origin (str, optional) – The origin of the image. Default is “upper”.

  • transform (cartopy.crs.CRS, optional) – The CRS of the image. Default is PlateCarree (euirectangular).

labels(data=None, label=None, x=None, y=None, **kwargs)
land(*args, **kwargs)

Add country boundary polygons from Natural Earth.

Parameters:

resolution ((str, optional)) – One of “low”, “medium” or “high”, or a named resolution from the Natrual Earth dataset.

map_units(*args, **kwargs)

Add country boundary polygons from Natural Earth.

Parameters:

resolution ((str, optional)) – One of “low”, “medium” or “high”, or a named resolution from the Natrual Earth dataset.

natural_earth_layer(name, default_attribute='NAME_LONG', default_label='NAME_LONG', max_resolution='high', min_resolution='low', line=False)
natural_earth_resolution = 'medium'
ocean(*args, **kwargs)

Add country boundary polygons from Natural Earth.

Parameters:

resolution ((str, optional)) – One of “low”, “medium” or “high”, or a named resolution from the Natrual Earth dataset.

point_cloud(*args, **kwargs)

Plot a point cloud on the map.

Parameters:

  • data (xarray.DataArray or earthkit.data.core.Base, optional) – The data source for which to plot grid_points.

  • x (str, optional) – The name of the x-coordinate variable in the data source.

  • y (str, optional) – The name of the y-coordinate variable in the data source.

  • **kwargs – Additional keyword arguments to pass to matplotlib.pyplot.scatter.

shapes(shapes, *args, transform=ccrs.PlateCarree(), adjust_labels=False, labels=False, **kwargs)

Add shapes to the map.

Parameters:

  • shapes (str or cartopy.io.shapereader.Reader) – The shapes to add to the map. Can be a path to a shapefile or a cartopy Reader object.

  • *args – Positional arguments to pass to the add_geometries method.

  • transform (cartopy.crs.CRS, optional) – The CRS of the shapes. Default is PlateCarree.

  • adjust_labels (bool, optional) – Whether to adjust the positions of shape labels to avoid overlap. Default is False. Note that this adjustment can be slow for large numbers of labels.

  • labels (str, optional) – The attribute of the shapes to use as labels. Default is False.

  • **kwargs – Additional keyword arguments to pass to the add_geometries method.

standard_layers()

Add standard map layers to the map.

This method adds the following layers to the map: - land - coastlines - borders - gridlines

stock_img(*args, **kwargs)

Add the cartopy stock image to the map.

Parameters:

  • *args – Positional arguments to pass to the stock_img method.

  • **kwargs – Keyword arguments to pass to the stock_img method.

unit_boundaries(*args, **kwargs)

Add country boundary polygons from Natural Earth.

Parameters:

resolution ((str, optional)) – One of “low”, “medium” or “high”, or a named resolution from the Natrual Earth dataset.

urban_areas(*args, **kwargs)

Add country boundary polygons from Natural Earth.

Parameters:

resolution ((str, optional)) – One of “low”, “medium” or “high”, or a named resolution from the Natrual Earth dataset.