epygram.geometries.D3Geometry — 3-D Geometry class

Contains the classes for 3D geometries of fields.


class epygram.geometries.D3Geometry.D3Geometry(*args, **kwargs)[source]

Bases: epygram.util.RecursiveObject, footprints.FootprintBase

Handles the geometry for a 3-Dimensions Field. Abstract mother class.

Note

This class is managed by footprint.

  • info: Not documented
  • priority: PriorityLevel::DEFAULT (rank=1)

Automatic parameters from the footprint:

  • dimensions (footprints.stdtypes.FPDict) - rxx - Handles grid dimensions.
  • geoid (footprints.stdtypes.FPDict) - rxx - To specify geoid shape.
    • Optional. Default is FPDict::<<as_dict:: dict(ellps = ‘WGS84’,)>>.
  • grid (footprints.stdtypes.FPDict) - rxx - Handles description of the horizontal grid.
  • name (builtins.str) - rxx - Name of geometrical type of representation of points on the Globe.
    • Values: set([‘rotated_reduced_gauss’, ‘unstructured’, ‘mercator’, ‘rotated_lonlat’, ‘regular_gauss’, ‘polar_stereographic’, ‘regular_lonlat’, ‘reduced_gauss’, ‘lambert’])
  • position_on_horizontal_grid (builtins.str) - rwx - Position of points w/r to the horizontal.
    • Optional. Default is ‘__unknown__’.
    • Values: set([‘center’, ‘lower-center’, ‘upper-center’, ‘lower-right’, ‘__unknown__’, ‘upper-right’, ‘lower-left’, ‘center-right’, ‘upper-left’, ‘center-left’])
  • structure (builtins.str) - rxx - Type of geometry.
    • Values: set([‘3D’])
  • vcoordinate (epygram.geometries.VGeometry.VGeometry) - rwx - Handles vertical geometry parameters.
azimuth(*args, **kwargs)[source]

Initial bearing from end1 to end2 points following a Great Circle.

Parameters:
  • end1 – must be a tuple (lon, lat) in degrees.
  • end2 – must be a tuple (lon, lat) in degrees.

Warning: requires the pyproj module.

cartopy_CRS_reproject(lons, lats, projection=None)

Note

Requires plugin: with_cartopy (config.activate_plugins)

Reproject lons/lats onto a cartopy CRS projection coordinates.

datashape

Returns the data shape requested by this geometry.

dimensions

Undocumented footprint attribute

distance(*args, **kwargs)[source]

Computes the distance between two points along a Great Circle.

Parameters:
  • end1 – first point, must be a tuple (lon, lat) in degrees.
  • end2 – second point, must be a tuple (lon, lat) in degrees.

If one of (end1, end2) is a tuple of arrays (like (<array of lon>, <array of lat>)) the other one must be a scalar tuple or a tuple of arrays with same dimensions.

Warning: requires the pyproj module.

eq_Hgeom(other)[source]

Tests if the horizontal part of the geometry is equal to the horizontal part of another geometry. :param: other: other geometry to use in the comparison

geoid

Undocumented footprint attribute

get_levels(d4=False, nb_validities=0, subzone=None)[source]

Returns an array containing the level for each data point.

Parameters:
  • d4
    • if True, returned values are shaped in a 4 dimensions array
    • if False, shape of returned values is determined with respect to geometry d4=True requires nb_validities > 0
  • nb_validities – the number of validities represented in data values
  • subzone – optional, among (‘C’, ‘CI’), for LAM grids only, extracts the levels resp. from the C or C+I zone off the C+I(+E) zone.

Levels are internally stored with the vertical dimension first whereas this method puts the time in first dimension.

grid

Undocumented footprint attribute

linspace(*args, **kwargs)[source]

Returns evenly spaced points over the specified interval. Points are lined up along a Great Circle.

Parameters:
  • end1 – must be a tuple (lon, lat) in degrees.
  • end2 – must be a tuple (lon, lat) in degrees.
  • num – the number of points, including point1 and point2.

Warning: requires the pyproj module.

make_physicallevels_geometry()[source]

Returns a new geometry excluding levels with no physical meaning.

Parameters:getdata – if False returns a field without data
make_point_geometry(lon, lat)[source]

Returns a PointGeometry at coordinates (lon,lat) in degrees.

make_profile_geometry(lon, lat)[source]

Returns a V1DGeometry at coordinates (lon,lat) in degrees.

make_section_geometry(end1, end2, points_number=None, resolution=None, position=None)[source]

Returns a V2DGeometry.

Parameters:
  • end1 – must be a tuple (lon, lat) in degrees.
  • end2 – must be a tuple (lon, lat) in degrees.
  • points_number – defines the total number of horizontal points of the section (including ends). If None, defaults to a number computed from the ends and the resolution.
  • resolution – defines the horizontal resolution to be given to the field. If None, defaults to the horizontal resolution of the field.
  • position – defines the position of data in the grid (for projected grids only)
make_vtkGrid(*args, **kwargs)

Note

Requires plugin: with_vtk (config.activate_plugins)

Makes an empty grid to use with vtk

Parameters:
  • rendering – a usevtk.Usevtk instance
  • subzone

    optional, among (‘C’, ‘CI’), for LAM grids only, returns the grid resp. for the C or C+I zone off the C+I+E zone.

    Default is no subzone, i.e. the whole field.

make_zoom_geometry(zoom, extra_10th=False)[source]

Returns an unstructured geometry with the points contained in zoom.

Parameters:
  • zoom – a dict(lonmin=, lonmax=, latmin=, latmax=).
  • extra_10th – if True, add 1/10th of the X/Y extension of the zoom (only usefull for the regular_lonlat grid implementation).
name

Undocumented footprint attribute

plot3DBluemarble(rendering, subzone=None, interpolation='nearest', color_transform=None)

Note

Requires plugin: with_vtk (config.activate_plugins)

This method adds the NOAA’s bluemarble image to the vtk rendering system. The image is projected on the vertical coordinate of this geometry.

Parameters:
  • rendering – a usevtk.Usevtk instance
  • subzone

    optional, among (‘C’, ‘CI’), for LAM grids only, returns the grid resp. for the C or C+I zone off the C+I+E zone.

    Default is no subzone, i.e. the whole field.

  • interpolation – interpolation method to use to compute levels at each pixel
  • color_transform
    if not None, must be a user-defined function with parameters
    (rgb, alpha, (lons, lats)) with rgb an array representing the rgb values on each of the image points, alpha the alpha values on the same points and (lons, lats) a turple of the points coordinate. The function must return (rgb, alpha). This enables the color modification of the image. For example, the following function transforms the color into grey levels:
    def grey(rgb, alpha, ll):
    rgb[:, :, :] = rgb.mean(axis=2)[:, :, numpy.newaxis] return rgb, alpha
Image can be found here:
https://sos.noaa.gov/datasets/blue-marble-without-clouds/ ftp://public.sos.noaa.gov/land/blue_marble/earth_vegetation/4096.jpg
plot3DMaptiles(rendering, url, resol_factor, minzoom=1, maxzoom=18, subzone=None, interpolation='nearest', color_transform=None)

Note

Requires plugin: with_vtk (config.activate_plugins)

This method adds tiles image to the vtk rendering system. The image is projected on the vertical coordinate of this geometry.

