MapPanel#

class metpy.plots.MapPanel(**kwargs: Any)[source]#

Set figure related elements for an individual panel.

Parameters that need to be set include collecting all plotting types (e.g., contours, wind barbs, etc.) that are desired to be in a given panel. Additionally, traits can be set to plot map related features (e.g., coastlines, borders), projection, graphics area, and title.

Attributes Summary

`area`	A tuple or string value that indicates the graphical area of the plot.
`ax`	Get the `matplotlib.axes.Axes` to draw on.
`cross_validation_lock`	A contextmanager for running a block with our cross validation lock set to True.
`layers`	A list of strings for a pre-defined feature layer or a Cartopy Feature object.
`layers_alpha`	A list of values defining the alpha for a layer.
`layers_edgecolor`	A list of strings for a pre-defined edgecolor for a layer.
`layers_linestyle`	A list of string values defining the linestyle for a layer or None.
`layers_linewidth`	A list of values defining the linewidth for a layer.
`layers_zorder`	A list of values defining the zorder for a layer.
`layout`	A tuple that contains the description (nrows, ncols, index) of the panel position; default value is (1, 1, 1).
`left_title`	A string to set a title for the figure with the location on the top left of the figure.
`mpl_args`	Supply a dictionary of valid Matplotlib keyword arguments to modify how the plot variable is drawn.
`parent`	A trait whose value must be an instance of a specified class.
`plots`	A list of handles that represent the plots (e.g., `ContourPlot`, `FilledContourPlot`, `ImagePlot`) to put on a given panel.
`projection`	A string for a pre-defined projection or a Cartopy projection object.
`right_title`	A string to set a title for the figure with the location on the top right of the figure.
`title`	A string to set a title for the figure.
`title_fontsize`	An integer or string value for the font size of the title of the figure.

Methods Summary

`__init__`(args, *kwargs)
`add_traits`(**traits)	Dynamically add trait attributes to the HasTraits instance.
`class_own_trait_events`(name)	Get a dict of all event handlers defined on this class, not a parent.
`class_own_traits`(**metadata)	Get a dict of all the traitlets defined on this class, not a parent.
`class_trait_names`(**metadata)	Get a list of all the names of this class' traits.
`class_traits`(**metadata)	Get a `dict` of all the traits of this class.
`copy`()	Return a copy of the panel.
`draw`()	Draw the panel.
`has_trait`(name)	Returns True if the object has a trait with the specified name.
`hold_trait_notifications`()	Context manager for bundling trait change notifications and cross validation.
`notify_change`(change)	Notify observers of a change event
`observe`(handler[, names, type])	Setup a handler to be called when a trait changes.
`on_trait_change`([handler, name, remove])	DEPRECATED: Setup a handler to be called when a trait changes.
`refresh`(changed)	Refresh the drawing if necessary.
`set_trait`(name, value)	Forcibly sets trait attribute, including read-only attributes.
`setup_instance`(**kwargs)	This is called before self.__init__ is called.
`trait_defaults`(names, *metadata)	Return a trait's default value or a dictionary of them
`trait_events`([name])	Get a `dict` of all the event handlers of this class.
`trait_has_value`(name)	Returns True if the specified trait has a value.
`trait_metadata`(traitname, key[, default])	Get metadata values for trait by key.
`trait_names`(**metadata)	Get a list of all the names of this class' traits.
`trait_values`(**metadata)	A `dict` of trait names and their values.
`traits`(**metadata)	Get a `dict` of all the traits of this class.
`unobserve`(handler[, names, type])	Remove a trait change handler.
`unobserve_all`([name])	Remove trait change handlers of any type for the specified name.

Attributes Documentation

area#

A tuple or string value that indicates the graphical area of the plot.

The tuple value corresponds to longitude/latitude box based on the projection of the map with the format (west-most longitude, east-most longitude, south-most latitude, north-most latitude). This tuple defines a box from the lower-left to the upper-right corner.

