Skip to main content

2D map plots of data and NetCDF files using Cartopy

Project description

Build status License DOI

Map Plotter

Map Plotter is a toolkit that provides a framework for 2D map plots of data and NetCDF files. It consists of a python class (MapPlotter) that interfaces with cartopy to generate beautiful maps.

This tool depends on:

Two examples (example_MapPlotter_1.py and example_MapPlotter_2.py) are provided as a reference.

For any issues please contact: arnau.miro(at)upc(dot)edu.

Installation

A Makefile is provided within the tool to automate the installation for easiness of use for the user. To install the tool simply create a virtual environment as stated below or use the system Python. Once this is done simply type:

make

This will install all the requirements and install the package to your active python. To uninstall simply use

make uninstall

The previous operations can be done one step at a time using

make requirements

to install all the requirements and

make install

to install the tool.

Virtual environment

The package can be installed in a Python virtual environement to avoid messing with the system Python installation. Next, we will use Conda for this purpose. Assuming that Conda is already installed, we can create a virtual environment with a specific python version and name (my_env) using

conda create -n my_env python=3.8

The environment is placed in ~/.conda/envs/my_env. Next we activate it be able to install packages using conda itself or another Python package manager in the environment directory:

conda activate my_env

Then just follow the instructions as stated above.

Get cartopy

Cartopy can be installed using the pip tool by doing:

pip install cartopy

Sometimes a segmentation fault can appear when running some projections. In that case the following fixes the issue:

pip uninstall shapely
pip install --no-binary :all: shapely

Usage

The MAPPLOTTER class

Plot NETCDF data using CARTOPY. Example python snippets:

import MapPlotter as mp

# Define class instance
plotter = mp.MapPlotter(projection='PlateCarree')
params  = plotter.defaultParams() # Create basic parameters dictionary

# To plot already loaded fields
plotter.plot(lon,lat,data,params=params)

# To plot data from NetCDF data
plotter.plot_from_file(filename,varname,lonname,latname,iTime=0,iDepth=0,params=params)

# To see the data
plotter.save('outfile.png',dpi=300)
plotter.show() # wrapper of plt.show()

MAPPLOTER plot types

The following plotting functions are available:

  • Basic empty plot
def plot_empty(self,params=None,clear=True):
	'''
	Plot the map with all the settings and without data.

	Outputs:
		> Figure object
	'''
  • Main plotting function based on pcolormesh
def plot(self,lon,lat,data,params=None,clear=True,projection='PlateCarree',**kwargs):
	'''
	Main plotting function. Plots given the longitude, latitude and data.
	An optional params dictionary can be inputted to control the plot.

	Inputs:
		> lon:        Longitude vector or matrix
		> lat:        Latitude vector or matrix
		> data:       Data matrix
		> params:     (Optional) parameter dictionary
		> clear:      (Optional) Clear axes before plotting
		> Projection: Type of projection that the data is
						using (default assumes PlateCarree)

	Outputs:
		> Figure object
	'''
  • Plotting directly from NetCDF files
def plot_from_file(self,filename,varname,lonname,latname,iTime=0,iDepth=0,params=None,clear=True,projection='PlateCarree',**kwargs):
	'''
	Plot function. Plots data given a NetCDF file and the names of the variables
	as well as the current depth and time index.

	Inputs:
		> filename:   NetCDF file path
		> varname:    Name of the NetCDF variable to plot
		> lonname:    Name of the longitude dimension
		> latname:    Name of the latitude dimension
		> iTime:      Time index for NetCDF (default: 0)
		> iDepth:     Depth index for NetCDF (default: 0)
		> params:     (Optional) parameter dictionary
		> clear:      (Optional) Clear axes before plotting
		> Projection: Type of projection that the data is
						using (default assumes PlateCarree)

	Outputs:
		> Figure object
	'''
