zapata.mapping module

Contouring, stremlines and vector plots

Latitude-Longitude Plotting

A set of routines for horizontal plotting

xmap, xsmap, xstmap, vecmap

Zonal Plotting

These routine split zonal sections in pressures and latitude.

zonal_plot, zonal_stream_plot, ocean_section_plot

Utilities

choose_contour, add_colorbar, make_ticks, set_title_and_labels

Detailed Description:

zapata.mapping.init_figure(rows, cols, proview, constrained_layout=True, figsize=(16, 8), **kwargs)[source]

Initialization for the entire figure, choose projection and number of panels.

Parameters:

  • rows -- Number of rows in multiple picture

  • cols -- Number of columns in multiple picture

  • figsize -- Size of figure in inches (height, width)

  • proview -- Projection for the map

    • String:

      • "Pacific", cartopy PlateCarree, central longitude 180

      • "Atlantic", cartopy PlateCarree, central longitude 0

      • "NHStereoEurope", NH Stereo, central longitude 0

      • "NHStereoAmerica", NH Stereo, central longitude 90

      • "SHStereoAfrica", NH Stereo, central longitude 0

      • "RobPacific", Robinson, central longitude 180

      • "RobAtlantic", Robinson, central longitude 0

    • Dictionary:

      For projections requiring more parameters. The first element in the dictionary is the name of the projection followed by the parameters required

      • projection: 'Satellite':

        • centlon: Central Longitude

        • centlat: Central Latitude

        • height: Altitude of the view (m)

  • constrained_layout -- True/False

Returns:

  • fig (handle) -- Dictionary with matplotlib-like info on the plot

  • ax (axes) -- Axes of the panels

  • pro (projection) -- Projection chosen

zapata.mapping.choose_projection(proview)[source]

Auxiliary routine to select projection

Parameters:

proview -- Projection for the map

  • String:

    • "Pacific", cartopy PlateCarree, central longitude 180

    • "Atlantic", cartopy PlateCarree, central longitude 0

    • "NHStereoEurope", NH Stereo, central longitude 0

    • "NHStereoAmerica", NH Stereo, central longitude 90

    • "SHStereoAfrica", NH Stereo, central longitude 0

    • "RobPacific", Robinson, central longitude 180

    • "RobAtlantic", Robinson, central longitude 0

  • Dictionary:

    For projections requiring more parameters. The first element in the dictionary is the name of the projection followed by the parameters required

    • projection: 'Satellite':

      • centlon: Central Longitude

      • centlat: Central Latitude

      • height: Altitude of the view (m)

Returns:

Projection object

Return type:

projection

zapata.mapping.xmap(data, cont, prol, ax=None, fill=True, contour=True, data_cent_lon=180, clabel=True, c_format=' {:6.0f} ', lonlabel=None, latlabel=None, refline=None, title={}, title_style={}, xlimit=None, ylimit=None, cyclic=False, colorbar=False, cmap='coolwarm', coasts=True, color_land='lightgray', quiet=True, custom=False, label_style={})[source]

Mapping function based on cartopy and matplotlib.

The data is supposed to be on a Plate (lat-lon) projection and the central longitude can be defined via the paramater data_cent_lon. The defualt is data_cent_lon=180, meaning that the central longitude is over the pacific. Coordinates that go from 0 to 360 implicitly assume such a Pacific central longitude.

For the Pacific view it is assumed that the central longitude is at the daetline whereas for the Atlantic view the central longitude is at Greenwich.

The projection needs to be established in init_figure