This trait can also be set with a string value associated with the named geographic regions within MetPy. The tuples associated with the names are based on a PlatteCarree projection. For a CONUS region, the following strings can be used: ‘us’, ‘spcus’, ‘ncus’, and ‘afus’. For regional plots, US postal state abbreviations can be used, such as ‘co’, ‘ny’, ‘ca’, et cetera. Providing a ‘+’ or ‘-’ suffix to the string value will zoom in or out, respectively. Providing multiple ‘+’ or ‘-’ characters will zoom in or out further.

ax[source]#

Get the matplotlib.axes.Axes to draw on.

Creates a new instance if necessary.

cross_validation_lock#

A contextmanager for running a block with our cross validation lock set to True.

At the end of the block, the lock’s value is restored to its value prior to entering the block.

layers#

A list of strings for a pre-defined feature layer or a Cartopy Feature object.

Like the projection, there are a couple of pre-defined feature layers that can be called using a short name. The pre-defined layers are: ‘coastline’, ‘states’, ‘borders’, ‘lakes’, ‘land’, ‘ocean’, ‘rivers’, ‘usstates’, and ‘uscounties’. Additionally, this can accept Cartopy Feature objects.

layers_alpha#

A list of values defining the alpha for a layer.

An option to set a different alpha for the map layer edge colors. Length of list should match that of layers if not using default value. Behavior is to repeat alpha if not enough provided by user.

layers_edgecolor#

A list of strings for a pre-defined edgecolor for a layer.

An option to set a different color for the map layer edge colors. Length of list should match that of layers if not using default value. Behavior is to repeat colors if not enough provided by user. Use None value for ‘ocean’, ‘lakes’, ‘rivers’, and ‘land’.

layers_linestyle#

A list of string values defining the linestyle for a layer or None.

Default is solid, which, will use a solid lines for drawing the layer. Behavior is to repeat linestyle if not enough provided by user.

The valid string values are those of Matplotlib which are ‘solid’, ‘dashed’, ‘dotted’, and ‘dashdot’, as well as their short codes (‘-’, ‘–’, ‘.’, ‘-.’). The object None, as described above, can also be used. Use None value for ‘ocean’, ‘lakes’, ‘rivers’, and ‘land’.

layers_linewidth#

A list of values defining the linewidth for a layer.

An option to set a different linewidth for the layer feature. Length of list should match that of layers if not using default value. Behavior is to repeat linewidth if not enough provided by user. Use None value for ‘ocean’, ‘lakes’, ‘rivers’, and ‘land’.

layers_zorder#

A list of values defining the zorder for a layer.

An option to set a different zorder for the map layer edge colors. Length of list should match that of layers if not using default value. Behavior is to repeat zorder if not enough provided by user.

layout#

A tuple that contains the description (nrows, ncols, index) of the panel position; default value is (1, 1, 1).

This trait is set to describe the panel position and the default is for a single panel. For example, a four-panel plot will have two rows and two columns with the tuple setting for the upper-left panel as (2, 2, 1), upper-right as (2, 2, 2), lower-left as (2, 2, 3), and lower-right as (2, 2, 4). For more details see the documentation for matplotlib.figure.Figure.add_subplot.

left_title#

A string to set a title for the figure with the location on the top left of the figure.

This trait sets a user-defined title that will plot at the top left of the figure.

mpl_args#

Supply a dictionary of valid Matplotlib keyword arguments to modify how the plot variable is drawn.

Using this attribute you must choose the appropriate keyword arguments (kwargs) based on what you are plotting (e.g., contours, color-filled contours, image plot, etc.). This is available for all plot types (ContourPlot, FilledContourPlot, RasterPlot, ImagePlot, BarbPlot, ArrowPlot, PlotGeometry, and PlotObs). For PlotObs, the kwargs are those to specify the StationPlot object. NOTE: Setting the mpl_args trait will override any other trait that corresponds to a specific kwarg for the particular plot type (e.g., linecolor, linewidth).