def plot_from_file_and_mask(self,filename,varname,maskfile,iTime=0,iDepth=0,
	masklon='glamt',masklat='gphit',params=None,clear=True):
	'''
	Plot function. Plots data given a NetCDF file, a mask file, the names of 
	the variables as well as the current depth and time index.

	Inputs:
		> filename:   NetCDF file path
		> varname:    Name of the NetCDF variable to plot
		> maskfile:   Path to the mask file
		> iTime:      Time index for NetCDF (default: 0)
		> iDepth:     Depth index for NetCDF (default: 0)
		> masklon:    Name of the longitude dimension (default: 'glamt')
		> masklat:    Name of the latitude dimension (default: 'gphit')
		> params:     (Optional) parameter dictionary
		> clear:      (Optional) Clear axes before plotting
		> Projection: Type of projection that the data is
						using (default assumes PlateCarree)

	Outputs:
		> Figure object		
	'''
  • Scatter plot
def scatter(self,xc,yc,data=np.array([]),params=None,clear=True,marker=None,size=None,projection='PlateCarree',**kwargs):
	'''
	Main plotting function. Plots given the longitude, latitude and data.
	An optional params dictionary can be inputted to control the plot.

	Inputs:
		> xc:     Scatter x points
		> yc:     Scatter y points
		> data:   Color data to be plotted
		> params: Optional parameter dictionary
		> clear:  Clear axes before plotting
		> marker: Marker for scatter plot
		> size:   Size for the scatter plot

	Outputs:
		> Figure object
	'''
  • Line plot (note that it does not allow to map it to a colormap)
def line(self,xc,yc,fmt='-',params=None,clear=True,size=None,projection='PlateCarree',**kwargs):
	'''
	Main plotting function. Plots given the longitude, latitude and data.
	An optional params dictionary can be inputted to control the plot.

	Inputs:
		> xc:     Scatter x points
		> yc:     Scatter y points
		> data:   Color data to be plotted
		> params: Optional parameter dictionary
		> clear:  Clear axes before plotting
		> marker: Marker for scatter plot
		> size:   Size for the scatter plot

	Outputs:
		> Figure object
	'''
  • Contour plot
def contour(self,lon,lat,data,levels=10,labelsize=None,linewidth=None,params=None,clear=True,projection='PlateCarree',**kwargs):
	'''
	Main plotting function. Plots given the longitude, latitude and data.
	An optional params dictionary can be inputted to control the plot.

	Inputs:
		> lon:        Longitude vector or matrix
		> lat:        Latitude vector or matrix
		> data:       Data matrix
		> levels:     Number and positions of the contour lines / regions
		> linewidth:  (Optional) The line width of the contour lines
		> labelsize:  (Optional) Label font size for contour plot
		> params:     (Optional) Parameter dictionary
		> clear:      (Optional) Clear axes before plotting
		> Projection: Type of projection that the data is
						using (default assumes PlateCarree)

	Outputs:
		> Figure object
	'''
  • Quiver plot
def quiver(self,xc,yc,uc,vc,dsample=1,data=None,params=None,clear=True,scale=None,color=None,projection='PlateCarree',**kwargs):
	'''
	Main plotting function. Plots given the longitude, latitude and data.
	An optional params dictionary can be inputted to control the plot.

	Inputs:
		> xc:      X position of the arrow
		> yc:      Y position of the arrow
		> uc:      U component for the quiver
		> yc:      V component for the quiver
		> dsample: Downsample (>1 to downsample, use integers)
		> data:    Color data to be plotted. If not provided the modulus is used
		> params:  Optional parameter dictionary
		> clear:   Clear axes before plotting
		> color:   Color to plot (dones not work when data is specified)

	Outputs:
		> Figure object
	'''

Parameters dictionary

The parameters dictionary includes the following modifiable variables.

Figure and axes handles

  • fig (default: None): store/give the figure handle
  • ax (default: None): store/give the axes handle

Figure and axes creation

  • size (default: (8,6)): figure size for creation
  • dpi (default: 100): figure dpi for creation
  • style (default: None): plot style according to matplotlib styles