Parameters:
  • rendering – a usevtk.Usevtk instance
  • url – url to get the map tiles to use ex: https://a.tile.openstreetmap.org/${z}/${x}/${y}.png where ${z}, ${x} and ${y} are place holders for zoom, x and y position of the tile
  • resol_factor – how many times the tile resolution must be approximately better than the geometry resolution. A factor of 2 (resp. 1/2.) induce using the next (resp. preceding) zoom level.
  • minzoom/maxzoom – minimum and maximum zoom levels to use
  • subzone

    optional, among (‘C’, ‘CI’), for LAM grids only, returns the grid resp. for the C or C+I zone off the C+I+E zone.

    Default is no subzone, i.e. the whole field.

  • interpolation – interpolation method to use to compute levels at each pixel
  • color_transform
    if not None, must be a user-defined function with parameters
    (rgb, alpha, (lons, lats)) with rgb an array representing the rgb values on each of the image points, alpha the alpha values on the same points and (lons, lats) a turple of the points coordinate. The function must return (rgb, alpha). This enables the color modification of the image. For example, the following function transforms the color into grey levels:
    def grey(rgb, alpha, ll):
    rgb[:, :, :] = rgb.mean(axis=2)[:, :, numpy.newaxis] return rgb, alpha

Zoom computation is done supposing that each tile is made of 256 * 256 pixels.

URL examples (these URLs have been found on internet but some are protected with copyrights and must not be used with this tool or kept in cache; please check before use):

plot3DProjImage(rendering, filename, geometry, subzone=None, interpolation='nearest', color_transform=None)

Note

Requires plugin: with_vtk (config.activate_plugins)

This method adds an image to the vtk rendering system. The image is projected on the vertical coordinate of this geometry.

Parameters:
  • rendering – a usevtk.Usevtk instance
  • filename – path to an image file
  • geometry – projection associated to the geometry
  • subzone

    optional, among (‘C’, ‘CI’), for LAM grids only, returns the grid resp. for the C or C+I zone off the C+I+E zone.

    Default is no subzone, i.e. the whole field.

  • interpolation – interpolation method to use to compute levels at each pixel
  • color_transform
    if not None, must be a user-defined function with parameters
    (rgb, alpha, (lons, lats)) with rgb an array representing the rgb values on each of the image points, alpha the alpha values on the same points and (lons, lats) a turple of the points coordinate. The function must return (rgb, alpha). This enables the color modification of the image. For example, the following function transforms the color into grey levels:
    def grey(rgb, alpha, ll):
    rgb[:, :, :] = rgb.mean(axis=2)[:, :, numpy.newaxis] return rgb, alpha

first_corner and last_corner describe the coverage of the image from the left edge of the leftmost pixel to the right edge of the rightmost pixel.

plotgeometry(color='blue', borderonly=True, **kwargs)[source]

Makes a simple plot of the geometry, with a number of options.

Parameters:
  • color – color of the plotting.
  • borderonly – if True, only plot the border of the grid, else the whole grid. Ignored for global geometries.

For other options, cf. plotfield() method of epygram.fields.H2DField.

This method uses (hence requires) ‘matplotlib’ and ‘basemap’ libraries.

position_on_horizontal_grid

Undocumented footprint attribute

projected_geometry

Is the geometry a projection ?

rectangular_grid

Is the grid rectangular ?

structure

Undocumented footprint attribute

vcoord_as_field(surface_type, validity=None, levels=None)[source]

Returns a field filled with the level values associated to a fake geometry :param validity: validities to associate with the returned field

if None, we try without setting validity
Parameters:
  • surface_type – typeOfFirstFixedSurface to associate to the fake geometry
  • levels – list of values to use as the levels of the fake geometry if None, levels will be replaced by a range
vcoordinate

Undocumented footprint attribute

what(out=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>, vertical_geometry=True, arpifs_var_names=False, spectral_geometry=None)[source]

Writes in file a summary of the geometry.

Parameters:
  • out – the output open file-like object (duck-typing: out.write() only is needed).
  • vertical_geometry – if True, writes the vertical geometry of the field.
  • arpifs_var_names – if True, prints the equivalent ‘arpifs’ variable names.
  • spectral_geometry – an optional dict containing the spectral truncatures {‘in_X’:, ‘in_Y’:} (LAM) or {‘max’:} (global).

class epygram.geometries.D3Geometry.D3RectangularGridGeometry(*args, **kwargs)[source]

Bases: epygram.geometries.D3Geometry.D3Geometry

Handles the geometry for a rectangular 3-Dimensions Field. Abstract.

Note

This class is managed by footprint.

  • info: Not documented
  • priority: PriorityLevel::DEFAULT (rank=1)

Automatic parameters from the footprint:

  • dimensions (footprints.stdtypes.FPDict) - rxx - Handles grid dimensions.
  • geoid (footprints.stdtypes.FPDict) - rxx - To specify geoid shape.
    • Optional. Default is FPDict::<<as_dict:: dict(ellps = ‘WGS84’,)>>.
  • grid (footprints.stdtypes.FPDict) - rxx - Handles description of the horizontal grid.
  • name (builtins.str) - rxx - Name of geometrical type of representation of points on the Globe.
    • Values: set([‘rotated_lonlat’, ‘unstructured’, ‘polar_stereographic’, ‘mercator’, ‘regular_lonlat’, ‘academic’, ‘lambert’])
  • position_on_horizontal_grid (builtins.str) - rwx - Position of points w/r to the horizontal.
    • Optional. Default is ‘__unknown__’.
    • Values: set([‘center’, ‘lower-center’, ‘upper-center’, ‘lower-right’, ‘__unknown__’, ‘upper-right’, ‘lower-left’, ‘center-right’, ‘upper-left’, ‘center-left’])
  • structure (builtins.str) - rxx - Type of geometry.
    • Values: set([‘3D’])
  • vcoordinate (epygram.geometries.VGeometry.VGeometry) - rwx - Handles vertical geometry parameters.
default_cartopy_CRS()

Note

Requires plugin: with_cartopy (config.activate_plugins)

Create a cartopy.crs appropriate to the Geometry.

By default, a PlateCarree (if the domain gets close to a pole) or a Miller projection is returned.

dimensions

Undocumented footprint attribute

extract_subzone(data, subzone)[source]

Extracts the subzone C or CI from a LAM field.

Parameters:
  • data – the data values with shape concording with geometry.
  • subzone – optional, among (‘C’, ‘CI’), for LAM grids only, extracts the data resp. from the C or C+I zone off the C+I(+E) zone.
fill_maskedvalues(data, fill_value=None)[source]

Returns a copy of data with masked values filled with fill_value.

geoid

Undocumented footprint attribute

get_datashape(dimT=1, force_dimZ=None, d4=False, subzone=None)[source]

Returns the data shape according to the geometry.

Parameters:
  • force_dimZ – if supplied, force the Z dimension instead of that of the vertical geometry
  • dimT – if supplied, is the time dimension to be added to the data shape
  • d4
    • if True, shape is 4D
    • if False, shape has only those > 1
  • subzone – optional, among (‘C’, ‘CI’), for LAM grids only, informes that data is resp. on the C or C+I zone off the C+I(+E) zone.
get_lonlat_grid(subzone=None, position=None, d4=False, nb_validities=0)[source]

Returns a tuple of two tables containing one the longitude of each point, the other the latitude, with 2D shape.

Parameters:
  • subzone

    optional, among (‘C’, ‘CI’), for LAM grids only, returns the grid resp. for the C or C+I zone off the C+I+E zone.

    Default is no subzone, i.e. the whole field.

  • position – position of lonlat grid with respect to the model cell. Defaults to self.position_on_horizontal_grid.
  • d4
    • if True, returned values are shaped in a 4 dimensions array
    • if False, shape of returned values is determined with respect to geometry. d4=True requires nb_validities > 0
  • nb_validities – number of validities represented in data values

Shape of 2D data on Rectangular grids:

  • grid[0,0] is SW, grid[-1,-1] is NE
  • grid[0,-1] is SE, grid[-1,0] is NW
gimme_corners_ij(subzone=None)[source]

Returns the indices (i, j) of the four corners of a rectangular grid, as a dict(corner=(i, j)) with corner in:

ll = lower-left / lr = lower-right / ur = upper-right / ul = upper-left.