parent#

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

plots#

A list of handles that represent the plots (e.g., ContourPlot, FilledContourPlot, ImagePlot) to put on a given panel.

This trait collects the different plots, including contours and images, that are intended for a given panel.

projection#

A string for a pre-defined projection or a Cartopy projection object.

There are three pre-defined projections that can be called with a short name: Lambert conformal conic (‘lcc’), Mercator (‘mer’), or polar-stereographic (‘ps’), or ‘area’ to use a default projection based on the string area used. Additionally, this trait can be set to a Cartopy projection object.

right_title#

A string to set a title for the figure with the location on the top right of the figure.

This trait sets a user-defined title that will plot at the top right of the figure.

title#

A string to set a title for the figure.

This trait sets a user-defined title that will plot at the top center of the figure.

title_fontsize#

An integer or string value for the font size of the title of the figure.

This trait sets the font size for the title that will plot at the top center of the figure. Accepts size in points or relative size. Allowed relative sizes are those of Matplotlib: ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’.

Methods Documentation

__init__(*args: Any, **kwargs: Any) → None#

add_traits(**traits: Any) → None#: Dynamically add trait attributes to the HasTraits instance.

classmethod class_own_trait_events(name: str) → dict[str, EventHandler]#

Get a dict of all event handlers defined on this class, not a parent.

Works like event_handlers, except for excluding traits from parents.

classmethod class_own_traits(**metadata: Any) → dict[str, TraitType[Any, Any]]#

Get a dict of all the traitlets defined on this class, not a parent.

Works like class_traits, except for excluding traits from parents.

classmethod class_trait_names(**metadata: Any) → list[str]#

Get a list of all the names of this class’ traits.

This method is just like the trait_names() method, but is unbound.

classmethod class_traits(**metadata: Any) → dict[str, TraitType[Any, Any]]#

Get a dict of all the traits of this class. The dictionary is keyed on the name and the values are the TraitType objects.

This method is just like the traits() method, but is unbound.

The TraitTypes returned don’t know anything about the values that the various HasTrait’s instances are holding.

The metadata kwargs allow functions to be passed in which filter traits based on metadata values. The functions should take a single value as an argument and return a boolean. If any function returns False, then the trait is not included in the output. If a metadata key doesn’t exist, None will be passed to the function.

copy()[source]#: Return a copy of the panel.

draw()[source]#: Draw the panel.

has_trait(name: str) → bool#: Returns True if the object has a trait with the specified name.

hold_trait_notifications() → Any#

Context manager for bundling trait change notifications and cross validation.

Use this when doing multiple trait assignments (init, config), to avoid race conditions in trait notifiers requesting other trait values. All trait notifications will fire after all values have been assigned.

notify_change(change: Bunch) → None#: Notify observers of a change event

observe(handler: Callable[[...], Any], names: Sentinel | str | Iterable[Sentinel | str] = traitlets.All, type: Sentinel | str = 'change') → None#

Setup a handler to be called when a trait changes.

This is used to setup dynamic notifications of trait changes.

Parameters:

handler (callable) – A callable that is called when a trait changes. Its signature should be handler(change), where change is a dictionary. The change dictionary at least holds a ‘type’ key. * type: the type of notification. Other keys may be passed depending on the value of ‘type’. In the case where type is ‘change’, we also have the following keys: * owner : the HasTraits instance * old : the old value of the modified trait attribute * new : the new value of the modified trait attribute * name : the name of the modified trait attribute.
names (list, str, All) – If names is All, the handler will apply to all traits. If a list of str, handler will apply to all names in the list. If a str, the handler will apply just to that name.
type (str, All (default: 'change')) – The type of notification to filter by. If equal to All, then all notifications are passed to the observe handler.

on_trait_change(handler: EventHandler | None = None, name: Sentinel | str | None = None, remove: bool = False) → None#

