gridutils module

class gridtools.gridutils.GridUtils(app={})

Bases: object

addDataSource(dataSource, delete=False)

Add a data source to the catalog. See: datasource.addDataSource()

addMessage(msg)

Append new message to message buffer.

adjustExternalLoggers()

This adjusts some noisy loggers from other python modules.

app()

By calling this function, the user is requesting the application functionality of GridUtils(). return the dashboard, but GridUtils() also has an internal pointer to the application.

application(app={})

Convienence function to attach application items to GridUtils() so it can update certain portions of the application:

app = {
    'messages': panel.widget.TextBox     # Generally a pointer to a panel widget for display of text
    'defaultFigureSize': (8,6)           # Default figure size to return from matplotlib
    'usePaneMatplotlib': True/False      # Instructs GridUtils to use panel.pane.Matplotlib for plot objects
}
applyEvalMap(dsName, dsData)

Apply constructed equations through python eval() to manipulate data source fields. Data source catalog entries must be prefixed with ds:. If GEBCO is defined as a data source in the catalog, use: ds:GEBCO. All catalog entries start with a slash.

applyExistingLandmask(dsData, dsVariable, maskFile, maskVariable, **kwargs)

This modifies a given bathymetry using an existing land mask. See applyExistingLandmask().

applyExistingOceanmask(dsData, dsVariable, maskFile, maskVariable, **kwargs)

This modifies a given bathymetry using an existing ocean mask. See applyExistingOceanmask().

cart2pol(x, y, z)

Transform a point on globe from Cartesian (x,y,z) to polar coordinates.

checkAvailableVariables(dsData, varList)

Check for available variables in a data source. If any variable is missing, issue a warning and return False. If all variables are available, return True.

checkGridMetadata(kwargs, varKey, defaultValue, append=False)

Update or overwrite global metadata values based on keyword arguments.

Keyword arguments

  • append (boolean) – Updated metadata is appended to any existing metadata. If the attribute does not exist, it is added.

clearGrid()

Call this when you want to erase the current grid. This also clobbers any current grid and plot parameters. Do not call this method between plots of the same grid in different projections.

clearGridParameters()

Clear grid parameters. This does not erase any grid data.

clearMessage()

This clears the message buffer of messages.

closeGrid()

Closes and open dataset file pointer.

computeBathymetricRoughness(dsName, **kwargs)

This generates h2 and other fields. See: gridtools.bathyutils.computeBathymetricRoughness()

computeGridMetricsCartesian()

Compute MOM6 grid metrics: angle_dx, dx, dy and area for a grid in cartesian coordinates.

computeGridMetricsSpherical(**kwargs)

Compute MOM6 grid metrics: angle_dx, dx, dy and area for a grid in spherical coordinates.

Keyword arguments

  • history (string) – optional message to append to the global history attribute. A default message is provided if one is not specified.

convertGrid(target, **kwargs)

Convert current grid to another grid type.

Parameters

target (string) – name of new grid format

Returns

none

Return type

none

Supported grid conversions:

SOURCE

TARGET

CODE CITATIONS

ROMS

MOM6

convert_ROMS_grid_to_MOM6.py [IAH20]

Keyword arguments:

  • writeTopography (boolean) – set True to write topographic grid to a file. Default: False

  • topographyFilename (string) – filename used to write topographic grid. Default: “ocean_topog.nc”

  • writeMosaic (boolean) – set True to write the mosaic file. Default: False

  • mosaicFilename (string) – filename for mosaic file. Default: “ocean_mosaic.nc”

  • oceanGridFilename (string) – filename for ocean grid file. Default: “ocean_hgrid.nc”

  • writeLandmask (boolean) – set True to write land mask file. Default: False

  • landmaskFilename (string) – filename used to write the land mask. Default: “land_mask.nc”

  • writeOceanmask (boolean) – set True to write ocean mask file. Default: False

  • oceanmaskFilename (string) – filename used to write the ocean mask. Default: “ocean_mask.nc”

  • tileName (string) – name to assign to the solo tile. Default: “tile1”

  • MINIMUM_DEPTH (float) – minimum depth of ocean in meters. Default: 0.0

  • MASKING_DEPTH (float) – masking depth of ocean in meters. Default: 0.0

  • MAXIMUM_DEPTH (float) – maximum depth of ocean in meters. Default: -99999.0

  • writeCouplerMosaic (boolean) – set False to skip creation of coupler mosaic file. Default: False

  • couplerMosaicFilename (string) – set False to skip creation of coupler mosaic file. Default: “mosaic.nc”

  • writeExchangeGrids (boolean) – set False to skip creation of exchange grids. Default: False

  • overwrite (boolean) – set True to overwrite existing files. Default: False

  • inputDirectory (string) – absolute or relative path to write model input files. Default: “INPUT”

  • relativeToINPUTDir (string) – absolute or relative path for mosaic files to the INPUT directory. Default: “./”

