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.AbstractGeometry.Geometry) - 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 0x74bef5539a80>]>>.

Constructor. See its footprint for arguments.

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, contourf_kw=None, pcolormesh_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, colorbar_kw={}, colorbar_legend=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’.

  • contourf_kw – kwargs to be passed to matplotlib’s ax.contourf(). Only for plot_method = ‘contourf’.

  • pcolormesh_kw – kwargs to be passed to matplotlib’s ax.pcolormesh(). Only for plot_method = ‘pcolormesh’.

  • 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 map 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)

  • colorbar_kw – kwargs to be passed to matpltolib’s colorbar()

  • colorbar_legend – legend for the colorbar; mutually exclusive with arg ‘minmax_along_colorbar’

  • 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, extent='focus')

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

(see the documentation above for more details).

extract_contour(level)[source]

Return the intersection of the plan level and the H2Dfield: the result is a list of (lon,lat) point list. The length of the first list is the number of disjoint lines. This function relies on the contourpy library which is expected to be installed by the user.

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

Extract a point as a PointField.

Cf. getvalue_ll() doc for other arguments.

fid

(see the documentation above for more details).

geometry

Geometry defining the position of the field gridpoints (see the documentation above for more details).

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

Returns self. Useless but for compatibility reasons.

misc_metadata

(see the documentation above for more details).

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

processtype

Generating process (see the documentation above for more details).

spectral_geometry

For a spectral field, its spectral geometry handles spectral transforms and dimensions (see the documentation above for more details).

structure

Type of Field geometry (see the documentation above for more details).

units

(see the documentation above for more details).

validity

Validity of the field (see the documentation above for more details).