DEPRECATED: Setup a handler to be called when a trait changes.

This is used to setup dynamic notifications of trait changes.

Static handlers can be created by creating methods on a HasTraits subclass with the naming convention ‘_[traitname]_changed’. Thus, to create static handler for the trait ‘a’, create the method _a_changed(self, name, old, new) (fewer arguments can be used, see below).

If remove is True and handler is not specified, all change handlers for the specified name are uninstalled.

Parameters:

handler (callable, None) – A callable that is called when a trait changes. Its signature can be handler(), handler(name), handler(name, new), handler(name, old, new), or handler(name, old, new, self).
name (list, str, None) – If None, the handler will apply to all traits. If a list of str, handler will apply to all names in the list. If a str, the handler will apply just to that name.
remove (bool) – If False (the default), then install the handler. If True then unintall it.

refresh(changed)[source]#: Refresh the drawing if necessary.

set_trait(name: str, value: Any) → None#: Forcibly sets trait attribute, including read-only attributes.

setup_instance(**kwargs: Any) → None#: This is called before self.__init__ is called.

trait_defaults(*names: str, **metadata: Any) → dict[str, Any] | Sentinel#

Return a trait’s default value or a dictionary of them

Notes

Dynamically generated default values may depend on the current state of the object.

classmethod trait_events(name: str | None = None) → dict[str, EventHandler]#

Get a dict of all the event handlers of this class.

Parameters:: name (str (default: None)) – The name of a trait of this class. If name is None then all the event handlers of this class will be returned instead.
Returns:: The event handlers associated with a trait name, or all event handlers.

trait_has_value(name: str) → bool#

Returns True if the specified trait has a value.

This will return false even if getattr would return a dynamically generated default value. These default values will be recognized as existing only after they have been generated.

Example

class MyClass(HasTraits):
    i = Int()


mc = MyClass()
assert not mc.trait_has_value("i")
mc.i  # generates a default value
assert mc.trait_has_value("i")

trait_metadata(traitname: str, key: str, default: Any = None) → Any#: Get metadata values for trait by key.

trait_names(**metadata: Any) → list[str]#: Get a list of all the names of this class’ traits.

trait_values(**metadata: Any) → dict[str, Any]#

A dict of trait names and their values.

The metadata kwargs allow functions to be passed in which filter traits based on metadata values. The functions should take a single value as an argument and return a boolean. If any function returns False, then the trait is not included in the output. If a metadata key doesn’t exist, None will be passed to the function.

Returns:: A dict of trait names and their values.

Notes

Trait values are retrieved via getattr, any exceptions raised by traits or the operations they may trigger will result in the absence of a trait value in the result dict.

traits(**metadata: Any) → dict[str, TraitType[Any, Any]]#

Get a dict of all the traits of this class. The dictionary is keyed on the name and the values are the TraitType objects.

The TraitTypes returned don’t know anything about the values that the various HasTrait’s instances are holding.

The metadata kwargs allow functions to be passed in which filter traits based on metadata values. The functions should take a single value as an argument and return a boolean. If any function returns False, then the trait is not included in the output. If a metadata key doesn’t exist, None will be passed to the function.

unobserve(handler: Callable[[...], Any], names: Sentinel | str | Iterable[Sentinel | str] = traitlets.All, type: Sentinel | str = 'change') → None#

Remove a trait change handler.

This is used to unregister handlers to trait change notifications.

Parameters:

handler (callable) – The callable called when a trait attribute changes.
names (list, str, All (default: All)) – The names of the traits for which the specified handler should be uninstalled. If names is All, the specified handler is uninstalled from the list of notifiers corresponding to all changes.
type (str or All (default: 'change')) – The type of notification to filter by. If All, the specified handler is uninstalled from the list of notifiers corresponding to all types.

unobserve_all(name: str | Any = traitlets.All) → None#: Remove trait change handlers of any type for the specified name. If name is not specified, removes all trait notifiers.