(0, 0) is always the lower-left corner of the grid.

Parameters:subzone – for LAM fields, returns the corners of the subzone.
gimme_corners_ll(subzone=None, position=None)[source]

Returns the lon/lat of the four corners of a rectangular grid, as a dict(corner=(lon, lat)) with corner in:

ll = lower-left / lr = lower-right / ur = upper-right / ul = upper-left.

Parameters:
  • subzone – for LAM grids, returns the corners of the subzone.
  • position – position of corners with respect to the model cell. Defaults to self.position_on_horizontal_grid.
grid

Undocumented footprint attribute

gridpoints_number

Returns the number of gridpoints of the grid.

Parameters:subzone

optional, among (‘C’, ‘CI’), for LAM grids only, returns the grid resp. for the C or C+I zone off the C+I+E zone.

Default is no subzone, i.e. the whole field.

horizontally_flattened(data)[source]

Returns a copy of data with horizontal dimensions flattened. data must be 4D for simplicity reasons.

isglobal
Returns:True if geometry is global
make_subarray_geometry(first_i, last_i, first_j, last_j)[source]

Make a modified geometry consisting in a subarray of the grid, defined by the indexes given as argument.

make_subsample_geometry(sample_x, sample_y, sample_z)[source]

Make a sample geometry by decreasing resolution. :param sample_x: take one over <sample_x> points in the x direction :param sample_y: same for the y direction :param sample_z: same for the z direction

CAUTION: if your grid contains non physical point, these points can be retain in subsample. Use select_zone beforehand to suppress these points.

minmax_ll(subzone=None)[source]

Return min/max of lon/lat.

name

Undocumented footprint attribute

nearest_points(lon, lat, request, position=None, external_distance=None, squeeze=True)[source]

Returns the (i, j) positions of the nearest points.

Parameters:
  • lon – longitude of point in degrees.
  • lat – latitude of point in degrees.
  • request

    criteria for selecting the points, among: * {‘n’:‘1’} - the nearest point * {‘n’:‘2*2’} - the 2*2 square points around the position * {‘n’:‘4*4’} - the 4*4 square points around the position * {‘n’:’N*N’} - the N*N square points around the position: N must be even * {‘radius’:xxxx, ‘shape’:’square’} - the points which are xxxx metres

    around the position in X or Y direction
    • {‘radius’:xxxx, ‘shape’:’circle’} - the points within xxxx metres around the position. (default shape == circle)
  • position – position in the model cell of the lat lon position. Defaults to self.position_on_horizontal_grid.
  • external_distance – can be a dict containing the target point value and an external field on the same grid as self, to which the distance is computed within the 4 horizontally nearest points; e.g. {‘target_value’:4810, ‘external_field’:a_3DField_with_same_geometry}. If so, the nearest point is selected with distance = |target_value - external_field.data| Only valid with request={‘n’:‘1’}
  • squeeze – True to suppress useless dimensions
Return type:

general output form is [list, list, …, list] with as many list items as the length of lon/lat. Each list item is of the form [tuple, tuple, …, tuple] with as many tuples as the request implies. A tuple represents one of the nearest points associated with one value taken from lon/lat. Each tuple as the form (i, j).

Dimensions with a length of one are removed except if squeeze is False. If squeeze is True and if request implies only one nearest point, the list item of the general output form is replaced by the tuple item; if length of lon/lat is one, the output is directly the list item of the general output form. Hence, if length of lon/lat is one and the request implies only one point, the output is a tuple.

In case of a simple square request, output is actually an array. Otherwise, the output is as described (it cannot be an array because the number of nearest points can vary with the entry point).

In case of a {‘n’:‘2*2’} request, order of points obtained on a rectangular grid is (and must be) such that first and second point share the i position (hence third and forth point also share the i position) and first and third share the j position (hence the second and forth also share the j position).

point_is_inside_domain_ij(i=None, j=None, margin=-0.1, subzone=None)[source]

Returns True if the point(s) of i/j coordinates is(are) inside the field.

Parameters:
  • i – X index of point
  • j – Y index of point.
  • margin – considers the point inside if at least ‘margin’ points far from the border. The -0.1 default is a safety for precision errors.
  • subzone – considers only a subzone among (‘C’, ‘CI’) of the domain.
point_is_inside_domain_ll(lon, lat, margin=-0.1, subzone=None, position=None)[source]

Returns True if the point(s) of lon/lat coordinates is(are) inside the field.

Parameters:
  • lon – longitude of point(s) in degrees.
  • lat – latitude of point(s) in degrees.
  • margin – considers the point inside if at least ‘margin’ points far from the border. The -0.1 default is a safety for precision errors.
  • subzone – considers only a subzone among (‘C’, ‘CI’) of the domain.
  • position – position of the grid with respect to the model cell. Defaults to self.position_on_horizontal_grid.
position_on_horizontal_grid

Undocumented footprint attribute

reshape_data(data, first_dimension=None, d4=False, subzone=None)[source]

Returns a 2D data (horizontal dimensions) reshaped from 1D, according to geometry.

Parameters:
  • data – the 1D data (or 3D with a T and Z dimensions, or 2D with either a T/Z dimension, to be specified), of dimension concording with geometry. In case data is 3D, T must be first dimension and Z the second.
  • first_dimension – in case data is 2D, specify what is the first dimension of data among (‘T’, ‘Z’)
  • subzone – optional, among (‘C’, ‘CI’), for LAM grids only, informes that data is resp. on the C or C+I zone off the C+I(+E) zone.
  • d4
    • if True, returned values are shaped in a 4 dimensions array
    • if False, shape of returned values is determined with respect to geometry
structure

Undocumented footprint attribute

vcoordinate

Undocumented footprint attribute


class epygram.geometries.D3Geometry.D3UnstructuredGeometry(*args, **kwargs)[source]

Bases: epygram.geometries.D3Geometry.D3RectangularGridGeometry

Handles the geometry for an unstructured 3-Dimensions Field.

Note

This class is managed by footprint.

  • info: Not documented
  • priority: PriorityLevel::DEFAULT (rank=1)

Automatic parameters from the footprint:

  • dimensions (footprints.stdtypes.FPDict) - rxx - Handles grid dimensions.
  • geoid (footprints.stdtypes.FPDict) - rxx - To specify geoid shape.
    • Optional. Default is FPDict::<<as_dict:: dict(ellps = ‘WGS84’,)>>.
  • grid (footprints.stdtypes.FPDict) - rxx - Handles description of the horizontal grid.
  • name (builtins.str) - rxx - Name of geometrical type of representation of points on the Globe.
    • Values: set([‘unstructured’])
  • position_on_horizontal_grid (builtins.str) - rwx - Position of points w/r to the horizontal.
    • Optional. Default is ‘center’.
    • Values: set([‘center’])
  • structure (builtins.str) - rxx - Type of geometry.
    • Values: set([‘3D’])
  • vcoordinate (epygram.geometries.VGeometry.VGeometry) - rwx - Handles vertical geometry parameters.
dimensions

Undocumented footprint attribute

geoid

Undocumented footprint attribute

get_lonlat_grid(subzone=None, position=None, d4=False, nb_validities=0)[source]

Returns a tuple of two tables containing one the longitude of each point, the other the latitude, with 2D shape.

Parameters:
  • subzone

    optional, among (‘C’, ‘CI’), for LAM grids only, returns the grid resp. for the C or C+I zone off the C+I+E zone.

    Default is no subzone, i.e. the whole field.

  • position – position of lonlat grid with respect to the model cell. Defaults to self.position_on_horizontal_grid.
  • d4
    • if True, returned values are shaped in a 4 dimensions array
    • if False, shape of returned values is determined with respect to geometry.
      d4=True requires nb_validities > 0
  • nb_validities – number of validities represented in data values