Keyword arguments (ROMS):

  • topographyVariable (string) – grid name for ROMS topography containing depths. Some ROMS grids also contain a hraw which might be useful. Default: h

Note

In the original ROMS to MOM6 conversion script, any land mask points are masked to a depth of zero(0). This version sets the depth to the MASKING_DEPTH. If the mask or clamping depth is known from the ROMS grid, please set MASKING_DEPTH appropriately or the land mask depths will be set to zero(0) which is the default.

convertToMathExpression(sourceExpression)

Convert a source expression to a python expression for evaluation.

Ex: “-[elevation]” => “-dsData[‘elevation’]”

debugMsg(msg, level=- 1)

This function has a specific purpose to aid in debugging and activating pdb breakpoints. NOTE: pdb breakpoints tend not to work very well when running under the gridtools application. It tends to terminate the bokeh/tornado server.

The debug level can be zero(0) and you can forcibly add a break point in the code by using debugMsg(msg, level=3) anywhere in the code.

Note

Currently defined debug levels:

0=off 1=log debugging messages 2=raise an exception 3=stop with a pdb breakpoint after logging message

deleteGridParameters(gList, subKey=None)

This deletes a given list of grid parameters.

deleteLogfile(logFilename)

Delete a log file. Logging must be off.

deletePlotParameters(pList, subKey=None)

This deletes a given list of plot parameters.

detachLoggingFromApplication()

Detach logging from application so messages are shown in the script and/or jupyter.

disableLogging()

Disable logging of messages to a file

enableLogging(logFilename)

Enable logging of messages to a file

extendGrid(jStart, jEnd, iStart, iEnd, gridMethod='auto', gridProj='auto')

Extend the current grid by jStart, jEnd, iStart, iEnd points using the specified method. The grid can be extended using ‘spherical’ space or ‘latlon’ space. If the method is ‘auto’, the routine tries to determine which to use. The grid is extended in all directions using the maximum of provided parameters and then clipped to the proper dimensions. Grids extended using ‘spherical’ space require the projection used when the grid was created to perform forward and reverse transformation of coordinates.

This function assumes an existing grid is present and that the variables x and y are longitude and latitude.

This function returns the extended grid.

Note

Since MOM6 grids are defined with a supergrid, to extend the regular grid one point in all directions, this routine should specify to extend the grid two points in all directions.

Grid Extension Technique:

This description shows the extension of a grid by one point.  This
also applies to any requested grid size.

Process

# Original grid (o); Points to fill (.)
#  . . . . .
#  . o o o .
#  . o o o .
#  . o o o .
#  . . . . .

# Step 1: Extend grid along j-direction
# New points shown by (A)
#  . . . . .
#  A o o o A
#  A o o o A
#  A o o o A
#  . . . . .
#

# Step 2: Extend grid along the i-direction
# New points shown by (B)
#  B B B B B
#  A o o o A
#  A o o o A
#  A o o o A
#  B B B B B

# Step 3: Clip grid back to requested size
# given by iStart, iEnd, jStart, jEnd.

# To prepend one column of points,
# please specify extendGrid(0,0,1,0).
# The grid returned should look like:
#  A o o o
#  A o o o
#  A o o o

# To prepend one column of points and
# append a row of points to the end,
# please specify extendGrid(0,1,1,0).
# The grid returned should look like:
#  B B B B
#  A o o o
#  A o o o
#  A o o o
extendGridDetectMethod()

This function looks at the grid metadata and searches for hints to see how the grid should be extended.

Sources probed for information:

  • Global attribute: projection

  • Variable ‘tile’ attribute: geometry

extendGridLatLon(inputGrid, maxIncrease)