Parameters:

  • field -- xarray -- cyclic point added in the routine

  • cont --

    • [cmin,cmax,cinc] fixed increment from cmin to cmax step cinc

    • [ c1,c2, ..., cn] fixed contours at [ c1,c2, ..., cn]

    • n n contours

    • [] automatic choice

  • prol -- Map Projection as initialized by init or it can be a string, one of the options in figinit

  • data_cent_lon -- Central longitude for the data projection

  • latlabel -- Position of Latitude grids

  • lonlabel -- Position of Longitude grids

  • ax -- Plot axis to be used

  • fill -- True/False flag to have filled contours or not

  • contour -- True/False flag to have contours or not

  • refline -- If a numeric value a single enhanced contour is plotted here

  • clabel -- True/False flag to have labelled contours or not

  • c_format -- Format for the contour labels

  • title (dict) -- Dictionary with the title and its subtitles

    • lefttitle -- Title string on the left

    • righttitle -- Title string on the right

    • maintitle -- Title string at the center

  • title_style (dict) -- Dictionary with the style for the title

  • label_style (dict) -- Dictionary with the style for the labels

  • cmap -- Colormap

  • cyclic -- True/False Add or not cylic longitude

  • coasts -- False/True Plotting or not empty coastlines

  • color_land -- if coasts=False, use color_land for land

  • xlimit -- Longitude limits of the map, if not set they are derived from the data. The projection used is the geographical projection pro

  • ylimit -- Latitude limits of the map, if not set they are derived from the data. The projection used is the geographical projection pro

  • quiet -- (False) Suppress all output

  • custom -- (False) Return a named tuple with full detail on the plot, including handles, gl etc...

Returns:

Dictionary with matplotlib-like info on the plot

Return type:

handle

zapata.mapping.zonal_plot(data, ax, cont, cmap, colorbar=True, title={}, title_style={}, label_style={}, refline=None)[source]

Zonal mapping function for xarray (lat,pressure).

Parameters:

  • data -- xarray -- cyclic point added in the routine (latitude, pressure)

  • cont --

    • [cmin,cmax,cinc] fixed increment from cmin to cmax step cinc

    • [ c1,c2, ..., cn] fixed contours at [ c1,c2, ..., cn]

    • n n contours

    • [] automatic choice

  • ax -- Plot axis to be used

  • title (dict) -- Dictionary with the title and its subtitles

    • lefttitle -- Title string on the left

    • righttitle -- Title string on the right

    • maintitle -- Title string at the center

  • title_style (dict) -- Dictionary with the style for the title

  • label_style (dict) -- Dictionary with the style for the labels

  • cmap -- Colormap

  • refline -- False/True if a zero line is desired

  • colorbar -- False/True if a colorbar is desired

Returns:

Dict with plot parameters

Return type:

handle

Examples

>>> zonal_plot(data,ax,[],'BYR',colorbar=True, titel={'maintitle': 'Title', 'lefttitle': None, 'righttitle':None},refline=None)
zapata.mapping.zonal_stream_plot(datau, datav, ax, C=None, lw=1, density=2, title={}, title_style={}, label_style={}, colorbar=False, cscale=None, cmap='coolwarm', norm=None, quiet=True)[source]

Plot zonal streamline for fielddatu e datav.

Parameters:

  • datau (xarray) -- X component of the streamlines

  • datav (xarray) -- Y component of the streamlines

  • C -- Color of the stremalines ('black'). If it is xarray color the streamlines with the colormap cmap

  • density -- Density of the streamlines

  • ax -- Plot axis to be used

  • title (dict) -- Dictionary with the title and its subtitles

    • lefttitle -- Title string on the left

    • righttitle -- Title string on the right

    • maintitle -- Title string at the center

  • title_style (dict) -- Dictionary with the style for the title

  • label_style (dict) -- Dictionary with the style for the labels

  • cmap -- Colormap

  • smooth -- False/True if smoothing is desired

  • colorbar -- False/True if a colorbar is desired

zapata.mapping.choose_contour(vmin, vmax, cont)[source]

Choose contours according to length of cont.

Parameters:

  • vmin -- Max Value of the field

  • vmax -- Min Value of the field

  • cont --

    • [cmin,cmax,cinc] fixed increment from cmin to cmax step cinc

    • [ c1,c2, ..., cn] fixed contours at [ c1,c2, ..., cn]

    • n n contours

    • [] automatic choice

Returns:

Levels of selected Contours

Return type:

contour_levels

Examples

>>> [0,1000,10] # Contours from 0 1000
>>> [0.01, 0.05, 1.0, 2.0, 5.0, 10.0] # Set Contours Leves
zapata.mapping.add_colorbar(fig, handle, ax, colorbar_size=0.05, label_size=10, edges=True)[source]

Add colorbar to plot.

Parameters:

  • handle -- Handle to plot

  • ax -- Axis to which to add the colorbar

  • colorbar_size -- Size of colorbar as a fraction of the axis

  • label_size -- Size of labels

  • edges -- Draw edges of the color bar