Axes definition and parameters

  • xlim (default: [-180,180]): map limits in degrees of longitude
  • ylim (default: [-90,90]): map limits in degrees of latitude
  • max_div (default: 4): maximum number of divisions on the axes
  • axis_format (default: '.1f'): format of the latitude and logitude axis
  • top_label (default: False): activate/deactivate axes label on top
  • bottom_label (default: True): activate/deactivate axes label on bottom
  • right_label (default: False): activate/deactivate axes label on right
  • left_label (default: True): activate/deactivate axes label on left
  • grdstyle (default: {}): style for the plot grid
  • grdargs (default: {'draw_labels':True,'linewidth':0}): arguments for the grid style
  • features (default: ['coastline','continents','rivers','image']): features to be added on the plot. Available options are:
    • coastline: draw the lines of the coast
    • continents: draw the lines of the continents
    • rivers: draw the rivers
    • image: use an image as background
    • tilemap: use a tilemap as background
  • res (default: '50m'): resolution for the tilemap option
  • img (default: None): image to be loaded for the image option
  • img_format (default: 'png'): image format to be loaded for the image option
  • map_zoom (default: 9): zoom for the tilemap option
  • map_kind (default: {'tile':'GoogleTiles','arguments':{'style':'satellite'}}): options for the tilemap option

Title and labels

  • title (default: []): Plot title in the format of [title,kwargs]
  • xlabel (default: []): Plot longitude axis label in the format of [title,kwargs]
  • ylabel (default: []): Plot latitude axis label in the format of [title,kwargs]

Plot params

  • alpha (default: 1.): Transparency control

Colormap and colorbar

  • cmap (default: 'coolwarm'): colormap for the plot. Any value from matplotlib or cmocean are valid
  • ncol (default: 256): number of colors of the colorbar
  • draw_cbar (default: True): activate/deactivate the colorbar
  • orientation (default: 'horizontal'): colorbar orientation, either horizontal or vertical
  • extend (default: None): whether to extend the colorbar or not
  • shrink (default: 1.0): shrinking factor for the colorbar
  • aspect (default: 20.): aspect ratio for the colorbar
  • bounds (default: [-1e30, 1e30]): bounds, setting as [min,max]
  • numticks (default: 10): number of ticks for the colorbar
  • tick_format (default: '%.2f'): tick format for the colorbar
  • tick_font (default: None): specific font for the colorbar
  • label (default: {'label':'','weight':None,'style':None}): label and specifications for the colorbar

Command line tool

A command line tool is also provided so that maps can easily be generated from NetCDF files through the command prompt. It can be accessed as:

map_plotter [-h] -f FILE -v VAR [-m MASK] [--lon LON] [--lat LAT] 
			[-t TIME] [-d DEPTH] [-c CONF] -o OUT [--dpi DPI]

Arguments:

  • -h, --help show this help message and exit
  • -f FILE, --file FILE NetCDF file path
  • -v VAR, --var VAR Variable to plot
  • -m MASK, --mask MASK Mask file
  • --lon LON Longitude variable name (default: glamt)
  • --lat LAT Latitude variable name (default: gphit)
  • -t TIME, --time TIME Time index for NetCDF (default: 0)
  • -d DEPTH, --depth DEPTH Depth index for NetCDF (default: 0)
  • -c CONF, --conf CONF Configuration file path
  • -o OUT, --outfile OUT Output file name
  • --dpi DPI Output file DPI (default: 300)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mapplotter-2.2.0.tar.gz (55.6 kB view details)

Uploaded Source

Built Distribution

MapPlotter-2.2.0-py3-none-any.whl (37.5 kB view details)

Uploaded Python 3

File details

Details for the file mapplotter-2.2.0.tar.gz.

File metadata

  • Download URL: mapplotter-2.2.0.tar.gz
  • Upload date:
  • Size: 55.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.9.20

File hashes

Hashes for mapplotter-2.2.0.tar.gz
Algorithm Hash digest
SHA256 ad8db95d29cc9c85005c2cd2ee23f0e93ae3b62f190da201d074519ca246f0f9
MD5 79747a64e1f2a058883e95c73964f6e3
BLAKE2b-256 d9d50ef8e6396c2a0f6f9669a797ef7e868459bf346d9d6d47a56adca854b94a

See more details on using hashes here.

File details

Details for the file MapPlotter-2.2.0-py3-none-any.whl.

File metadata

  • Download URL: MapPlotter-2.2.0-py3-none-any.whl
  • Upload date:
  • Size: 37.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.9.20

File hashes

Hashes for MapPlotter-2.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 5f276e69ebda0fea5855ce15b9f5f8a4779d0b1bb671bec2724ad4a0786d97b9
MD5 ac2d79f61210f4829b3ce45fbefb0d22
BLAKE2b-256 6338eb89cd1708a903cba046a61db40daca3e2c3f610d5eadfe26edfd1fd40e5

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page