This uniformly extends the input grid by maxIncrease points using latitude and longitude coordinates in degrees.

To increase the grid size we need maxIncrease points on either size (twice as big).

extendGridSpherical(inputGrid, maxIncrease, gridProj)

This uniformly extends the input grid by maxIncrease points using spherical coordinates in meters. This function requires a grid projection to accurately perform the forward and reverse transformation of grid points.

To increase the grid size we need maxIncrease points on either size (twice as big).

filterLogMessages(record)

This may not be needed after all.

findLineFromPoints(ptsY, ptsX, nY, nX)

Find the extension points at the end of given set of points. This routine assumes a nearly linear regularly spaced array of points is provided.

Returned are the new points on the given line.

([y1, y2], [x1, x2]) where (y1, x1) is the head of the line and (y2, x2) is the tail of the line.

NOTE: Number of points to extend should be the same nY = nX. If the points are not regularly spaced, extension of a line with a large number of points is not going to work very well.

formProjString(param)

Create a projection string from parameter attributes.

generateGridByRefinement(dsName, **kwargs)

Generates a grid from a data source using refinement regridding.

generate_latlon_mesh_centered(lni, lnj, llon0, llen_lon, llat0, llen_lat, **kwargs)

Generate a regular lat-lon grid

generate_regional_mercator(cUnits, cX, cY, dx, dxU, dy, dyU, tilt, grX, grXU, grY, grYU, pD, **kwargs)

Generate a regional mercator grid centered at (cX, cY) with spans of (dx, dy) with resolution (grX, grY) and tilted by angle tilt

generate_regional_spherical(lon0, lon_span, lat0, lat_span, tilt, gRes, gMode)

Generate a regional grid centered at (lon0,lat0) with spans of (lon_span,lat_span) and tilted by angle tilt

generate_regional_spherical_degrees(cUnits, cX, cY, dx, dxU, dy, dyU, tilt, grX, grXU, grY, grYU, pD, **kwargs)

Create a grid in the spherical projection using grid distances in degrees.

generate_regional_spherical_meters(cUnits, cX, cY, dx, dxU, dy, dyU, tilt, grX, grXU, grY, grYU, pD, **kwargs)

Create a grid in the spherical projection using grid distances in meters.

This function uses code that performs projection transformation of 2D grids. [Dus20]

generate_rotated_grid(lon0, lon_span, lat0, lat_span, tilt, refine)
getDebugLevel()

Get the current debug level for GridUtils(). See setDebugLevel() for available levels.

getGridParameter(gkey, subKey=None, default=None, inform=True)

Return the requested grid parameter or the default if none is available. The routine will emit a message by default. Use inform=False to suppress messages emitted by this function.

getLogLevel()

Get the current debug level for GridUtils(). See setLogLevel() for available levels.

getPlotParameter(pkey, subKey=None, default=None, inform=True)

Return the requested plot parameter or the default if none is available.

To access dictionary values in projection, use the subKey argument.

This function will emit an informational message when a default parameter is being used. Use inform=False to suppress the messages.

getRadius(param)

Return a radius based on projection string. If parsing the projection string fails, the radius from GRS80/WGS84 is used.

getVerboseLevel()

Get the current verbose level for GridUtils()

getVersion()

Return the version number of this library

getXYDist(x1, y1, x2, y2)

Compute distance between two points in x/y space.

ice9(**kwargs)

This calls the ice-9 algorithm from bathyutils. See: gridtools.bathyutils.ice9()

isAvailable(utilName)

Check the availablilty of a runnable executable in the system PATH. Returns True if an executable appears to be available in the system PATH. Otherwise, return False.

makeGrid(setFilename=None)

Using supplied grid parameters, populate a grid in memory.

makeSoloMosaic(**kwargs)

This replicates some of the processes of make_solo_mosaic from [GeophysicalFDLGFDLMSGroup21]. This routine is also based on code from [IAH20].

A grid must be created or read. This function has the following keyword arguments and default values. This is a MOM6 specific function to write out various files depending on arguments passed.