Shape of 2D data on Rectangular grids:

  • grid[0,0] is SW, grid[-1,-1] is NE
  • grid[0,-1] is SE, grid[-1,0] is NW
getcenter(position=None)[source]

Returns the coordinate of the grid center as a tuple of Angles (center_lon, center_lat).

Caution: this is computed as the raw average of all grid points. A barycentric computation would be more adequate.

grid

Undocumented footprint attribute

ij2ll(i, j, position=None)[source]

Return the (lon, lat) coordinates of point (i,j), in degrees.

Parameters:
  • i – X index of point in the 2D matrix of gridpoints
  • j – Y index of point in the 2D matrix of gridpoints
  • position – lat lon position to return with respect to the model cell. Defaults to self.position_on_horizontal_grid.
ll2ij(lon, lat, position=None)[source]

Return the (i, j) indexes of point (lon, lat) in degrees, in the 2D matrix of gridpoints.

Parameters:
  • lon – longitude of point in degrees
  • lat – latitude of point in degrees
  • position – lat lon position to return with respect to the model cell. Defaults to self.position_on_horizontal_grid.

Caution: the returned (i,j) are float.

make_basemap(gisquality='i', specificproj=None, zoom=None, ax=None, **_)

Note

Requires plugin: with_basemap (config.activate_plugins)

Returns a matplotlib.basemap.Basemap object of the ‘ad hoc’ projection (if available). This is designed to avoid explicit handling of deep horizontal geometry attributes.

Parameters:
  • gisquality

    defines the quality of GIS contours, cf. Basemap doc.

    Possible values (by increasing quality): ‘c’, ‘l’, ‘i’, ‘h’, ‘f’.

  • specificproj

    enables to make basemap on the specified projection, among: ‘kav7’, ‘cyl’, ‘ortho’, (‘nsper’, {…}) (cf. Basemap doc). In ‘nsper’ case, the {} may contain:

    • ’sat_height’ = satellite height in km;
    • ’lon’ = longitude of nadir in degrees;
    • ’lat’ = latitude of nadir in degrees.

    Overwritten by zoom.

  • zoom

    specifies the lon/lat borders of the map, implying hereby a ‘cyl’ projection. Must be a dict(lonmin=, lonmax=, latmin=, latmax=).

    Overwrites specificproj.

  • ax – a matplotlib ax on which to plot; if None, plots will be done on matplotlib.pyplot.gca()
name

Undocumented footprint attribute

nearest_points(lon, lat, request, position=None, external_distance=None, squeeze=True)[source]

Returns the (i, j) position of the points needed to perform an interpolation. This is a list of (lon, lat) tuples.

Parameters:
  • lon – longitude of point in degrees.
  • lat – latitude of point in degrees.
  • request – criteria for selecting the points, among: * {‘n’:‘1’} - the nearest point
  • position – position in the model cell of the lat lon position. Defaults to self.position_on_horizontal_grid.
  • external_distance – can be a dict containing the target point value and an external field on the same grid as self, to which the distance is computed within the 4 horizontally nearest points; e.g. {‘target_value’:4810, ‘external_field’:a_3DField_with_same_geometry}. If so, the nearest point is selected with distance = |target_value - external_field.data|
  • squeeze – True to suppress useless dimensions
Return type:

general output form is [list, list, …, list] with as many list items as the length of lon/lat. Each list item is of the form [tuple, tuple, …, tuple] with as many tuples as the request implies. A tuple represents one of the nearest points associated with one value taken from lon/lat. Each tuple as the form (i, j).

Dimensions with a length of one are removed except if squeeze is False. If squeeze is True and if request implies only one nearest point, the list item of the general output form is replaced by the tuple item; if length of lon/lat is one, the output is directly the list item of the general output form. Hence, if length of lon/lat is one and the request implies only one point, the output is a tuple.

In case of a simple square request, output is actually an array. Otherwise, the output is as described (it cannot be an array because the number of nearest points can vary with the entry point).

position_on_horizontal_grid

Undocumented footprint attribute

resolution_ij(i, j, position=None)[source]

Returns the distance to the nearest point of (i,j) point.

Parameters:
  • i – X index of point in the 2D matrix of gridpoints
  • j – Y index of point in the 2D matrix of gridpoints
resolution_ll(lon, lat)[source]

Returns the local resolution at the nearest point of lon/lat. It’s the distance between this point and its closest neighbour.

Parameters:
  • lon – longitude of point in degrees.
  • lat – latitude of point in degrees.
structure

Undocumented footprint attribute

vcoordinate

Undocumented footprint attribute


class epygram.geometries.D3Geometry.D3AcademicGeometry(*args, **kwargs)[source]

Bases: epygram.geometries.D3Geometry.D3RectangularGridGeometry

Handles the geometry for an academic 3-Dimensions Field.

Note

This class is managed by footprint.

  • info: Not documented
  • priority: PriorityLevel::DEFAULT (rank=1)

Automatic parameters from the footprint:

  • dimensions (footprints.stdtypes.FPDict) - rxx - Handles grid dimensions.
  • geoid (footprints.stdtypes.FPDict) - rxx - Of no meaning in this geometry.
    • Optional. Default is FPDict::<<as_dict:: dict()>>.
  • grid (footprints.stdtypes.FPDict) - rxx - Handles description of the horizontal grid.
  • name (builtins.str) - rxx - Name of geometrical type of representation of points on the Globe.
    • Values: set([‘academic’])
  • position_on_horizontal_grid (builtins.str) - rwx - Position of points w/r to the horizontal.
    • Optional. Default is ‘__unknown__’.
    • Values: set([‘center’, ‘lower-center’, ‘upper-center’, ‘lower-right’, ‘__unknown__’, ‘upper-right’, ‘lower-left’, ‘center-right’, ‘upper-left’, ‘center-left’])
  • projection (footprints.stdtypes.FPDict) - rxx - Handles projection information.
  • structure (builtins.str) - rxx - Type of geometry.
    • Values: set([‘3D’])
  • vcoordinate (epygram.geometries.VGeometry.VGeometry) - rwx - Handles vertical geometry parameters.
azimuth(end1, end2)[source]

Same as plane_azimuth in this geometry.

default_cartopy_CRS()

Note

Requires plugin: with_cartopy (config.activate_plugins)

Create a cartopy.crs appropriate to the Geometry.

In this case, cartopy is not used but raw matplotlib, so returned CRS is None.

dimensions

Undocumented footprint attribute

distance(end1, end2)[source]

Computes the distance between two points along a straight line in the geometry. :param end1: must be a tuple (lon, lat) in degrees. :param end2: must be a tuple (lon, lat) in degrees.

geoid

Undocumented footprint attribute

getcenter()[source]

Returns the coordinate of the grid center as a tuple (center_lon, center_lat).

grid

Undocumented footprint attribute

ij2ll(i, j, position=None)[source]

Return the (lon, lat) coordinates of point (i,j), in degrees.

Parameters:
  • i – X index of point in the 2D matrix of gridpoints
  • j – Y index of point in the 2D matrix of gridpoints
  • position – lat lon position to return with respect to the model cell. Defaults to self.position_on_horizontal_grid.

This routine has a special meaning for this geometry. It returns the (i, j) position in the original grid (especially after a section extraction) with an offset of one (for old tools compatibility).

ij2xy(i, j, position=None)[source]

Return the (x, y) coordinates of point (i,j), in the projection.

Parameters:
  • i – X index of point in the 2D matrix of gridpoints
  • j – Y index of point in the 2D matrix of gridpoints
  • position – position to return with respect to the model cell. Defaults to self.position_on_horizontal_grid.

Note that origin of coordinates in projection is the center of the C+I domain.

linspace(end1, end2, num)[source]

Returns evenly spaced points over the specified interval. Points are lined up in the geometry.

