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.

Note

This class is managed by footprint.

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

Automatic parameters from the footprint:

  • comment (builtins.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.
  • misc_metadata (footprints.stdtypes.FPDict) - rwd - Not documented, sorry.
    • Optional. Default is FPDict::<<as_dict:: dict()>>.
  • processtype (builtins.str) - rwx - 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 (builtins.str) - rxx - Type of Field geometry.
    • Values: set([‘H2D’])
  • units (builtins.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 0x7f60a500d7b8>]>>.

Constructor. See its footprint for arguments.

animate_plot(maplib, title='__auto__', repeat=False, interval=1000, **kwargs)

Note

Requires plugin: with_basemap (config.activate_plugins)

Note

Deprecated since version 1.3.11: Animations shall be made externally.

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

In addition to those specified below, all plot method (cartoplot/basemap_plot) arguments can be provided.

Parameters:
  • maplib – map library to be used: ‘cartopy’/’basemap’ (basemap is deprecated!)
  • 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
basemap_plot(subzone=None, title=None, gisquality='i', specificproj=None, zoom=None, over=(None, None), colorbar_over=None, use_basemap=None, minmax=None, graphicmode='colorshades', levelsnumber=21, colormap='jet', center_cmap_on_0=False, drawrivers=False, drawcoastlines=True, drawcountries=True, meridians='auto', parallels='auto', colorbar='right', minmax_in_title=True, departments=False, boundariescolor='0.25', pointsize=20, contourcolor='blue', contourwidth=1, contourlabel=True, bluemarble=0.0, background=False, mask_threshold=None, contourlabelfmt='%0i', pointsmarker=', ', 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, force_colorbar_ticks_positions=None, force_colorbar_ticks_labels=None)

Note

Requires plugin: with_basemap (config.activate_plugins)

Note

Deprecated since version 1.3.9: (cf. cartoplot())

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

Parameters:
  • 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,

    **kwargs)
  • force_colorbar_ticks_position – as a list, or ‘center’ to center it between the color shifting levels of the colormap
  • force_colorbar_ticks_labels – as a list

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

cartoplot(fig=None, ax=None, figsize=(16.0, 12.0), rcparams=[(('font',), {'family': 'serif'})], title=None, projection=None, subzone=None, extent='__default__', plot_method='__default__', minmax=None, mask_threshold=None, scatter_kw=None, contour_kw=None, contourlabel=False, clabel_kw=None, meridians='auto', parallels='auto', gridlines_kw=None, cartopy_features=[], natural_earth_features='__default__', epygram_departments=False, colormap_helper=None, colormap='plasma', colorbounds=None, colorsnumber=None, colorstep=None, center_cmap_on_0=False, contourcolor='blue', colorbar='right', colorbar_over=None, colorbar_ax_kw=None, minmax_along_colorbar=True, takeover=False)

Note

Requires plugin: with_cartopy (config.activate_plugins)

Plot field with cartopy. Returns (figure, axis).

Figure settings:

Parameters:
  • fig – any existing figure to be used for the plot. A matplotlib figure is a frame containing eventually several subplots (axes).
  • ax – any existing axis to be used to plot on. A matplotlib axis is the subplot on which the drawing is done. If given, fig and ax must be consistent, i.e. ax being one of the fig axes.
  • figsize – figure sizes in inches, e.g. (5, 8.5). Default figsize is config.plotsizes.
  • rcparams – list of (*args, **kwargs) to be passed to pyplot.rc() defaults to [((‘font’,), dict(family=’serif’)),]
  • title – title for the plot. Default is field identifier and validity.

Geometry settings:

Parameters:
  • projection – a cartopy.crs projection to be used for plot. Defaults to the field.geometry.default_cartopy_CRS()
  • subzone – [LAM fields only] among (‘C’, ‘CI’), plots the data resp. on the C or C+I zone. Default is no subzone, i.e. the whole field.
  • extent – tune the extent of the map. Among (‘focus’, ‘global’, ‘__default__’). ‘focus’ will focus on the field geometry extent. ‘global’ will de-zoom to have the whole globe, if possible (call cartopy GeoAxes.set_global()). ‘__default__’ will choose one of these depending on the geometry.

Graphical settings:

Parameters:
  • plot_method – choice of the matplotlib plotting function to be used, among (‘contourf’, ‘contour’, ‘scatter’, ‘pcolormesh’, None). If None, prepare the blank figure, but skip actual plot. Default is ‘pcolormesh’ if the geometry is “meshable”, else ‘contourf’.
  • minmax – defines the min and max values for the plot colorbar. Syntax: [min, max]. Strings ‘min’ and ‘max’ (default) will take the min and max of the field.
  • mask_threshold – dict with min and/or max value(s) to mask outside.
  • scatter_kw – kwargs to be passed to matplotlib’s ax.scatter(). Only for plot_method = ‘scatter’.
  • contour_kw – kwargs to be passed to matplotlib’s ax.contour(). Only for plot_method = ‘contour’.
  • contourlabel – displays labels on contours. Only for plot_method = ‘contour’.
  • clabel_kw – kwargs to be passed to matplotlib’s ax.clabel(). Only for plot_method = ‘contour’.

Cartography settings:

Parameters:
  • meridians –

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

    • ’auto’: automatic scaling to the basemap extents
    • ’default’: every 10 degree
    • a list of values
    • a grid step, e.g. 5 to plot each 5 degree.
    • None: no one is plot
  • parallels – cf. meridians
  • gridlines_kw – graphical characteristics of meridians/parallels, arguments to be passed to cartopy’s ax.gridlines(…)
  • cartopy_features – list of cartopy.feature.??? features.
  • natural_earth_features – list of dicts, each of them containing arguments to instanciate a cartopy.feature.NaturalEarthFeature(…). E.g. [dict(category=’cultural’, name=’admin_1_states_provinces’, facecolor=’none’, linestyle=’:’),] will add states/departments/provinces. Cf. https://scitools.org.uk/cartopy/docs/latest/matplotlib/feature_interface.html#cartopy.feature.NaturalEarthFeature for details.
  • epygram_departments – add high-resolution french departments limits stored in epygram. May be a dict containing lines plotting arguments, such as linewidth etc… Warning: not consistent with natural_earth_features !

Colormap settings:

Parameters:
  • colormap_helper – an instance of the class epygram.colormapping.ColormapHelper. Has priority on the following arguments.
  • colormap – name of the matplotlib colormap to use (or an epygram one, or a user-defined one, cf. config.usercolormaps).
  • colorbounds – levels on which to shift color.
  • colorsnumber – number of levels for contours and colorbar.
  • colorstep – step in value between two color shift.
  • center_cmap_on_0 – aligns the colormap center on the value 0.
  • contourcolor – color or colormap to be used for ‘contourlines’ plot_method. It can be either a legal html color name, or a colormap name.

Colorbar settings:

Parameters:
  • colorbar – if False, hide colorbar the plot; else, defines the colorbar position, among (‘bottom’, ‘right’). Defaults to ‘right’.
  • colorbar_over – an optional existing ax to plot the colorbar on.
  • colorbar_ax_kw – kwargs to be passed to make_axes_locatable(ax).append_axes(colorbar, **kwargs)
  • minmax_along_colorbar – if True and minmax is not None, adds min and max values along colorbar.

Takeover:

Parameters:takeover – give the user more access to the objects used in the plot, by returning a dict containing them instead of only fig/ax
cartoplot_background(ax, projection, cartopy_features=[], natural_earth_features='__default__', meridians='auto', parallels='auto', gridlines_kw=None, epygram_departments=False, subzone=None)

Note

Requires plugin: with_cartopy (config.activate_plugins)

Set cartography features, such as borders, coastlines, meridians and parallels…

cartoplot_fig_init(fig=None, ax=None, projection=None, figsize=(16.0, 12.0), rcparams=[(('font',), {'family': 'serif'})], set_global=False)

Note

Requires plugin: with_cartopy (config.activate_plugins)

Consistently set figure, ax and projection.

comment

Undocumented footprint attribute

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

Extract a point as a PointField.

Cf. getvalue_ll() doc for other arguments.

fid

Undocumented footprint attribute

geometry

Undocumented footprint attribute

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

Returns self. Useless but for compatibility reasons.

misc_metadata

Undocumented footprint attribute

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

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

Parameters:
  • 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(*args, **kwargs)

Note

Requires plugin: with_basemap (config.activate_plugins)

Proxy to animate_plot().

plotfield(*args, **kwargs)

Note

Requires plugin: with_basemap (config.activate_plugins)

Proxy to basemap_plot().

processtype

Undocumented footprint attribute

spectral_geometry

Undocumented footprint attribute

structure

Undocumented footprint attribute

units

Undocumented footprint attribute

validity

Undocumented footprint attribute