epygram.fields.H2DField — Horizontal 2-D Field class

Contains the class that handle a Horizontal 2D field.

class epygram.fields.H2DField.H2DField(*args, **kwargs)[source]

Bases: epygram.fields.D3Field.D3Field

Horizontal 2-Dimensions field class. A field is defined by its identifier ‘fid’, its data, its geometry (gridpoint and optionally spectral), and its validity.

The natural being of a field is gridpoint, so that: a field always has a gridpoint geometry, but it has a spectral geometry only in case it is spectral.


This class is managed by footprint.

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

Automatic parameters from the footprint:

  • comment (str) - rwd - Not documented, sorry.
    • Optional. Default is None.
  • fid (footprints.stdtypes.FPDict) - rwx - Not documented, sorry.
  • geometry (epygram.geometries.H2DGeometry.H2DGeometry) - rxx - Geometry defining the position of the field gridpoints.
  • processtype (str) - rxx - Generating process.
    • Optional. Default is None.
  • spectral_geometry (epygram.geometries.SpectralGeometry.SpectralGeometry) - rxx - For a spectral field, its spectral geometry handles spectral transforms and dimensions.
    • Optional. Default is None.
  • structure (str) - rxx - Type of Field geometry.
    • Values: set([‘H2D’])
  • units (str) - rwd - Not documented, sorry.
    • Optional. Default is ‘’.
  • validity (epygram.base.FieldValidityList) - rwx - Validity of the field.
    • Optional. Default is FieldValidityList::<<as_list:: [FieldValidity::<epygram.base.FieldValidity object at 0x7ffa493ca310>]>>.

Constructor. See its footprint for arguments.

extract_point(lon, lat, interpolation=u'nearest', external_distance=None)[source]

Extract a point as a PointField.

Cf. getvalue_ll() doc for other arguments.

getlevel(level=None, k=None)[source]

Returns self. Useless but for compatibility reasons.

morph_with_points(points, alpha=1.0, morphing=u'nearest', increment=False, **kwargs)[source]

Perturb the field values with the values of a set of points.

  • points – a list/fieldset of PointField.
  • alpha – is the blending value, ranging from 0. to 1.: e.g. with ‘nearest’ morphing, the final value of the point is alpha*point.value + (1-alpha)*original_field.value
  • morphing

    is the way the point modify the field:

    • ‘nearest’: only the nearest point is modified
    • ‘exp_decay’: modifies the surrounding points with an isotrop exponential decay weighting
    • ‘gaussian’: modifies the surrounding points with an isotrop gaussian weighting. Its standard deviation sigma must then be passed as argument, in meters. Weightingassumed to be 0. from 3*sigma.
  • increment – if True, the final value of the point is original_field.value + point.value
plotanimation(title=u'__auto__', repeat=False, interval=1000, **kwargs)[source]

Plot the field with animation with regards to time dimension. Returns a matplotlib.animation.FuncAnimation.

In addition to those specified below, all plotfield() method arguments can be provided.

  • title – title for the plot. ‘__auto__’ (default) will print the current validity of the time frame.
  • repeat – to repeat animation
  • interval – number of milliseconds between two validities