Parameters:
  • end1 – must be a tuple (lon, lat) in degrees.
  • end2 – must be a tuple (lon, lat) in degrees.
  • num – number of points, including point1 and point2.
ll2ij(lon, lat, position=None)[source]

Return the (i, j) indexes of point (lon, lat) in degrees, in the 2D matrix of gridpoints.

Parameters:
  • lon – longitude of point in degrees
  • lat – latitude of point in degrees
  • position – lat lon position to return with respect to the model cell. Defaults to self.position_on_horizontal_grid.

Caution: the returned (i,j) are float.

This routine has a special meaning for this geometry. It returns the (lon, lat) position in the original grid (especially after a section extraction) with an offset of one (for old tools compatibility).

ll2xy(lon, lat)[source]

Return the (x, y) coordinates of point (lon, lat) in degrees.

Parameters:
  • lon – longitude of point in degrees
  • lat – latitude of point in degrees

Note that origin of coordinates in projection is the center of the C+I domain.

make_section_geometry(end1, end2, points_number=None, resolution=None, position=None)[source]

Returns a academic V2DGeometry.

Parameters:
  • end1 – must be a tuple (lon, lat) in degrees.
  • end2 – must be a tuple (lon, lat) in degrees.
  • points_number – defines the total number of horizontal points of the section (including ends). If None, defaults to a number computed from the ends and the resolution.
  • resolution – defines the horizontal resolution to be given to the field. If None, defaults to the horizontal resolution of the field.
  • position – defines the position of data in the grid (defaults to ‘center’)
name

Undocumented footprint attribute

plane_azimuth(end1, end2)[source]

Initial bearing from end1 to end2 points in plane local referential geometry.

Parameters:
  • end1 – must be a tuple (lon, lat) in degrees.
  • end2 – must be a tuple (lon, lat) in degrees.
position_on_horizontal_grid

Undocumented footprint attribute

projection

Undocumented footprint attribute

resolution_ij(*_, **__)[source]

Returns the minimum of X and Y resolution.

resolution_ll(*_, **__)[source]

Returns the minimum of X and Y resolution.

structure

Undocumented footprint attribute

vcoordinate

Undocumented footprint attribute

xy2ij(x, y, position=None)[source]

Return the (i, j) indexes of point (x, y), in the 2D matrix of gridpoints.

Parameters:
  • x – X coordinate of point in the academic projection
  • y – Y coordinate of point in the academic projection
  • position – position to return with respect to the model cell. Defaults to self.position_on_horizontal_grid.

Caution: (i,j) are float (the nearest grid point is the nearest integer).

Note that origin of coordinates in projection is the center of the C+I domain.

xy2ll(x, y)[source]

Return the (lon, lat) coordinates of point (x, y) in the 2D matrix of gridpoints*(i,j)*, in degrees.

Parameters:
  • x – X coordinate of point in the academic projection
  • y – Y coordinate of point in the academic projection

Note that origin of coordinates in projection is the center of the C+I domain.


class epygram.geometries.D3Geometry.D3RegLLGeometry(*args, **kwargs)[source]

Bases: epygram.geometries.D3Geometry.D3RectangularGridGeometry

Handles the geometry for a Regular Lon/Lat 3-Dimensions Field.

Note

This class is managed by footprint.

  • info: Not documented
  • priority: PriorityLevel::DEFAULT (rank=1)

Automatic parameters from the footprint:

  • dimensions (footprints.stdtypes.FPDict) - rxx - Handles grid dimensions.
  • geoid (footprints.stdtypes.FPDict) - rxx - To specify geoid shape.
    • Optional. Default is FPDict::<<as_dict:: dict(ellps = ‘WGS84’,)>>.
  • grid (footprints.stdtypes.FPDict) - rxx - Handles description of the horizontal grid.
  • name (builtins.str) - rxx - Name of geometrical type of representation of points on the Globe.
    • Values: set([‘regular_lonlat’])
  • position_on_horizontal_grid (builtins.str) - rwx - Position of points w/r to the horizontal.
    • Optional. Default is ‘__unknown__’.
    • Values: set([‘center’, ‘lower-center’, ‘upper-center’, ‘lower-right’, ‘__unknown__’, ‘upper-right’, ‘lower-left’, ‘center-right’, ‘upper-left’, ‘center-left’])
  • structure (builtins.str) - rxx - Type of geometry.
    • Values: set([‘3D’])
  • vcoordinate (epygram.geometries.VGeometry.VGeometry) - rwx - Handles vertical geometry parameters.
dimensions

Undocumented footprint attribute

distance(*args, **kwargs)[source]

Computes the distance between two points along a straight line in the geometry.

Parameters:
  • end1 – must be a tuple (lon, lat) in degrees.
  • end2 – must be a tuple (lon, lat) in degrees.

Warning: requires the pyproj module.

geoid

Undocumented footprint attribute

getcenter()[source]

Returns the coordinate of the grid center as a tuple of Angles (center_lon, center_lat).

global_shift_center(longitude_shift)[source]

Shifts the center of the geometry by longitude_shift (in degrees). longitude_shift has to be a multiple of the grid’s resolution in longitude.

grid

Undocumented footprint attribute

ij2ll(i, j, position=None)[source]

Return the (lon, lat) coordinates of point (i,j), in degrees.

Parameters:
  • i – X index of point in the 2D matrix of gridpoints
  • j – Y index of point in the 2D matrix of gridpoints
  • position – lat lon position to return with respect to the model cell. Defaults to self.position_on_horizontal_grid.
ij2xy(i, j, position=None)[source]

Return the (x, y) coordinates of point (i,j), in the projection.

Parameters:
  • i – X index of point in the 2D matrix of gridpoints
  • j – Y index of point in the 2D matrix of gridpoints
  • position – position to return with respect to the model cell. Defaults to self.position_on_horizontal_grid.

Note that origin of coordinates in projection is the center of the C+I domain.

isglobal
Returns:True if geometry is global
linspace(end1, end2, num)[source]

Returns evenly spaced points over the specified interval. Points are lined up in the geometry.

Parameters:
  • end1 – must be a tuple (lon, lat) in degrees.
  • end2 – must be a tuple (lon, lat) in degrees.
  • num – number of points, including point1 and point2.
ll2ij(lon, lat, position=None)[source]

Return the (i, j) indexes of point (lon, lat) in degrees, in the 2D matrix of gridpoints.

Parameters:
  • lon – longitude of point in degrees
  • lat – latitude of point in degrees
  • position – lat lon position to return with respect to the model cell. Defaults to self.position_on_horizontal_grid.

Caution: (i,j) are float.

ll2xy(lon, lat)[source]

Return the (x, y) coordinates of point (lon, lat) in degrees.

Parameters:
  • lon – longitude of point in degrees
  • lat – latitude of point in degrees

Note that origin of coordinates in projection is the center of the C+I domain.

make_basemap(gisquality='i', subzone=None, specificproj=None, zoom=None, ax=None)

Note

Requires plugin: with_basemap (config.activate_plugins)

Returns a matplotlib.basemap.Basemap object of the ‘ad hoc’ projection (if available). This is designed to avoid explicit handling of deep horizontal geometry attributes.

Parameters:
  • gisquality

    defines the quality of GIS contours, cf. Basemap doc.

    Possible values (by increasing quality): ‘c’, ‘l’, ‘i’, ‘h’, ‘f’.

  • subzone – defines the LAM subzone to be included, in LAM case, among: ‘C’, ‘CI’.
  • specificproj

    enables to make basemap on the specified projection, among: ‘kav7’, ‘cyl’, ‘ortho’, (‘nsper’, {…}) (cf. Basemap doc).

    In ‘nsper’ case, the {} may contain:

    • ’sat_height’ = satellite height in km;
    • ’lon’ = longitude of nadir in degrees;
    • ’lat’ = latitude of nadir in degrees.

    Overwritten by zoom.

  • zoom

    specifies the lon/lat borders of the map, implying hereby a ‘cyl’ projection. Must be a dict(lonmin=, lonmax=, latmin=, latmax=).

    Overwrites specificproj.

  • ax – a matplotlib ax on which to plot; if None, plots will be done on matplotlib.pyplot.gca()