zapata.mapping.make_ticks(xt, dt=20, quiet=True)[source]

Calculates nice tickes for the axes. Selecting 20 or 10 intervals

Parameters:

  • xt -- Axes limit [west, east]

  • dt -- Tick spacing

Returns:

  • ticks -- Nice ticks position

  • quiet -- T/F get Output

zapata.mapping.set_titles_and_labels(ax, title_text, label_text, opt_title, opt_label)[source]

Utility function to handle axis titles, left/right aligned titles.

Parameters:

  • ax -- Current axes to the current figure

  • title_text (dict) -- Dictionary with the title and its subtitles

    • lefttitle -- Title string on the left

    • righttitle -- Title string on the right

    • maintitle -- Title string at the center

  • title_style (dict) -- Dictionary with the style for the title

  • label_text --

    • xlabel -- Label for the x axis

    • ylabel -- Label for the y axis

  • label_style (dict) -- Dictionary with the style for the labels

zapata.mapping.ocean_section_plot(data, ax, cont, cmap, colorbar=True, fill=True, contour=True, clabel=True, c_format=' {:4.0f} ', dxtick=20, dytick=10, title={}, title_style={}, label_style={}, xlimit=None, ylimit=None, refline=None, view='Atlantic')[source]

Ocean Section mapping function for xarray (lat,lon ,depth).

Parameters:

  • data -- xarray -- latitude or longitude, depth)

  • cont --

    • [cmin,cmax,cinc] fixed increment from cmin to cmax step cinc

    • [ c1,c2, ..., cn] fixed contours at [ c1,c2, ..., cn]

    • n n contours

    • [] automatic choice

  • ax -- Plot axis to be used

  • title (dict) -- Dictionary with the title and its subtitles

    • lefttitle -- Title string on the left

    • righttitle -- Title string on the right

    • maintitle -- Title string at the center

  • title_style (dict) -- Dictionary with the style for the title

  • label_style (dict) -- Dictionary with the style for the labels

  • cmap -- Colormap

  • refline -- False/True if a zero line is desired

  • colorbar -- False/True if a colorbar is desired

  • fill -- True/False flag to have filled contours or not

  • contour -- True/False flag to have contours or not

  • refline -- If a numeric value inlist form a single enhanced contour is pltted here

  • clabel -- True/False flag to have labelled contours or not

  • c_format -- Format for the contour labels

  • dxtick -- Tick interval for longitudes

  • dytick -- Tick interval for latitudes

  • xlimit -- x axis limits A Pacific view is obtained by giving limits in coordinae with the central longitude at Greenwich, e.g. (120,-120) will produce a shifted Pacific section

  • ylimit -- y axis limits

  • view -- Shift between Atlantic and Pacific views

Returns:

Dict with plot parameters

Return type:

handle

Examples

>>> ocean_zonal_plot(data,ax,[],'BYR',colorbar=True, maintitle=None, lefttitle=None, righttitle=None,refline=None)
zapata.mapping.small_map(fig, ax, cent_lon=0, lat=None, lon=None)[source]

Add small map for sections. The line is drawn at one lat or lon.

Parameters:

  • fig -- fig to add the small map

  • ax -- ax to used

  • cent_lon -- central longitude for longitude sections

  • lat ((None)) -- Latitude of the longitude section

  • lon ((None)) -- Longitude of the latitude section

zapata.mapping.adjust_data_centlon(data, centlon_old=0, centlon_new=180.0, roll_coords=False)[source]

Adjust xarray to a different central longitude. The data are rolled without rolling the coordinates.

Parameters:

  • data (xarray) -- xarray data to be shifed. it is assumed to have dimension lat and lon

  • centlon_old -- Original Central longitude of the data

  • centlon_new -- New central longitude of the data

Return type:

Rolled xarray

zapata.mapping.lon_sect(fig, ax, field, lon_sec, labelR=[], maintit=[], lmax=1000, xl=None, cmap='coolwarm', contour=True, levels=[], sharp=0.0, **kw)[source]

Latitude section at a fixed longitude.

This routine performs a section at the chosen longutude. The sharpness of he section is controlled by the parameter sharp. A sharp = 0 indicates a precise section at the nominal longitude, where any value different from zero will result in average on an interval of length 2*sharpness centered at the longitude.