plotfield(subzone=None, title=None, gisquality=u'i', specificproj=None, zoom=None, over=(None, None), colorbar_over=None, use_basemap=None, minmax=None, graphicmode=u'colorshades', levelsnumber=21, colormap=u'jet', center_cmap_on_0=False, drawrivers=False, drawcoastlines=True, drawcountries=True, meridians=u'auto', parallels=u'auto', colorbar=u'right', minmax_in_title=True, departments=False, boundariescolor=u'0.25', pointsize=20, contourcolor=u'blue', contourwidth=1, contourlabel=True, bluemarble=0.0, background=False, mask_threshold=None, contourlabelfmt=u'%0i', pointsmarker=u', ', figsize=None, drawmapboundary_kwargs=None, fillcontinents_kwargs=None, drawcoastlines_kwargs=None, drawcountries_kwargs=None, drawparallels_kwargs=None, drawmeridians_kwargs=None, drawequator_kwargs=None, drawgreenwich_kwargs=None, rcparams=None, colorbar_ax_kwargs=None)[source]

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

  • subzone – among (‘C’, ‘CI’), for LAM fields only, plots the data resp. on the C or C+I zone. Default is no subzone, i.e. the whole field.
  • gisquality – among (‘c’, ‘l’, ‘i’, ‘h’, ‘f’) – by increasing quality. Defines the quality for GIS elements (coastlines, countries boundaries...).
  • 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.

  • zoom

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

    Overwrites specificproj.

  • over – any existing figure and/or ax to be used for the plot, given as a tuple (fig, ax), with None for missing objects. fig is the frame of the matplotlib figure, containing eventually several subplots (axes); ax is the matplotlib axes on which the drawing is done. When given (is not None), these objects must be coherent, i.e. ax being one of the fig axes.
  • colorbar_over – an optional existing ax to plot the colorbar on.
  • use_basemap – a basemap.Basemap object used to handle the projection of the map. If given, the map projection options (specificproj, zoom, gisquality ...) are ignored, keeping the properties of the use_basemap object.
  • title – title for the plot. Default is field identifier.
  • minmax

    defines the min and max values for the plot colorbar.

    Syntax: [min, max]. [0.0, max] also works. Default is min/max of the field.

  • graphicmode – among (‘colorshades’, ‘contourlines’, ‘points’).
  • levelsnumber – number of levels for contours and colorbar. (A list of levels also works).
  • colormap – name of the matplotlib colormap to use (or an epygram one, or a user-defined one, cf. config.usercolormaps).
  • center_cmap_on_0 – aligns the colormap center on the value 0.
  • drawrivers – to add rivers on map.
  • drawcoastlines – to add coast lines on map.
  • drawcountries – to add countries on map.
  • colorbar – if False, hide colorbar the plot; else, defines the colorbar position, among (‘bottom’, ‘right’). Defaults to ‘right’.
  • meridians

    enable to fine-tune the choice of lines to plot, with either:

    • ‘auto’: automatic scaling to the basemap extents
    • ‘default’: range(0,360,10)
    • a list of values
    • a grid step, e.g. 5 to plot each 5 degree.
    • None: no one is plot
    • meridians == ‘greenwich’ // ‘datechange’ // ‘greenwich+datechange’ or any combination (,) will plot only these.
  • parallels

    enable to fine-tune the choice of lines to plot, with either:

    • ‘auto’: automatic scaling to the basemap extents
    • ‘default’: range(-90,90,10)
    • a list of values
    • a grid step, e.g. 5 to plot each 5 degree.
    • None: no one is plot
    • ‘equator’ // ‘polarcircles’ // ‘tropics’ or any combination (,) will plot only these.
  • minmax_in_title – if True and minmax is not None, adds min and max values in title.
  • departments – if True, adds the french departments on map (instead of countries).
  • boundariescolor – color of lines for boundaries (countries, departments, coastlines)
  • pointsize – size of points for graphicmode == ‘points’.
  • contourcolor – color or colormap to be used for ‘contourlines’ graphicmode. It can be either a legal html color name, or a colormap name.
  • contourwidth – width of contours for ‘contourlines’ graphicmode.
  • contourlabel – displays labels on contours.
  • bluemarble – if > 0.0 (and <=1.0), displays NASA’s “blue marble” as background. The numerical value sets its transparency.
  • background – if True, set a background color to continents and oceans.
  • mask_threshold – dict with min and/or max value(s) to mask outside.
  • contourlabelfmt – format of the contour labels: e.g. 273.15 will appear: ‘%0i’ => 273, ‘%0f’ => 273.150000, ‘%0.2f’ => 273.15, ‘%04i’ => 0273, ‘%0.5e’ => 2.731500e+02
  • pointsmarker – shape of the points if graphicmode=’points’. Cf. matplotlib.scatter() for possible markers.
  • figsize – figure sizes in inches, e.g. (5, 8.5). Default figsize is config.plotsizes.
  • drawmapboundary_kwargs – kwargs to be passed to basemap.drawmapboundary()
  • fillcontinents_kwargs – kwargs to be passed to basemap.fillcontinents()
  • drawcoastlines_kwargs – kwargs to be passed to basemap.drawcoastlines()
  • drawcountries_kwargs – kwargs to be passed to basemap.drawcountries()
  • drawparallels_kwargs – kwargs to be passed to basemap.drawparallels()
  • drawmeridians_kwargs – kwargs to be passed to basemap.drawgreenwich()
  • drawequator_kwargs – draw kwargs to emphasize equator parallel
  • drawgreenwich_kwargs – draw kwargs to emphasize greenwich meridian
  • rcparams – list of (*args, **kwargs) to be passed to pyplot.rc() defaults to [((‘font’,), dict(family=’serif’)),]
  • colorbar_ax_kwargs

    kwargs to be passed to make_axes_locatable(ax).append_axes(colorbar,


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