make_zoom_geometry(zoom, extra_10th=False)[source]

Returns a new geometry with the points contained in zoom.

Parameters:
  • zoom – a dict(lonmin=, lonmax=, latmin=, latmax=).
  • extra_10th – if True, add 1/10th of the X/Y extension of the zoom (only usefull for the regular_lonlat grid implementation).
name

Undocumented footprint attribute

plane_azimuth(end1, end2)[source]

Initial bearing from end1 to end2 points in plane local referential geometry.

Parameters:
  • end1 – must be a tuple (lon, lat) in degrees.
  • end2 – must be a tuple (lon, lat) in degrees.
position_on_horizontal_grid

Undocumented footprint attribute

resolution_ij(i, j)[source]

Returns the distance to the nearest point of (i,j) point.

Parameters:
  • i – X index of point in the 2D matrix of gridpoints
  • j – Y index of point in the 2D matrix of gridpoints
resolution_ll(lon, lat)[source]

Returns the local resolution at the nearest point of lon/lat. It’s the distance between this point and its closest neighbour.

Parameters:
  • lon – longitude of the point in degrees
  • lat – latitude of the point in degrees
structure

Undocumented footprint attribute

vcoordinate

Undocumented footprint attribute

xy2ij(x, y, position=None)[source]

Return the (i, j) indexes of point (x, y), in the 2D matrix of gridpoints.

Parameters:
  • x – X coordinate of point in the projection
  • y – Y coordinate of point in the projection
  • position – position to return with respect to the model cell. Defaults to self.position_on_horizontal_grid.

Caution: (i,j) are float (the nearest grid point is the nearest integer).

Note that origin of coordinates in projection is the center of the C+I domain.

xy2ll(x, y)[source]

Return the (lon, lat) coordinates of point (x, y) in the 2D matrix of gridpoints*(i,j)*, in degrees.

Parameters:
  • x – X coordinate of point in the projection
  • y – Y coordinate of point in the projection

Note that origin of coordinates in projection is the center of the C+I domain.


class epygram.geometries.D3Geometry.D3ProjectedGeometry(*args, **kwargs)[source]

Bases: epygram.geometries.D3Geometry.D3RectangularGridGeometry

Handles the geometry for a Projected 3-Dimensions Field.

Note

This class is managed by footprint.

  • info: Not documented
  • priority: PriorityLevel::DEFAULT (rank=1)

Automatic parameters from the footprint:

  • dimensions (footprints.stdtypes.FPDict) - rxx - Handles grid dimensions.
  • geoid (footprints.stdtypes.FPDict) - rxx - To specify geoid shape.
    • Optional. Default is FPDict::<<as_dict:: dict(ellps = ‘WGS84’,)>>.
  • grid (footprints.stdtypes.FPDict) - rxx - Handles description of the horizontal grid.
  • name (builtins.str) - rxx - Name of geometrical type of representation of points on the Globe.
    • Values: set([‘polar_stereographic’, ‘mercator’, ‘lambert’, ‘space_view’])
  • position_on_horizontal_grid (builtins.str) - rwx - Position of points w/r to the horizontal.
    • Optional. Default is ‘__unknown__’.
    • Values: set([‘center’, ‘lower-center’, ‘upper-center’, ‘lower-right’, ‘__unknown__’, ‘upper-right’, ‘lower-left’, ‘center-right’, ‘upper-left’, ‘center-left’])
  • projection (footprints.stdtypes.FPDict) - rxx - Handles projection information.
  • structure (builtins.str) - rxx - Type of geometry.
    • Values: set([‘3D’])
  • vcoordinate (epygram.geometries.VGeometry.VGeometry) - rwx - Handles vertical geometry parameters.
compass_grid(subzone=None, position=None)[source]

Get the compass grid, i.e. the angle between Y-axis and North for each gridpoint.

Parameters:
  • subzone

    optional, among (‘C’, ‘CI’), for LAM grids only, returns the grid resp. for the C or C+I zone off the C+I+E zone.

    Default is no subzone, i.e. the whole field.

  • position – position of lonlat grid with respect to the model cell. Defaults to self.position_on_horizontal_grid.
default_cartopy_CRS()

Note

Requires plugin: with_cartopy (config.activate_plugins)

Create a cartopy.crs appropriate to the Geometry.

dimensions

Undocumented footprint attribute

distance(end1, end2)[source]

Computes the distance between two points along a straight line in the geometry.

Parameters:
  • end1 – must be a tuple (lon, lat) in degrees.
  • end2 – must be a tuple (lon, lat) in degrees.
geoid

Undocumented footprint attribute

get_cartopy_extent(subzone=None)

Note

Requires plugin: with_cartopy (config.activate_plugins)

Gets the extension of the geometry in the default crs :param subzone: defines the LAM subzone to be included, in LAM case,

among: ‘C’, ‘CI’.
Returns:(xmin, xmax, ymin, ymax) as expected by matplotlib’s ax.set_extent
getcenter()[source]

Returns the coordinate of the grid center as a tuple of Angles (center_lon, center_lat).

grid

Undocumented footprint attribute

ij2ll(i, j, position=None)[source]

Return the (lon, lat) coordinates of point (i,j), in degrees.

Parameters:
  • i – X index of point in the 2D matrix of gridpoints
  • j – Y index of point in the 2D matrix of gridpoints
  • position – lat lon position to return with respect to the model cell. Defaults to self.position_on_horizontal_grid.
ij2xy(i, j, position=None)[source]

Return the (x, y) coordinates of point (i,j), in the projection.

Parameters:
  • i – X index of point in the 2D matrix of gridpoints
  • j – Y index of point in the 2D matrix of gridpoints
  • position – position to return with respect to the model cell. Defaults to self.position_on_horizontal_grid.

Note that origin of coordinates in projection is the center of the C+I domain.

linspace(end1, end2, num)[source]

Returns evenly spaced points over the specified interval. Points are lined up in the geometry.

Parameters:
  • end1 – must be a tuple (lon, lat) in degrees.
  • end2 – must be a tuple (lon, lat) in degrees.
  • num – number of points, including point1 and point2.
ll2ij(lon, lat, position=None)[source]

Return the (i, j) indexes of point (lon, lat) in degrees, in the 2D matrix of gridpoints.

Parameters:
  • lon – longitude of point in degrees
  • lat – latitude of point in degrees
  • position – lat lon position to return with respect to the model cell. Defaults to self.position_on_horizontal_grid.

Caution: (i,j) are float.

ll2xy(lon, lat)[source]

Return the (x, y) coordinates of point (lon, lat) in degrees.

Parameters:
  • lon – longitude of point in degrees
  • lat – latitude of point in degrees

Note that origin of coordinates in projection is the center of the C+I domain.

make_basemap(gisquality='i', subzone=None, specificproj=None, zoom=None, ax=None)

Note

Requires plugin: with_basemap (config.activate_plugins)

Returns a matplotlib.basemap.Basemap object of the ‘ad hoc’ projection (if available). This is designed to avoid explicit handling of deep horizontal geometry attributes.

Deprecated since version 1.3.9.