Keyword arguments:

  • topographyGrid (xarray) – topographic grid to be used with the model grid. REQUIRED. Default: None

  • topographyFilename (string) – filename used to write topographic grid. Default: “ocean_topog.nc”

  • mosaicFilename (string) – filename for mosaic file. Default: “ocean_mosaic.nc”

  • oceanGridFilename (string) – filename for ocean grid file. Default: “ocean_hgrid.nc”

  • writeLandmask (boolean) – set True to write land mask file. Default: False

  • landmaskFilename (string) – filename used to write the land mask. Default: “land_mask.nc”

  • writeOceanmask (boolean) – set True to write ocean mask file. Default: False

  • oceanmaskFilename (string) – filename used to write the ocean mask. Default: “ocean_mask.nc”

  • tileName (string) – name to assign to the solo tile. Default: “tile1”

  • MINIMUM_DEPTH (float) – minimum depth of ocean in meters. Default: 0.0

  • MASKING_DEPTH (float) – masking depth of ocean in meters. Default: 0.0

  • MAXIMUM_DEPTH (float) – maximum depth of ocean in meters. Default: -99999.0

  • writeCouplerMosaic (boolean) – set False to skip creation of coupler mosaic file. Default: True

  • couplerMosaicFilename (string) – set False to skip creation of coupler mosaic file. Default: “mosaic.nc”

  • writeExchangeGrids (boolean) – set False to skip creation of exchange grids. Default: True

  • overwrite (boolean) – set True to overwrite existing files. Default: False

  • inputDirectory (string) – absolute or relative path to write model input files. Default: “INPUT”

  • relativeToINPUTDir (string) – absolute or relative path for mosaic files to the INPUT directory. Default: “./”

Note

Integers stored in the mosaic tiles must be 32 bit integers. If 64 bit integers are used, the FMS coupler will die with invalid netcdf variable type. Using the defaults, this routine will write the following files to the INPUT directory with one tile named tile1:

  • mosaic.nc

  • ocean_mosaic.nc

  • ocean_topog.nc

  • atmos_mosaic_tile1Xland_mosaic_tile1.nc

  • atmos_mosaic_tile1Xocean_mosaic_tile1.nc

  • land_mosaic_tile1Xocean_mosaic_tile1.nc

If any of these files exist, the file will NOT be replaced and a warning will be issued.

For oceanGridFile, if the filename is not provided, the routine will attempt to use the name provided when the grid was read. The filename may need to be set if the grid was just constructed using the library.

mesh_plot(lon, lat, lon0=0.0, lat0=90.0)

Plot a given mesh with a perspective centered at (lon0,lat0)

newFigure(figsize=None, dpi=None)

Establish a new matplotlib figure.

openDataset(dsName, **kwargs)

Open a dataset using the data source catalog or url that can point to a raw dataset using a prefix file: in the data source name. The url can be an OpenDAP dataset: e.g. https://opendap.jpl.nasa.gov/opendap/allData/ghrsst/data/L4/GLOB/NCDC/AVHRR_AMSR_OI/2011/001/20110101-NCDC-L4LRblend-GLOB-v01-fv02_0-AVHRR_AMSR_OI.nc.bz2

Keyword arguments

  • chunks (int, tuple of int or mapping of hashable to int) – xarray chunk description.

  • gridid (ROMS model grid ID) – Model grid identification using the gridid.txt file. The environment variable ROMS_GRIDID_FILE must be set.

openGrid(inputUrl, **kwargs)

Open a grid file. This creates and open file pointer which is local to the gridtools object.