Parameters:

  • fig -- Figure to be used

  • ax -- Plot axis to be used

  • field (xarray) -- Data to be plotted

  • lon_sec -- Longitude of the section

  • lmax -- Maximum depth of the section

  • xl -- Extent of the section

  • cmap -- colormap

  • contour -- True/false for having contours

  • levels -- Contour Levels ( see choose_contour)

  • sharp (positive float) -- Semi-width of the averaging interval around the section. The average ignore NaN and therefore small features can be lost in the averaging.

  • labelR -- Label ont he top roght of the plot

  • maintit -- Main title

Returns:

handle to the plot

Return type:

handle

zapata.mapping.lat_sect(fig, ax, field, lat_sec, labelR=[], view='Atlantic', maintit=[], lmax=1000, xl=None, cmap='coolwarm', contour=True, levels=[], sharp=[], **kw)[source]

Longitude section at a fixed latitude.

This routine performs a section at the chosen latitude. The sharpness of he section is controlled by the parameter sharp. A sharp = 0 indicates a precise section at the nominal latitude, where any value different from zero will result in average on an interval of length 2*sharpness centered at the latitude.

Parameters:

  • fig -- Figure to be used

  • ax -- Plot axis to be used

  • field (xarray) -- Data to be plotted

  • lon_sec -- Longitude of the section

  • lmax -- Maximum depth of the section

  • view --

    • Atlantic Atlantic at the center

    • Pacific Pacific at the center

  • xl -- Extent of the section

  • cmap -- colormap

  • contour -- True/false for having contours

  • levels -- Contour Levels ( see choose_contour)

  • sharp (positive float) -- Semi-width of the averaging interval around the section. The average ignore NaN and therefore small features can be lost in the averaging.

  • labelR -- Label on the top right of the plot

  • maintit -- Main title

Returns:

handle to the plot

Return type:

handle

zapata.mapping.changelabel(ax, fontsize=12, fontfamily='times', fontweight='normal')[source]

Change label properties globally for all labels, for a single ax or all axes in figure

Parameters:

  • ax -- axes of figure or single axes of panel

  • fontsize -- Fontsize

  • fontfamily -- FontFamily

  • fontweight -- FontWeight

Examples

>>> changelabel(ax,fontsize=12,fontfamily='times',fontweight='normal')
zapata.mapping.changebox(ax, choice, linewidth=2, color='black', capstyle='round')[source]

Change spines properties globally for all labels, for a single ax or all axes in figure.

Parameters:

  • ax -- axes of figure or single axes of panel

  • choice -- The spines to be modified, either all or top,`right`,`left`,`bottom` If it is not all it could be a list..

  • linewidth -- linewidth

  • color -- color

  • capstyle

Examples

>>> changebox(ax,'all',linewidth=2,color='black',capstyle='round')
>>> changebox(ax,['top','bottom'],linewidth=2,color='black',capstyle='round')
>>> changebox(ax,'left',linewidth=2,color='black',capstyle='round')
zapata.mapping.label_equator(ax, short=True)[source]

Change latitudinal labels to 'EQ in the middle'

zapata.mapping.zonal_streamfun_plot(datau, datav, ax, cont, color='black', refline=None, cmap='bwr', title={}, title_style={}, label_style={}, colorbar=True, smooth=True, special_value=9999)[source]

Zonal streamfunction.

Plot meridional streamfunction for field datu e datav.

Parameters:

  • datau (xarray) -- X component of the streamlines

  • datav (xarray) -- Y component of the streamlines

  • ax -- Plot axis to be used

  • title (dict) -- Dictionary with the title and its subtitles

    • lefttitle -- Title string on the left

    • righttitle -- Title string on the right

    • maintitle -- Title string at the center

  • title_style (dict) -- Dictionary with the style for the title

  • label_style (dict) -- Dictionary with the style for the labels

  • cmap -- Colormap

  • smooth -- False/True if smoothing is desired

  • colorbar -- False/True if a colorbar is desired

zapata.mapping.add_cyclic_lon(data)[source]

Adding a cyclic longitude to an xarray (corrected error on data.lon[0])

Parameters:

data (xarray)

Returns:

Data with cyclic coordinate added

Return type:

xarray