Parameters:
  • gisquality – defines the quality of GIS contours, cf. Basemap doc. Possible values (by increasing quality): ‘c’, ‘l’, ‘i’, ‘h’, ‘f’.
  • subzone – defines the LAM subzone to be included, in LAM case, among: ‘C’, ‘CI’.
  • specificproj

    enables to make basemap on the specified projection, among: ‘kav7’, ‘cyl’, ‘ortho’, (‘nsper’, {…}) (cf. Basemap doc).

    In ‘nsper’ case, the {} may contain:

    • ’sat_height’ = satellite height in km;
    • ’lon’ = longitude of nadir in degrees;
    • ’lat’ = latitude of nadir in degrees.

    Overwritten by zoom.

  • zoom – specifies the lon/lat borders of the map, implying hereby a ‘cyl’ projection. Must be a dict(lonmin=, lonmax=, latmin=, latmax=). Overwrites specificproj.
  • ax – a matplotlib ax on which to plot; if None, plots will be done on matplotlib.pyplot.gca()
make_section_geometry(end1, end2, points_number=None, resolution=None, position=None)[source]

Returns a projected V2DGeometry.

Parameters:
  • end1 – must be a tuple (lon, lat) in degrees.
  • end2 – must be a tuple (lon, lat) in degrees.
  • points_number – defines the total number of horizontal points of the section (including ends). If None, defaults to a number computed from the ends and the resolution.
  • resolution – defines the horizontal resolution to be given to the field. If None, defaults to the horizontal resolution of the field.
  • position – defines the position of data in the grid (defaults to ‘center’)
map_factor(lat)[source]

Returns the map factor at the given latitude(s) lat in degrees.

map_factor_field(position=None)[source]

Returns a new field whose data is the map factor over the field.

Parameters:position – grid position with respect to the model cell. Defaults to self.position_on_horizontal_grid.
mesh_area(lat)[source]

Compute the area of a mesh/gridpoint, given its latitude.

mesh_area_field(position=None)[source]

Returns a new field whose data is the mesh area of gridpoints, i.e. X_resolution x Y_resolution / m^2, where m is the local map factor.

Parameters:position – grid position with respect to the model cell. Defaults to self.position_on_horizontal_grid.
name

Undocumented footprint attribute

plane_azimuth(end1, end2)[source]

Initial bearing from end1 to end2 points in plane local referential geometry.

Parameters:
  • end1 – must be a tuple (lon, lat) in degrees.
  • end2 – must be a tuple (lon, lat) in degrees.
position_on_horizontal_grid

Undocumented footprint attribute

projection

Undocumented footprint attribute

reproject_wind_on_lonlat(u, v, lon=None, lat=None, map_factor_correction=True, reverse=False)[source]

Reprojects a wind vector (u, v) on the grid onto real axes, i.e. with components on true zonal/meridian axes.

Parameters:
  • u – the u == zonal-on-the-grid component of wind
  • v – the v == meridian-on-the-grid component of wind
  • lon – longitudes of points in degrees, if u/v are not vectors on the whole grid
  • lat – latitudes of points in degrees, if u/v are not vectors on the whole grid
:param map_factor_correction:, applies a correction of magnitude due
to map factor.
Parameters:reverse – if True, apply the reverse reprojection.
resolution_ij(i, j)[source]

Returns the distance to the nearest point of (i,j) point.

Parameters:
  • i – X index of point in the 2D matrix of gridpoints
  • j – Y index of point in the 2D matrix of gridpoints
resolution_ll(lon, lat)[source]

Returns the local resolution at the nearest point of lon/lat. It’s the distance between this point and its closest neighbour.

Parameters:
  • lon – longitude of the point in degrees
  • lat – latitude of the point in degrees
secant_projection

Is the projection secant to the sphere ? (or tangent)

select_subzone(subzone)[source]

If a LAMzone defines the geometry, select only the subzone from it and return a new geometry object.

Parameters:subzone – among (‘C’, ‘CI’).
structure

Undocumented footprint attribute

vcoordinate

Undocumented footprint attribute

xy2ij(x, y, position=None)[source]

Return the (i, j) indexes of point (x, y), in the 2D matrix of gridpoints.

Parameters:
  • x – X coordinate of point in the projection
  • y – Y coordinate of point in the projection
  • position – position to return with respect to the model cell. Defaults to self.position_on_horizontal_grid.

Caution: (i,j) are float (the nearest grid point is the nearest integer).

Note that origin of coordinates in projection is the center of the C+I domain.

xy2ll(x, y)[source]

Return the (lon, lat) coordinates of point (x, y) in the 2D matrix of gridpoints*(i,j)*, in degrees.

Parameters:
  • x – X coordinate of point in the projection
  • y – Y coordinate of point in the projection

Note that origin of coordinates in projection is the center of the C+I domain.


class epygram.geometries.D3Geometry.D3GaussGeometry(*args, **kwargs)[source]

Bases: epygram.geometries.D3Geometry.D3Geometry

Handles the geometry for a Global Gauss grid 3-Dimensions Field.

Note

This class is managed by footprint.

  • info: Not documented
  • priority: PriorityLevel::DEFAULT (rank=1)

Automatic parameters from the footprint:

  • dimensions (footprints.stdtypes.FPDict) - rxx - Handles grid dimensions.
  • geoid (footprints.stdtypes.FPDict) - rxx - To specify geoid shape.
    • Optional. Default is FPDict::<<as_dict:: dict(ellps = ‘WGS84’,)>>.
  • grid (footprints.stdtypes.FPDict) - rxx - Handles description of the horizontal grid.
  • name (builtins.str) - rxx - Name of geometrical type of representation of points on the Globe.
    • Values: set([‘reduced_gauss’, ‘rotated_reduced_gauss’, ‘regular_gauss’])
  • position_on_horizontal_grid (builtins.str) - rwx - Position of points w/r to the horizontal.
    • Optional. Default is ‘__unknown__’.
    • Values: set([‘center’, ‘lower-center’, ‘upper-center’, ‘lower-right’, ‘__unknown__’, ‘upper-right’, ‘lower-left’, ‘center-right’, ‘upper-left’, ‘center-left’])
  • structure (builtins.str) - rxx - Type of geometry.
    • Values: set([‘3D’])
  • vcoordinate (epygram.geometries.VGeometry.VGeometry) - rwx - Handles vertical geometry parameters.
default_cartopy_CRS()

Note

Requires plugin: with_cartopy (config.activate_plugins)

Create a cartopy.crs appropriate to the Geometry.

dimensions

Undocumented footprint attribute

distance_to_nearest_neighbour_ij(i, j)[source]

Returns the distance to the nearest point of (i,j) point

Parameters:
  • i – X index of point in the 2D matrix of gridpoints
  • j – Y index of point in the 2D matrix of gridpoints
distance_to_nearest_neighbour_ll(lon, lat)[source]

Returns the local resolution at the nearest point of lon/lat. It’s the distance between this point and its closest neighbour.

Parameters:
  • lon – longitude of the point in degrees
  • lat – latitude of the point in degrees
fill_maskedvalues(data, fill_value=None)[source]

Returns a copy of data with ‘real’ masked values (i.e. not those linked to reduced Gauss) filled with fill_value. data must be already 4D for simplicity reasons.

geoid

Undocumented footprint attribute

get_datashape(force_dimZ=None, dimT=None, d4=False, **_)[source]

Returns the data shape according to the geometry.

Parameters:
  • force_dimZ – if supplied, force the Z dimension instead of that of the vertical geometry
  • dimT – if supplied, is the time dimension to be added to the data shape
  • d4
    • if True, shape is 4D (need to specify dimT)
    • if False, shape is 3D if dimZ > 1 else 2D
get_lonlat_grid(position=None, d4=False, nb_validities=0, **_)[source]

Returns a tuple of two tables containing one the longitude of each point, the other the latitude, with 2D shape.

Shape of 2D data in Gauss grids:

  • grid[0, 0:Nj] is first (Northern) band of latitude, masked after Nj = number of longitudes for latitude j
  • grid[-1, 0:Nj] is last (Southern) band of latitude (idem).