Specify with file: or OpenDAP (http://, https://) or ds:.

To access the opened grid, use: obj.xrDS. This grid now needs to be formally read by readGrid() and the grid will be available to obj.grid and obj.nativeGrid.

plotGrid(**kwargs)

Perform a plot operation. This function supports plotting a variable from a data source or the model grid that was loaded or created. A plot may contain both.

Returns

Returns a tuple of matplotlib objects (figure, axes)

Return type

tuple

In general, a projection is necessary to plot a variable or model grid.

Example

>>> grd = gridUtils()
>>> grd.setPlotParameters(
        {
            ...other grid options...,
            'projection': {
                'name': 'Mercator',
                ...other projection options...,
            },
        })
>>> grd.plotGrid()

Keyword arguments:

  • showModelGrid (boolean) – set False to hide the model grid. Default: True

  • plotVariables (dict()) – one or more variables and plot parameters. Default: None

  • showGridPoints (list()) – list of grid points to show on the plot. The list contains tuples of (j,i), (j,i,c) or (j,i,c,s). The default color (c) is red with a size (s) of 5. To change just the size of the point, the color must also be specified. NOTE: For MOM6 grids, the (j,i) refer to points on the supergrid. Points on the regular grid should be multiples of two.

Keyword arguments for plotVariables:

  • vals (xarray) – one dataset, variable or grid of information.

  • cmap (str or Colormap) – A Colormap instance or registered colormap name. Default: rcParams["image.cmap"] or viridis

  • norm (Normalize) – A Normalize instance. Default: The data range is mapped to the colorbar range using linear scaling.

  • levels (list()) – Discrete levels for plotting. Default: None

  • cbar_kwargs (dict()) – Keyword arguments that are applied to the colorbar. See: matplotlib.figure.Figure.colorbar() Default: dict()

Useful information on plot shading for grid cell or centered over a grid point. Useful example for adjusting the colorbar and using a different colormap.

pol2cart(lam, phi)

Transform a point on globe from Polar (lam,phi) to Cartesian coordinates.

printMsg(msg, level=20)

The verboseLevel and msgLogLevel can be set separately to any level. If this is attached to a panel application with a message box, the output is sent to that object. Messages omitting the level argument will default to INFO.

readGrid(**kwargs)

Read a grid. This is more of a convenience function for applications that need to pass grids to gridtools instead of using the openGrid function.

This can be generalized to work with “other” grids if we desired? (ROMS, HyCOM, etc). This routine does not verify the read grid vs. type of grid specified.

Note

A copy of the native grid native structure can be found by using obj.nativeGrid. The obj.grid variable may be modified by the gridtools library.

regridTopo(dsData, gridGeoLoc='corner', topoVarName='elevation', coarsenInt=10, method='conservative', superGrid=True, periodic=True, gridDimX=None, gridDimY=None, gridLatName=None, gridLonName=None, topoDimX=None, topoDimY=None, topoLatName=None, topoLonName=None, convert_to_depth=True)

Generate a bathymetry and ocean mask for a given data source topography or bathymetry. See gridtools.topoutils.TopoUtils.regridTopo().

removeFillValueAttributes(data=None, stringVars=None)

Helper function to format the netCDF file to emulate the current styles.

Parameters
  • data (xarray) – variables to format

  • stringVars (dict()) – dictionary of string variables and lengths

Returns

netCDF encoding

Return type

dict()

For data, the _FillValue is masked.

For stringVars, supply a string length. e.g. {'tile': 255} This will result in an encoding of {'dtype': 'S255', 'char_dim_name': 'string'}.

resetPlotParameters()

Resets plot parameters for a grid.

rotate_u(x, y, z, ux, uy, uz, theta)

Rotate by angle \(\theta\) around a general axis (ux,uy,uz).

rotate_u_mesh(lam, phi, ux, uy, uz, theta)
rotate_x(x, y, z, theta)

Rotate vector (x,y,z) by angle theta around x axis.

rotate_x_mesh(lam, phi, theta)

Rotate the whole mesh on globe by angle theta around x axis (passing through equator and prime meridian.).

rotate_y(x, y, z, theta)

Rotate vector (x,y,z) by angle theta around y axis.

rotate_y_mesh(lam, phi, theta)

Rotate the whole mesh on globe by angle theta around y axis (passing through equator and prime meridian+90.).

rotate_z(x, y, z, theta)

Rotate vector (x,y,z) by angle theta around z axis.

rotate_z_mesh(lam, phi, theta)

Rotate the whole mesh on globe by angle theta around z axis (globe polar axis).

saveDataset(dsName, dsData, **kwargs)

This allows saving variables to a file.

Parameters
  • dsName (string) – data source name or filename

  • dsData (xarray object) – dataset, data array or data object

Returns

none

Return type

none

Keyword arguments

  • overwrite (boolean) – set to True to allow overwriting. Default: False

  • hashVariables (list()) – names of variables to add a sha256sum attribute

  • mapVariables (dict()) – map variable names to names stored in the output file. This argument takes precidence over all arguments.

Note

(Unimplemented) If the dsName is a data source (ds:) any variable map specified will be reversed before writing the final file.

saveGrid(filename=None, directory=None, enc=None)

This operation is destructive using the last known filename which can be overridden.

setDebugLevel(newLevel)

Set a new debug level.

Parameters

newLevel (integer) – debug level to set or update

Returns

none

Return type

none

Note

Areas of code that typically cause errors have try/except blocks. Some of these have python debugging breakpoints that are active when the debug level is set to a positive number.

Currently defined debug levels:

0=off 1=extra messages 2=raise an exception 3=stop at breakpoints

setGridParameters(gridParameters, subKey=None)

Generic method for setting gridding parameters using dictionary arguments.

Parameters
  • gridParameters (dictionary) – grid parameters to set or update

  • subKey (string) – an entry in gridParameters that contains a dictionary of information to set or update

Returns

none

Return type

none

Note

Core gridParameter list. See other grid functions for other potential options. Defaults are bold. See the user manual for more details.

Primary keys

  • centerUnits (string) – Grid center point units [‘degrees’, ‘meters’]

  • centerX (float) – Grid center in the j direction

  • centerY (float) – Grid center in the i direction

  • dx (float) – grid length in the j direction

  • dy (float) – grid length in the i direction

  • dxUnits (string) – grid length units [‘degrees’, ‘meters’]

  • dyUnits (string) – grid length units [‘degrees’, ‘meters’]

  • nx (integer) – number of grid points along the j direction

  • ny (integer) – number of grid points along the i direction

  • tilt (float) – degrees to rotate the grid (LambertConformalConic only)

  • gridResolution (float) – grid cell size in i and j direction

  • gridResolutionX (float) – grid cell size in the j direction

  • gridResolutionY (float) – grid cell size in the i direction

  • gridResoultionUnits (string) – grid cell units in the i and j direction [‘degrees’, ‘meters’]

  • gridResoultionXUnits (string) – grid cell units in the j direction [‘degrees’, ‘meters’]

  • gridResoultionYUnits (string) – grid cell units in the i direction [‘degrees’, ‘meters’]

subKey ‘projection’

  • name (string) – Grid projection [‘LambertConformalConic’,’Mercator’,’Stereographic’]

  • lat_0 (float degrees) – Latitude of projection center [0.0]

  • lat_1 (float degrees) – First standard parallel (latitude) [0.0]

  • lat_2 (float degrees) – Second standard parallel (latitude) [0.0]

  • lat_ts (float degrees) – Latitude of true scale. Defines the latitude where scale is not distorted. Takes precedence over k_0 if both options are used together. For stereographic, if not set, will default to lat_0.

  • lon_0 (float degrees) – Longitude of projection center [0.0]

  • ellps (string) – See proj -le for a list of available ellipsoids [‘GRS80’]

  • R’ (float meters) – Radius of the sphere given in meters. If both R and ellps are given, R takes precedence.

  • x_0 (float meters) – False easting [0.0]

  • y_0 (float meters) – False northing [0.0]

  • k_0 (float) – Depending on projection, this value determines the scale factor for natural origin or the ellipsoid [1.0]

The subkey ‘projection’ mostly follows proj.org terminology for any giving projection. See: Lambert Conformal Conic, Mercator and Stereographic for more details.

MOM6 specific options
  • gridMode (integer) – 2 = supergrid(*); 1 = actual grid [1 or 2]

Warning

These options are similar to setPlotParameters() which control how this grid or other information is plotted. For instance, the grid projection and the plot projection can be in different projections.

setLogLevel(newLevel)

Set a new logging level.

Parameters

newLevel (integer or string) – logging level to set or update

Returns

none

Return type

none

Note

Setting this to a positive number will increase the feedback from this module.

The available levels are:

Level

Numeric value

CRITICAL

50

ERROR

40

WARNING

30

INFO

20

DEBUG

10

setPlotCMap(varArgs)

Set user defined color map or use matplotlib default.

setPlotCbarkwargs(varArgs)
setPlotLevels(varArgs)
setPlotNorm(varArgs)
setPlotParameters(plotParameters, subKey=None)

A generic method for setting plotting parameters using dictionary arguments. These parameters are applied to plots using the grid or any requested field. The grid projection may be different than the requested plot projection.

Parameters
  • plotParameters (dictionary) – plot parameters to set or update

  • subkey – an entry in plotParameters that contains a dictionary of information to set or update

Returns

none

Return type

none

Note

Plot parameters persist for as long as the python GridUtils object exists.

See the user manual for additional details.

Primary keys

  • figsize ((float inches, float inches)) – matplotlib figure size (width, height) Default: (5.0, 3.75)

  • extent ([x0, x1, y0, y1]) – map extent of given coordinate system (see extentCRS) If no extent is given, [], then the global extent, set_global(), is used. See matplotlib geoaxes. Default: []

  • extentCRS (cartopy.crs method) – cartopy crs You must have the cartopy.crs module loaded to change this setting. See Cartopy projection list. Default: cartopy.crs.PlateCarree()

  • showGrid (boolean) – show the grid outline. Default: True

  • showGridCells (boolean) – show the grid cells. Default: False

  • showSupergrid (boolean) – show the MOM6 supergrid cells. Default: False

  • title (string) – set plot title. Default: None

  • iColor (string) – matplotlib color for i vertices. Default: ‘k’ (black)

  • jColor (string) – matplotlib color for j vertices. Default: ‘k’ (black)

  • iLinewidth (float points) – matplotlib linewidth for i vertices. Default: 1.0

  • jLinewidth (float points) – matplotlib linewidth for j vertices. Default: 1.0

Line width in matplotlib is generally defined by a numerical value over the default dots per inch (dpi). The nominal dpi value is 72 dots per inch. A line width of one (1.0) is 1/72nd of an inch at 72 dpi. A Stack Overflow post discusses dpi and figure size in good detail.

subKey ‘projection’

  • name (string) – Grid projection [‘LambertConformalConic’,’Mercator’,’Stereographic’]

  • lat_0 (float degrees) – Latitude of projection center [0.0]

  • lat_1 (float degrees) – First standard parallel (latitude) [0.0]

  • lat_2 (float degrees) – Second standard parallel (latitude) [0.0]

  • lat_ts (float degrees) – Latitude of true scale. Defines the latitude where scale is not distorted. Takes precedence over k_0 if both options are used together. For stereographic, if not set, will default to lat_0.

  • lon_0 (float degrees) – Longitude of projection center [0.0]

  • ellps (string) – See proj -le for a list of available ellipsoids [‘GRS80’]

  • R (float meters) – Radius of the sphere given in meters. If both R and ellps are given, R takes precedence.

  • x_0 (float meters) – False easting [0.0]

  • y_0 (float meters) – False northing [0.0]

  • k_0 (float) – Depending on projection, this value determines the scale factor for natural origin or the ellipsoid [1.0]

The subkey ‘projection’ mostly follows proj.org terminology for any giving projection. See: Lambert Conformal Conic, Mercator and Stereographic for more details.

Warning

These options are similar to setGridParameters() which controls the representation of the grid. In this library, it is possible that the grid projection and the plot projection can be in different projections.

setVerboseLevel(newLevel)

Set a new verbose level.

Parameters

newLevel (integer or string) – verbose level to set or update

Returns

none

Return type

none

Note

Setting this to a positive number will increase the feedback from this module.

The available levels are:

Level

Numeric value

CRITICAL

50

ERROR

40

WARNING

30

INFO

20

DEBUG

10

showGridMetadata()

Show current grid metadata.

showGridParameters()

Show current grid parameters.

showLoggers()

Display an alphabetical list of loggers. Messages sent at the INFO level.

showMessages()

This converts the message buffer to text with linefeeds.

showPlotParameters()

Show current plot parameters.

subsetGrid(scaleFactor)

Subsets current grid by the specified scale factor. Scale factor must be an integer and be evenly divisble into the regular grid. A subsetted grid is returned or None on any error.

updateAxes(ax, varArgs)

Apply figure options to axes based on parameters passed to variable.

updateGridMetadata(**kwargs)

Generic routine to apply metadata to appropriate entries to the existing grid loaded into the gridutils object. This also checks any existing gridParameters. This attempts to set several attributes. If only setting one or two attributes, consider using gridtools.gridutils.checkGridMetadata().

Keyword arguments:

  • updateMetadata (boolean) – Allow updates to metadata global attributes. If False, existing metadata is not overwritten. If an attribute is missing, the global attribute is added. Default: True

useDataSource(dsObj)
writeLandmask(dsData, dsVariable, outVariable, outFile, **kwargs)

Write a land mask based on provided information.

writeOceanmask(dsData, dsVariable, outVariable, outFile, **kwargs)

Write a ocean mask based on provided information.