MapPlotter 2.2.0

2D map plots of data and NetCDF files using Cartopy

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:

• the PROJ library
• Cartopy
• the requests module

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)