Parameters:
  • position – position of lonlat grid with respect to the model cell. Defaults to self.position_on_horizontal_grid.
  • d4
    • if True, returned values are shaped in a 4 dimensions array
    • if False, shape of returned values is determined with respect to geometry.
      d4=True requires nb_validities > 0
  • nb_validities – number of validities represented in data values
grid

Undocumented footprint attribute

gridpoints_number

Returns the number of gridpoints of the grid.

horizontally_flattened(data)[source]

Returns a copy of data with horizontal dimensions flattened and compressed (cf. numpy.ma.masked_array.compressed). data must be 4D for simplicity reasons.

ij2ll(i, j, position=None)[source]

Return the (lon, lat) coordinates of point (i,j), in degrees.

Parameters:
  • i – X index of point in the 2D matrix of gridpoints
  • j – Y index of point in the 2D matrix of gridpoints
  • position – lat lon position to return with respect to the model cell. Defaults to self.position_on_horizontal_grid.
isglobal
Returns:True if geometry is global
ll2ij(lon, lat, position=None)[source]

Return the (i, j) coordinates in the 2D matrix of gridpoints, of the gridpoint nearest to (lon, lat).

Parameters:
  • lon – longitude of point in degrees
  • lat – latitude of point in degrees
  • position – lat lon position to return with respect to the model cell. Defaults to self.position_on_horizontal_grid.
make_basemap(gisquality='l', specificproj=None, zoom=None, ax=None, **_)

Note

Requires plugin: with_basemap (config.activate_plugins)

Returns a matplotlib.basemap.Basemap object of the ‘ad hoc’ projection (if available). This is designed to avoid explicit handling of deep horizontal geometry attributes.

Parameters:
  • gisquality

    defines the quality of GIS contours, cf. Basemap doc.

    Possible values (by increasing quality): ‘c’, ‘l’, ‘i’, ‘h’, ‘f’. WARNING: this is forced to ‘l’ inside (except if a zoom is given), for time-consumption reasons.

  • specificproj

    enables to make basemap on the specified projection, among: ‘kav7’, ‘cyl’, ‘ortho’, (‘nsper’, {…}) (cf. Basemap doc).

    In ‘nsper’ case, the {} may contain:

    • ’sat_height’ = satellite height in km;
    • ’lon’ = longitude of nadir in degrees;
    • ’lat’ = latitude of nadir in degrees.

    Overwritten by zoom.

  • zoom

    specifies the lon/lat borders of the map, implying hereby a ‘cyl’ projection. Must be a dict(lonmin=, lonmax=, latmin=, latmax=).

    Overwrites specificproj.

  • ax – a matplotlib ax on which to plot; if None, plots will be done on matplotlib.pyplot.gca()
map_factor(lon, lat)[source]

Returns the map factor at the given longitude/latitude(s)

Parameters:
  • lon – longitude in degrees
  • lat – latitude in degrees
map_factor_field(position=None)[source]

Returns a new field whose data is the map factor over the field.

Parameters:position – grid position with respect to the model cell. Defaults to self.position_on_horizontal_grid.
meridian_resolution_j(j)[source]

Returns the average meridian resolution at longitude circle number j.

name

Undocumented footprint attribute

nearest_points(lon, lat, request, position=None, external_distance=None, squeeze=True)[source]

Returns a list of the (i, j) position of the points needed to perform an interpolation.

Parameters:
  • lon – longitude of point in degrees.
  • lat – latitude of point in degrees.
  • request

    criteria for selecting the points, among: * {‘n’:‘1’} - the nearest point * {‘n’:‘2*2’} - the 2*2 square points around the position * {‘n’:‘4*4’} - the 4*4 square points around the position * {‘n’:’N*N’} - the N*N square points around the position: N must be even * {‘radius’:xxxx, ‘shape’:’square’} - the points which are xxxx metres

    around the position in X or Y direction
    • {‘radius’:xxxx, ‘shape’:’circle’} - the points within xxxx metres around the position. (default shape == circle)
  • position – position in the model cell of the lat lon position. Defaults to self.position_on_horizontal_grid.
  • external_distance – can be a dict containing the target point value and an external field on the same grid as self, to which the distance is computed within the 4 horizontally nearest points; e.g. {‘target_value’:4810, ‘external_field’:a_3DField_with_same_geometry}. If so, the nearest point is selected with distance = |target_value - external_field.data|
  • squeeze – True to suppress useless dimensions
Return type:

general output form is [list, list, …, list] with as many list items as the length of lon/lat. Each list item is of the form [tuple, tuple, …, tuple] with as many tuples as the request implies. A tuple represents one of the nearest points associated with one value taken from lon/lat. Each tuple as the form (i, j).

Dimensions with a length of one are removed except if squeeze is False. If squeeze is True and if request implies only one nearest point, the list item of the general output form is replaced by the tuple item; if length of lon/lat is one, the output is directly the list item of the general output form. Hence, if length of lon/lat is one and the request implies only one point, the output is a tuple.

In case of a simple square request, output is actually an array. Otherwise, the output is as described (it cannot be an array because the number of nearest points can vary with the entry point).

point_is_inside_domain_ij(i, j, margin=-0.1)[source]

Returns True if the point(s) of lon/lat coordinates is(are) inside the field.

Parameters:
  • i – X index of point in the 2D matrix of gridpoints
  • j – Y index of point in the 2D matrix of gridpoints
  • margin – DEPRECATED
point_is_inside_domain_ll(lon, *_, **__)[source]

Returns True if the point(s) of lon/lat coordinates is(are) inside the field. This is always the case in Gauss grids, no real meaning.

Parameters:
  • lon – longitude of the point in degrees
  • lat – latitude of the point in degrees
  • margin – considers the point inside if at least ‘margin’ points far from the border. The -0.1 default is a safety for precision errors.
  • position – position of the grid with respect to the model cell. Defaults to self.position_on_horizontal_grid.
position_on_horizontal_grid

Undocumented footprint attribute

reproject_wind_on_lonlat(u, v, lon, lat, map_factor_correction=True, reverse=False)[source]

Reprojects a wind vector (u, v) on rotated/stretched sphere onto real sphere, i.e. with components on true zonal/meridian axes.

Parameters:
  • u – the u == zonal-on-the-grid component of wind
  • v – the v == meridian-on-the-grid component of wind
  • lon – longitudes of points in degrees
  • lat – latitudes of points in degrees
  • map_factor_correction – applies a correction of magnitude due to map factor.
  • reverse – if True, apply the reverse reprojection.

lon/lat are coordinates on real sphere.

reshape_data(data, first_dimension=None, d4=False)[source]

Returns a 2D data (horizontal dimensions) reshaped from 1D, according to geometry.

Parameters:
  • data – the 1D data (or 3D with a T and Z dimensions, or 2D with either a T/Z dimension, to be specified), of dimension concording with geometry. In case data is 3D, T must be first dimension and Z the second.
  • first_dimension – in case data is 2D, specify what is the first dimension of data among (‘T’, ‘Z’)
  • d4
    • if True, returned values are shaped in a 4 dimensions array
    • if False, shape of returned values is determined with respect to geometry
resolution_field(direction='meridian')[source]

Returns a field whose values are the local resolution in m.

Parameters:direction – among (‘zonal’, ‘meridian’), direction in which the resolution is computed.
resolution_field_from_stretching(*args, **kwargs)[source]

Returns a field which values are the local resolution computed as the nominal resolution stretched locally by the map factor.

resolution_j(j)[source]

Returns the average meridian resolution at longitude circle number j.

resolution_ll(lon, lat)[source]

Returns the average meridian resolution (worst directional resolution) at point position.

Parameters:
  • lon – longitude of the point in degrees
  • lat – latitude of the point in degrees
structure

Undocumented footprint attribute

vcoordinate

Undocumented footprint attribute

zonal_resolution_j(j)[source]

Returns the average zonal resolution at longitude circle number j.