zapata.mapping.xstmap(U, V, color='black', pro=None, ax=None, data_cent_lon=180, cyclic=True, coasts=True, lw=1, density=2, title=None, title_style=None, label_style=None, lonlabel=None, latlabel=None, xlimit=None, ylimit=None, colorbar=False, cscale=None, cmap='coolwarm', norm=None, quiet=True)[source]

Plot streamline for field U and V.

This routine draws streamlines for the fields U,V, optionally colored with the field color. Internally assume data is always on a latlon projection with central longitude at Greenwich.

The data is supposed to be on a Plate (lat-lon) projection and the central longitude can be defined via the paramater data_cent_lon. The defualt is data_cent_lon=180, meaning that the central longitude is over the pacific. Coordinates that go from 0 to 360 implicitly assume such a Pacific central longitude.

For the Pacific view it is assumed that the central longitude is at the dateline whereas for the Atlantic view the central longitude is at Greenwich.

Parameters:

  • U (xarray) -- X component of the streamlines

  • V (xarray) -- Y component of the streamlines

  • color -- Color of the stremalines ('black'). If it is xarray color the streamlines with the colormap cmap

  • cscale -- Optionally, if an array is used in color, it normalize to cscale = ( min, max) If omitted, (min,max) is computed from the array

  • lw (float or array) -- Linewidth, if a numpy array it is varying with the array values

  • data_cent_lon -- Central longitude for the data projection

  • latlabel -- Position of Latitude grids

  • lonlabel -- Position of Longitude grids

  • density -- Density of the streamlines

  • ax -- Plot axis to be used

  • title (dict) -- Dictionary with the title and its subtitles

    • lefttitle -- Title string on the left

    • righttitle -- Title string on the right

    • maintitle -- Title string at the center

  • title_style (dict) -- Dictionary with the style for the title

  • label_style (dict) -- Dictionary with the style for the labels

  • cmap -- Colormap

  • colorbar -- False/True

  • xlimit -- Limit of the map (lon)

  • ylimit -- Limit of the map (lat)

Returns:

Dictionary with matplotlib-like info on the plot

Return type:

handle

zapata.mapping.vecmap(U, V, C, color='black', pro=None, ax=None, data_cent_lon=0, cyclic=True, coasts=True, veckey=None, vec_min=0.0, stride=10, title=None, title_style=None, label_style=None, lonlabel=None, latlabel=None, xlimit=None, ylimit=None, colorbar=False, cscale=None, cmap='coolwarm', norm=None, quiet=True, **kw)[source]

Vector plot for field U and V.

This routine draws vectors for the fields U,V, optionally colored with the field color. Internally assume data is always on a latlon projection with central longitude at Greenwich.

Data must be on a (0,360) longitude coordinate referred to Greenwich, but the xlimit are referred to the projection chosen in init.

For the Pacific view it is assumed that the central longitude is at the dateline whereas for the Atlantic view the central longitude is at Greenwich.

It also takes all the other arguments for quiver

Parameters:

  • U (xarray) -- X component of the vectors

  • V (xarray) -- Y component of the vectors

  • C (xarray) -- Field to scale the vectors. If it is xarray color the streamlines with the colormap cmap

  • pro -- Projection

  • ax -- ax to plot

  • color -- Color of the stremalines ('black').

  • cscale -- Optionally, if an array is used in color, it normalize to cscale = ( min, max) If omitted, (min,max) is computed from the array

  • data_cent_lon -- Central longitude for the data projection

  • veckey --

    It is a dictionary for the reference vector, the values are

    • X, Y -- Location in figure coordinates

    • U -- Reference Unit Length

    • label -- Reference string, it can be a latex string, i.e r'$1 frac{m}{s}$'

  • vec_min -- Minimum value to represent with the vectors

  • latlabel -- Position of Latitude grids

  • lonlabel -- Position of Longitude grids

  • title (dict) -- Dictionary with the title and its subtitles

    • lefttitle -- Title string on the left

    • righttitle -- Title string on the right

    • maintitle -- Title string at the center

  • title_style (dict) -- Dictionary with the style for the title

  • label_style (dict) -- Dictionary with the style for the labels

  • cmap -- Colormap

  • colorbar -- False/True

  • xlimit -- Limit of the map (lon)

  • ylimit -- Limit of the map (lat)

Returns:

Dictionary with matplotlib-like info on the plot

Return type:

handle