Horizontal transects for maps.

Formatoption classes:

`HorizontalTransect`(key[, plotter, ...])	Transect along a vertical level
`HorizontalTransectLonLatBox`(key[, plotter, ...])
`HorizontalTransectVector`(key[, plotter, ...])
`MapTransectDataGrid`(args, *kwargs)
`MapTransectMapPlot2D`(args, *kwargs)

Plotter classes:

`HorizontalTransectCombinedPlotter`(*args, ...)
`HorizontalTransectFieldPlotter`(args, *kwargs)
`HorizontalTransectVectorPlotter`(args, *kwargs)

Classes:

HorizontalTransectPlotterMixin(*args, **kwargs)

class psy_transect.maps.HorizontalTransect(key, plotter=None, index_in_list=None, additional_children=[], additional_dependencies=[], **kwargs)

Bases: Formatoption

Transect along a vertical level

This formatoption takes a list of x-y tuples, the so-called transect, and extracts the raw data along this path.

Possible types

list of x-y tuples: The point coordinates of the transect.

Attributes:

`name`	`str`.
`priority`	`int`.

Methods:

`update`(value)	Method that is call to update the formatoption on the axes
`update_data_from_ds`(ds)

name = 'Transect within the raw data': str. A bit more verbose name than the formatoption key to be included in the gui. If None, the key is used in the gui

priority = 30

int. Priority value of the the formatoption determining when the formatoption is updated.

10: at the end (for labels, etc.)
20: before the plotting (e.g. for colormaps, etc.)
30: before loading the data (e.g. for lonlatbox)

update(value)

Method that is call to update the formatoption on the axes

Parameters:: value – Value to update

update_data_from_ds(ds)

class psy_transect.maps.HorizontalTransectCombinedPlotter(*args, **kwargs)

Bases: HorizontalTransectPlotterMixin, CombinedPlotter

Vector plot formatoptions:

`arrowsize`	Change the size of the arrows
`arrowstyle`	Change the style of the arrows
`density`	Change the density of the arrows

Axes formatoptions:

`background`	The background color for the matplotlib axes.
`tight`	Automatically adjust the plots.
`transpose`	Transpose the data before plotting

Color coding formatoptions:

`bounds`	Specify the boundaries of the colorbar
`cbar`	Specify the position of the colorbars
`cbarspacing`	Specify the spacing of the bounds in the colorbar
`cmap`	Specify the color map
`color`	Set the color for the arrows
`ctickprops`	Specify the font properties of the colorbar ticklabels
`cticksize`	Specify the font size of the colorbar ticklabels
`ctickweight`	Specify the fontweight of the colorbar ticklabels
`extend`	Draw arrows at the side of the colorbar
`levels`	The levels for the contour plot
`miss_color`	Set the color for missing values
`vbounds`	Specify the boundaries of the vector colorbar
`vcbar`	Specify the position of the vector plot colorbars
`vcbarspacing`	Specify the spacing of the bounds in the colorbar
`vcmap`	Specify the color map
`vctickprops`	Specify the font properties of the colorbar ticklabels
`vcticksize`	Specify the font size of the colorbar ticklabels
`vctickweight`	Specify the fontweight of the colorbar ticklabels

Label formatoptions:

`clabel`	Show the colorbar label
`clabelprops`	Properties of the Colorbar label
`clabelsize`	Set the size of the Colorbar label
`clabelweight`	Set the fontweight of the Colorbar label
`figtitle`	Plot a figure title
`figtitleprops`	Properties of the figure title
`figtitlesize`	Set the size of the figure title
`figtitleweight`	Set the fontweight of the figure title
`text`	Add text anywhere on the plot
`title`	Show the title
`titleprops`	Properties of the title
`titlesize`	Set the size of the title
`titleweight`	Set the fontweight of the title
`vclabel`	Show the colorbar label of the vector plot
`vclabelprops`	Properties of the Vector colorbar label
`vclabelsize`	Set the size of the Vector colorbar label
`vclabelweight`	Set the fontweight of the Vector colorbar label

Miscallaneous formatoptions:

`clat`	Set the center latitude of the plot
`clip`	Clip the part outside the latitudes of the map extent
`clon`	Set the center longitude of the plot
`datagrid`
`google_map_detail`	Show a map of google on the plot.
`grid_color`	Set the color of the grid
`grid_labels`	Display the labels of the grid
`grid_labelsize`	Modify the size of the grid tick labels
`grid_settings`	Modify the settings of the grid explicitly
`interp_bounds`	Interpolate grid cell boundaries for 2D plots
`linewidth`	Change the linewidth of the arrows
`lonlatbox`	Set the longitude-latitude box of the data shown
`lsm`	Draw the continents
`map_extent`	Set the extent of the map
`mask_datagrid`	Mask the datagrid where the array is NaN
`projection`	Specify the projection for the plot
`stock_img`	Display a stock image on the map
`transform`	Specify the coordinate system of the data
`vtransect`
`xgrid`	Draw vertical grid lines (meridians)
`ygrid`	Draw horizontal grid lines (parallels)

Axis tick formatoptions:

`cticklabels`	Specify the colorbar ticklabels
`cticks`	Specify the tick locations of the colorbar
`vcticklabels`	Specify the colorbar ticklabels
`vcticks`	Specify the tick locations of the vector colorbar

Masking formatoptions:

`mask`	Mask the data where a certain condition is True
`maskbetween`	Mask data points between two numbers
`maskgeq`	Mask data points greater than or equal to a number
`maskgreater`	Mask data points greater than a number
`maskleq`	Mask data points smaller than or equal to a number
`maskless`	Mask data points smaller than a number

Plot formatoptions:

`plot`
`vplot`	Choose the vector plot type

Post processing formatoptions:

`post`	Apply your own postprocessing script
`post_timing`	Determine when to run the `post` formatoption

Attributes:

`sliders`
`transect`

arrowsize

Change the size of the arrows

Possible types

None: make no scaling
float: Factor scaling the size of the arrows

arrowstyle

Change the style of the arrows

Possible types

str: Any arrow style string (see FancyArrowPatch)

Notes

This formatoption only has an effect for stream plots

background

The background color for the matplotlib axes.

Possible types

‘rc’: to use matplotlibs rc params
None: to use a transparent color
color: Any possible matplotlib color

bounds

Specify the boundaries of the colorbar

Possible types

None

make no normalization

numeric array

specifies the ticks manually

str or list [str, …]

A list of the below mentioned values of the mapping like [method, N, percmin, percmax, vmin, vmax], where only the first one is absolutely necessary

dict

Automatically determine the ticks corresponding to the data. The mapping can have the following keys, but only method is not optional.

N

An integer describing the number of boundaries (or ticks per power of ten, see log and symlog above)

percmin

The percentile to use for the minimum (by default, 0, i.e. the minimum of the array)

percmax

The percentile to use for the maximum (by default, 100, i.e. the maximum of the array)

vmin

The minimum to use (in which case it is not calculated from the specified method)

vmax

The maximum to use (in which case it is not calculated from the specified method)

method

A string that defines how minimum and maximum shall be set. This argument is not optional and can be one of the following:

data: plot the ticks exactly where the data is.
mid: plot the ticks in the middle of the data.
rounded: Sets the minimum and maximum of the ticks to the rounded data minimum or maximum. Ticks are rounded to the next 0.5 value with to the difference between data max- and minimum. The minimal tick will always be lower or equal than the data minimum, the maximal tick will always be higher or equal than the data maximum.
roundedsym: Same as rounded above but the ticks are chose such that they are symmetric around zero
minmax: Uses the minimum as minimal tick and maximum as maximal tick
sym: Same as minmax but symmetric around zero
log: Use logarithmic bounds. In this case, the given number N determines the number of bounds per power of tenth (i.e. N == 2 results in something like 1.0, 5.0, 10.0, 50.0, etc., If this second number is None, then it will be chosen such that we have around 11 boundaries but at least one per power of ten.
symlog: The same as log but symmetric around 0. If the number N is None, then we have around 12 boundaries but at least one per power of ten

int

Specifies how many ticks to use with the 'rounded' option. I.e. if integer i, then this is the same as ['rounded', i].

matplotlib.colors.Normalize

A matplotlib normalization instance

Examples

Plot 11 bounds over the whole data range:

>>> plotter.update(bounds='rounded')

which is equivalent to:

>>> plotter.update(bounds={'method': 'rounded'})

Plot 7 ticks over the whole data range where the maximal and minimal tick matches the data maximum and minimum:
```
>>> plotter.update(bounds=['minmax', 7])
```
which is equivaluent to:
```
>>> plotter.update(bounds={'method': 'minmax', 'N': 7})
```

chop the first and last five percentiles:

>>> plotter.update(bounds=['rounded', None, 5, 95])

which is equivalent to:

>>> plotter.update(bounds={'method': 'rounded', 'percmin': 5,
...                        'percmax': 95})

Plot 3 bounds per power of ten:
```
>>> plotter.update(bounds=['log', 3])
```

Plot continuous logarithmic bounds:

>>> from matplotlib.colors import LogNorm
>>> plotter.update(bounds=LogNorm())

See also

cmap: Specifies the colormap

cbar

Specify the position of the colorbars

Possible types

bool

True: defaults to ‘b’ False: Don’t draw any colorbar

str

The string can be a combination of one of the following strings: {‘fr’, ‘fb’, ‘fl’, ‘ft’, ‘b’, ‘r’, ‘sv’, ‘sh’}

‘b’, ‘r’ stand for bottom and right of the axes
‘fr’, ‘fb’, ‘fl’, ‘ft’ stand for bottom, right, left and top of the figure
‘sv’ and ‘sh’ stand for a vertical or horizontal colorbar in a separate figure

list

A containing one of the above positions

Examples

Draw a colorbar at the bottom and left of the axes:

>>> plotter.update(cbar='bl')

cbarspacing

Specify the spacing of the bounds in the colorbar

Possible types

str {‘uniform’, ‘proportional’}: if 'uniform', every color has exactly the same width in the colorbar, if 'proportional', the size is chosen according to the data

clabel

Show the colorbar label

Set the label of the colorbar. You can insert any meta key from the xarray.DataArray.attrs via a string like '%(key)s'. Furthermore there are some special cases:

Strings like '%Y', '%b', etc. will be replaced using the datetime.datetime.strftime() method as long as the data has a time coordinate and this can be converted to a datetime object.
'%(x)s', '%(y)s', '%(z)s', '%(t)s' will be replaced by the value of the x-, y-, z- or time coordinate (as long as this coordinate is one-dimensional in the data)
any attribute of one of the above coordinates is inserted via axis + key (e.g. the name of the x-coordinate can be inserted via '%(xname)s').
Labels defined in the psyplot.rcParams 'texts.labels' key are also replaced when enclosed by ‘{}’. The standard labels are
- tinfo: %H:%M
- dtinfo: %B %d, %Y. %H:%M
- dinfo: %B %d, %Y
- desc: %(long_name)s [%(units)s]
- sdesc: %(name)s [%(units)s]

Possible types

str: The title for the set_label() method.

clabelprops

Properties of the Colorbar label

Specify the font properties of the figure title manually.

Possible types

dict: Items may be any valid text property

See also

clabel, clabelsize, clabelweight

clabelsize

Set the size of the Colorbar label

Possible types

float: The absolute font size in points (e.g., 12)
string: Strings might be ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’.

See also

clabel, clabelweight, clabelprops

clabelweight

Set the fontweight of the Colorbar label

Possible types

float: a float between 0 and 1000
string: Possible strings are one of ‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’.

See also

clabel, clabelsize, clabelprops

clat

Set the center latitude of the plot

Parameters:

None – Let the lonlatbox formatoption determine the center
float – Specifiy the center manually
str – A pattern that matches any of the keys in the psyplot.rcParams 'extents.boxes' item (contains user-defined longitude-latitude boxes) or the psyplot.plotter.boxes.lonlatboxes dictionary (contains longitude-latitude boxes of different countries and continents)

clip

Clip the part outside the latitudes of the map extent

Possible types

None: Clip if all longitudes are shown (i.e. the extent goes from -180 to 180) and the projection is orthographic or stereographic
bool: True, clip, else, don’t

Notes

If the plot is clipped. You might need to update with replot=True!

clon

Set the center longitude of the plot

Parameters:

None – Let the lonlatbox formatoption determine the center
float – Specifiy the center manually
str – A pattern that matches any of the keys in the psyplot.rcParams 'extents.boxes' item (contains user-defined longitude-latitude boxes) or the psyplot.plotter.boxes.lonlatboxes dictionary (contains longitude-latitude boxes of different countries and continents)

cmap

Specify the color map

This formatoption specifies the color coding of the data via a matplotlib.colors.Colormap

Possible types

str

Strings may be any valid colormap name suitable for the matplotlib.cm.get_cmap() function or one of the color lists defined in the ‘colors.cmaps’ key of the psyplot.rcParams dictionary (including their reversed color maps given via the ‘_r’ extension).

matplotlib.colors.Colormap: The colormap instance to use

See also

bounds: specifies the boundaries of the colormap

color

Set the color for the arrows

This formatoption can be used to set a single color for the vectors or define the color coding

Possible types

float

Determines the greyness

color

Defines the same color for all arrows. The string can be either a html hex string (e.g. ‘#eeefff’), a single letter (e.g. ‘b’: blue, ‘g’: green, ‘r’: red, ‘c’: cyan, ‘m’: magenta, ‘y’: yellow, ‘k’: black, ‘w’: white) or any other color

string {‘absolute’, ‘u’, ‘v’}

Strings may define how the formatoption is calculated. Possible strings are

absolute: for the absolute wind speed
u: for the u component
v: for the v component

2D-array

The values determine the color for each plotted arrow. Note that the shape has to match the one of u and v.

cticklabels

Specify the colorbar ticklabels

Possible types

str: A formatstring like '%Y' for plotting the year (in the case that time is shown on the axis) or ‘%i’ for integers
array: An array of strings to use for the ticklabels

ctickprops

Specify the font properties of the colorbar ticklabels

Possible types

dict: Items may be anything of the matplotlib.pyplot.tick_params() function

cticks

Specify the tick locations of the colorbar

Possible types

None

use the default ticks

numeric array

specifies the ticks manually

str or list [str, …]

A list of the below mentioned values of the mapping like [method, N, percmin, percmax, vmin, vmax], where only the first one is absolutely necessary

dict

Automatically determine the ticks corresponding to the data. The mapping can have the following keys, but only method is not optional.

N

An integer describing the number of boundaries (or ticks per power of ten, see log and symlog above)

percmin

The percentile to use for the minimum (by default, 0, i.e. the minimum of the array)

percmax

The percentile to use for the maximum (by default, 100, i.e. the maximum of the array)

vmin

The minimum to use (in which case it is not calculated from the specified method)

vmax

The maximum to use (in which case it is not calculated from the specified method)

method

A string that defines how minimum and maximum shall be set. This argument is not optional and can be one of the following:

data: plot the ticks exactly where the data is.
mid: plot the ticks in the middle of the data.
rounded: Sets the minimum and maximum of the ticks to the rounded data minimum or maximum. Ticks are rounded to the next 0.5 value with to the difference between data max- and minimum. The minimal tick will always be lower or equal than the data minimum, the maximal tick will always be higher or equal than the data maximum.
roundedsym: Same as rounded above but the ticks are chose such that they are symmetric around zero
minmax: Uses the minimum as minimal tick and maximum as maximal tick
sym: Same as minmax but symmetric around zero
log: Use logarithmic bounds. In this case, the given number N determines the number of bounds per power of tenth (i.e. N == 2 results in something like 1.0, 5.0, 10.0, 50.0, etc., If this second number is None, then it will be chosen such that we have around 11 boundaries but at least one per power of ten.
symlog: The same as log but symmetric around 0. If the number N is None, then we have around 12 boundaries but at least one per power of ten
bounds: let the bounds keyword determine the ticks. An additional integer i may be specified to only use every i-th bound as a tick (see also int below)
midbounds: Same as bounds but in the middle between two bounds

int

Specifies how many ticks to use with the 'bounds' option. I.e. if integer i, then this is the same as ['bounds', i].

See also

cticklabels

cticksize

Specify the font size of the colorbar ticklabels

Possible types

float: The absolute font size in points (e.g., 12)
string: Strings might be ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’.

ctickweight

Specify the fontweight of the colorbar ticklabels

Possible types

float: a float between 0 and 1000
string: Possible strings are one of ‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’.

datagrid

density

Change the density of the arrows

Possible types

float: Scales the density of the arrows in x- and y-direction (1.0 means no scaling)
tuple (x, y): Defines the scaling in x- and y-direction manually

extend

Draw arrows at the side of the colorbar

Possible types

str {‘neither’, ‘both’, ‘min’ or ‘max’}: If not ‘neither’, make pointed end(s) for out-of-range values

figtitle

Plot a figure title

Set the title of the figure. You can insert any meta key from the xarray.DataArray.attrs via a string like '%(key)s'. Furthermore there are some special cases:

Strings like '%Y', '%b', etc. will be replaced using the datetime.datetime.strftime() method as long as the data has a time coordinate and this can be converted to a datetime object.
'%(x)s', '%(y)s', '%(z)s', '%(t)s' will be replaced by the value of the x-, y-, z- or time coordinate (as long as this coordinate is one-dimensional in the data)
any attribute of one of the above coordinates is inserted via axis + key (e.g. the name of the x-coordinate can be inserted via '%(xname)s').
Labels defined in the psyplot.rcParams 'texts.labels' key are also replaced when enclosed by ‘{}’. The standard labels are
- tinfo: %H:%M
- dtinfo: %B %d, %Y. %H:%M
- dinfo: %B %d, %Y
- desc: %(long_name)s [%(units)s]
- sdesc: %(name)s [%(units)s]

Possible types

str: The title for the suptitle() function

Notes

If the plotter is part of a psyplot.project.Project and multiple plotters of this project are on the same figure, the replacement attributes (see above) are joined by a delimiter. If the delimiter attribute of this Figtitle instance is not None, it will be used. Otherwise the rcParams[‘texts.delimiter’] item is used.
This is the title of the whole figure! For the title of this specific subplot, see the title formatoption.

figtitleprops

Properties of the figure title

Specify the font properties of the figure title manually.

Possible types

dict: Items may be any valid text property

figtitlesize

Set the size of the figure title

Possible types

float: The absolute font size in points (e.g., 12)
string: Strings might be ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’.

figtitleweight

Set the fontweight of the figure title

Possible types

float: a float between 0 and 1000
string: Possible strings are one of ‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’.

google_map_detail

Show a map of google on the plot.

Possible types

None: Do not show anything
int: The level of detail to show (usually between 6 and 9, must be greater than or equal to 0).

grid_color

Set the color of the grid

Possible types

None: Choose the default line color
color: Any valid color for matplotlib (see the matplotlib.pyplot.plot() documentation)

grid_labels

Display the labels of the grid

Possible types

None: Grid labels are draw if possible
bool: If True, labels are drawn and if this is not possible, a warning is raised

grid_labelsize

Modify the size of the grid tick labels

Possible types

float: The absolute font size in points (e.g., 12)
string: Strings might be ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’.

grid_settings

Modify the settings of the grid explicitly

Possible types

dict: Items may be any key-value-pair of the matplotlib.collections.LineCollection class

interp_bounds

Interpolate grid cell boundaries for 2D plots

This formatoption can be used to tell enable and disable the interpolation of grid cell boundaries. Usually, netCDF files only contain the centered coordinates. In this case, we interpolate the boundaries between the grid cell centers.

Possible types

None: Interpolate the boundaries, except for circumpolar grids
bool: If True (the default), the grid cell boundaries are inter- and extrapolated. Otherwise, if False, the coordinate centers are used and the default behaviour of matplotlib cuts of the most outer row and column of the 2D-data. Note that this results in a slight shift of the data

levels

The levels for the contour plot

This formatoption sets the levels for the filled contour plot and only has an effect if the plot Formatoption is set to 'contourf'

Possible types

None

Use the settings from the bounds formatoption and if this does not specify boundaries, use 11

numeric array

specifies the ticks manually

str or list [str, …]

A list of the below mentioned values of the mapping like [method, N, percmin, percmax, vmin, vmax], where only the first one is absolutely necessary

dict

Automatically determine the ticks corresponding to the data. The mapping can have the following keys, but only method is not optional.

N

An integer describing the number of boundaries (or ticks per power of ten, see log and symlog above)

percmin

The percentile to use for the minimum (by default, 0, i.e. the minimum of the array)

percmax

The percentile to use for the maximum (by default, 100, i.e. the maximum of the array)

vmin

The minimum to use (in which case it is not calculated from the specified method)

vmax

The maximum to use (in which case it is not calculated from the specified method)

method

A string that defines how minimum and maximum shall be set. This argument is not optional and can be one of the following:

data: plot the ticks exactly where the data is.
mid: plot the ticks in the middle of the data.
rounded: Sets the minimum and maximum of the ticks to the rounded data minimum or maximum. Ticks are rounded to the next 0.5 value with to the difference between data max- and minimum. The minimal tick will always be lower or equal than the data minimum, the maximal tick will always be higher or equal than the data maximum.
roundedsym: Same as rounded above but the ticks are chose such that they are symmetric around zero
minmax: Uses the minimum as minimal tick and maximum as maximal tick
sym: Same as minmax but symmetric around zero
log: Use logarithmic bounds. In this case, the given number N determines the number of bounds per power of tenth (i.e. N == 2 results in something like 1.0, 5.0, 10.0, 50.0, etc., If this second number is None, then it will be chosen such that we have around 11 boundaries but at least one per power of ten.
symlog: The same as log but symmetric around 0. If the number N is None, then we have around 12 boundaries but at least one per power of ten

int

Specifies how many ticks to use with the 'rounded' option. I.e. if integer i, then this is the same as ['rounded', i].

linewidth

Change the linewidth of the arrows

Possible types

float

give the linewidth explicitly

string {‘absolute’, ‘u’, ‘v’}

Strings may define how the formatoption is calculated. Possible strings are

absolute: for the absolute wind speed
u: for the u component
v: for the v component

tuple (string, float)

string may be one of the above strings, float may be a scaling factor

2D-array

The values determine the linewidth for each plotted arrow. Note that the shape has to match the one of u and v.

lonlatbox

Set the longitude-latitude box of the data shown

This formatoption extracts the data that matches the specified box.

Possible types

None: Use the full data
str: A pattern that matches any of the keys in the psyplot.rcParams 'extents.boxes' item (contains user-defined longitude-latitude boxes) or the psyplot.plotter.boxes.lonlatboxes dictionary (contains longitude-latitude boxes of different countries and continents)
[lonmin, lonmax, latmin, latmax]: The surrounding longitude-latitude that shall be used. Values can be either a float or a string as above

Notes

For only specifying the region of the plot, see the map_extent formatoption
If the coordinates are two-dimensional (e.g. for a circumpolar grid), than the data is not extracted but values outside the specified longitude-latitude box are set to NaN

See also

map_extent

lsm

Draw the continents

Possible types

bool

True: draw the coastlines with a line width of 1 False: don’t draw anything

float

Specifies the linewidth of the coastlines

str

The resolution of the land-sea mask (see the cartopy.mpl.geoaxes.GeoAxesSubplot.coastlines() method. Must be one of ('110m', '50m', '10m').

list [str or bool, float]

The resolution and the linewidth

dict

A dictionary with any of the following keys

coast: The color for the coastlines
land: The fill color for the continents
ocean: The fill color for the oceans
res: The resolution (see above)
linewidth: The linewidth of the coastlines (see above)

map_extent

Set the extent of the map

Possible types

None: The map extent is specified by the data (i.e. by the lonlatbox formatoption)
‘global’: The whole globe is shown
‘data’: The extent is set to the longitude-latitute box defined by the lonlatbox formatoption
str: A pattern that matches any of the keys in the psyplot.rcParams 'extents.boxes' item (contains user-defined longitude-latitude boxes) or the psyplot.plotter.boxes.lonlatboxes dictionary (contains longitude-latitude boxes of different countries and continents)
[lonmin, lonmax, latmin, latmax]: The surrounding longitude-latitude that shall be used. Values can be either a float or a string as above

Notes

This formatoption sets the extent of the plot. For choosing the region for the data, see the lonlatbox formatoption

See also

lonlatbox

mask

Mask the data where a certain condition is True

This formatoption can be used to mask the plotting data based on another array. This array can be the name of a variable in the base dataset, or it can be a numeric array. Note that the data needs to be on exactly the same coordinates as the data shown here

Possible types

None

Apply no mask

str

The name of a variable in the base dataset to use.

dimensions that are in the given mask but not in the visualized base variable will be aggregated using numpy.any()
if the given mask misses dimensions that are in the visualized data (i.e. the data of this plotter), we broadcast the mask to match the shape of the data
dimensions that are in mask and the base variable, but not in the visualized data will be matched against each other

str

The path to a netCDF file that shall be loaded

xr.DataArray or np.ndarray

An array that can be broadcasted to the shape of the data

mask_datagrid

Mask the datagrid where the array is NaN

This boolean formatoption enables to mask the grid of the datagrid formatoption where the data is NaN

Possible types

bool: Either True, to not display the data grid for cells with NaN, or False

See also

datagrid

maskbetween

Mask data points between two numbers

Possible types

float: The floating number to mask above

maskgeq

Mask data points greater than or equal to a number

Possible types

float: The floating number to mask above

maskgreater

Mask data points greater than a number

Possible types

float: The floating number to mask above

maskleq

Mask data points smaller than or equal to a number

Possible types

float: The floating number to mask below

maskless

Mask data points smaller than a number

Possible types

float: The floating number to mask below

miss_color

Set the color for missing values

Possible types

None: Use the default from the colormap
string, tuple.: Defines the color of the grid.

plot

post

Apply your own postprocessing script

This formatoption let’s you apply your own post processing script. Just enter the script as a string and it will be executed. The formatoption will be made available via the self variable

Possible types

None: Don’t do anything
str: The post processing script as string

Note

This formatoption uses the built-in exec() function to compile the script. Since this poses a security risk when loading psyplot projects, it is by default disabled through the Plotter.enable_post attribute. If you are sure that you can trust the script in this formatoption, set this attribute of the corresponding Plotter to True

Examples

Assume, you want to manually add the mean of the data to the title of the matplotlib axes. You can simply do this via

from psyplot.plotter import Plotter
from xarray import DataArray

plotter = Plotter(DataArray([1, 2, 3]))
# enable the post formatoption
plotter.enable_post = True
plotter.update(post="self.ax.set_title(str(self.data.mean()))")
plotter.ax.get_title()
"2.0"

By default, the post formatoption is only ran, when it is explicitly updated. However, you can use the post_timing formatoption, to run it automatically. E.g. for running it after every update of the plotter, you can set

plotter.update(post_timing="always")

See also

post_timing: Determine the timing of this formatoption

post_timing

Determine when to run the post formatoption

This formatoption determines, whether the post formatoption should be run never, after replot or after every update.

Possible types

‘never’: Never run post processing scripts
‘always’: Always run post processing scripts
‘replot’: Only run post processing scripts when the data changes or a replot is necessary

See also

post: The post processing formatoption

projection

Specify the projection for the plot

This formatoption defines the projection of the plot

Possible types

cartopy.crs.CRS

A cartopy projection instance (e.g. cartopy.crs.PlateCarree)

str

A string specifies the projection instance to use. The centered longitude and latitude are determined by the clon and clat formatoptions. Possible strings are (each standing for the specified projection)

cf	try to decode the CF-conventions
cyl	`cartopy.crs.PlateCarree`
robin	`cartopy.crs.Robinson`
moll	`cartopy.crs.Mollweide`
geo	`cartopy.crs.Geostationary`
northpole	`cartopy.crs.NorthPolarStereo`
southpole	`cartopy.crs.SouthPolarStereo`
ortho	`cartopy.crs.Orthographic`
stereo	`cartopy.crs.Stereographic`
near	`cartopy.crs.NearsidePerspective`
rotated	`cartopy.crs.RotatedPole`

The special case 'cf' tries to decode the CF-conventions in the data. If this is not possible, we assume a standard lat-lon projection ('cyl')

See also

Grid-mappings of cf-conventions

Warning

An update of the projection clears the axes!

sliders: Dict[Axes, Slider]

stock_img

Display a stock image on the map

This formatoption uses the cartopy.mpl.geoaxes.GeoAxes.stock_img() method to display a downsampled version of the Natural Earth shaded relief raster on the map

Possible types

bool: If True, the image is displayed

text

Add text anywhere on the plot

This formatoption draws a text on the specified position on the figure. You can insert any meta key from the xarray.DataArray.attrs via a string like '%(key)s'. Furthermore there are some special cases:

Strings like '%Y', '%b', etc. will be replaced using the datetime.datetime.strftime() method as long as the data has a time coordinate and this can be converted to a datetime object.
'%(x)s', '%(y)s', '%(z)s', '%(t)s' will be replaced by the value of the x-, y-, z- or time coordinate (as long as this coordinate is one-dimensional in the data)
any attribute of one of the above coordinates is inserted via axis + key (e.g. the name of the x-coordinate can be inserted via '%(xname)s').
Labels defined in the psyplot.rcParams 'texts.labels' key are also replaced when enclosed by ‘{}’. The standard labels are
- tinfo: %H:%M
- dtinfo: %B %d, %Y. %H:%M
- dinfo: %B %d, %Y
- desc: %(long_name)s [%(units)s]
- sdesc: %(name)s [%(units)s]

Possible types

str: If string s: this will be used as (1., 1., s, {‘ha’: ‘right’}) (i.e. a string in the upper right corner of the axes).
tuple or list of tuples (x,y,s[,coord.-system][,options]]): Each tuple defines a text instance on the plot. 0<=x, y<=1 are the coordinates. The coord.-system can be either the data coordinates (default, 'data') or the axes coordinates ('axes') or the figure coordinates (‘fig’). The string s finally is the text. options may be a dictionary to specify format the appearence (e.g. 'color', 'fontweight', 'fontsize', etc., see matplotlib.text.Text for possible keys). To remove one single text from the plot, set (x,y,’’[, coord.-system]) for the text at position (x,y)
empty list: remove all texts from the plot

See also

title, figtitle

tight

Automatically adjust the plots.

If set to True, the plots are automatically adjusted to fit to the figure limitations via the matplotlib.pyplot.tight_layout() function.

Possible types

bool: True for automatic adjustment

Warning

There is no update method to undo what happend after this formatoption is set to True!

title

Show the title

Set the title of the plot. You can insert any meta key from the xarray.DataArray.attrs via a string like '%(key)s'. Furthermore there are some special cases:

Strings like '%Y', '%b', etc. will be replaced using the datetime.datetime.strftime() method as long as the data has a time coordinate and this can be converted to a datetime object.
'%(x)s', '%(y)s', '%(z)s', '%(t)s' will be replaced by the value of the x-, y-, z- or time coordinate (as long as this coordinate is one-dimensional in the data)
any attribute of one of the above coordinates is inserted via axis + key (e.g. the name of the x-coordinate can be inserted via '%(xname)s').
Labels defined in the psyplot.rcParams 'texts.labels' key are also replaced when enclosed by ‘{}’. The standard labels are
- tinfo: %H:%M
- dtinfo: %B %d, %Y. %H:%M
- dinfo: %B %d, %Y
- desc: %(long_name)s [%(units)s]
- sdesc: %(name)s [%(units)s]

Possible types

str: The title for the title() function.

Notes

This is the title of this specific subplot! For the title of the whole figure, see the figtitle formatoption.

titleprops

Properties of the title

Specify the font properties of the figure title manually.

Possible types

dict: Items may be any valid text property

See also

title, titlesize, titleweight

titlesize

Set the size of the title

Possible types

float: The absolute font size in points (e.g., 12)
string: Strings might be ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’.

See also

title, titleweight, titleprops

titleweight

Set the fontweight of the title

Possible types

float: a float between 0 and 1000
string: Possible strings are one of ‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’.

See also

title, titlesize, titleprops

transect: HorizontalTransect

transform

Specify the coordinate system of the data

This formatoption defines the coordinate system of the data (usually we expect a simple latitude longitude coordinate system)

Possible types

cartopy.crs.CRS

A cartopy projection instance (e.g. cartopy.crs.PlateCarree)

str

A string specifies the projection instance to use. The centered longitude and latitude are determined by the clon and clat formatoptions. Possible strings are (each standing for the specified projection)

cf	try to decode the CF-conventions
cyl	`cartopy.crs.PlateCarree`
robin	`cartopy.crs.Robinson`
moll	`cartopy.crs.Mollweide`
geo	`cartopy.crs.Geostationary`
northpole	`cartopy.crs.NorthPolarStereo`
southpole	`cartopy.crs.SouthPolarStereo`
ortho	`cartopy.crs.Orthographic`
stereo	`cartopy.crs.Stereographic`
near	`cartopy.crs.NearsidePerspective`
rotated	`cartopy.crs.RotatedPole`

The special case 'cf' tries to decode the CF-conventions in the data. If this is not possible, we assume a standard lat-lon projection ('cyl')

See also

Grid-mappings of cf-conventions

transpose

Transpose the data before plotting

This formatoption can be used in case the data order of the variable dimensions is (x, y) instead of (y, x)

vbounds

Specify the boundaries of the vector colorbar

Possible types

None

make no normalization

numeric array

specifies the ticks manually

str or list [str, …]

A list of the below mentioned values of the mapping like [method, N, percmin, percmax, vmin, vmax], where only the first one is absolutely necessary

dict

Automatically determine the ticks corresponding to the data. The mapping can have the following keys, but only method is not optional.

N

An integer describing the number of boundaries (or ticks per power of ten, see log and symlog above)

percmin

The percentile to use for the minimum (by default, 0, i.e. the minimum of the array)

percmax

The percentile to use for the maximum (by default, 100, i.e. the maximum of the array)

vmin

The minimum to use (in which case it is not calculated from the specified method)

vmax

The maximum to use (in which case it is not calculated from the specified method)

method

A string that defines how minimum and maximum shall be set. This argument is not optional and can be one of the following:

data: plot the ticks exactly where the data is.
mid: plot the ticks in the middle of the data.
rounded: Sets the minimum and maximum of the ticks to the rounded data minimum or maximum. Ticks are rounded to the next 0.5 value with to the difference between data max- and minimum. The minimal tick will always be lower or equal than the data minimum, the maximal tick will always be higher or equal than the data maximum.
roundedsym: Same as rounded above but the ticks are chose such that they are symmetric around zero
minmax: Uses the minimum as minimal tick and maximum as maximal tick
sym: Same as minmax but symmetric around zero
log: Use logarithmic bounds. In this case, the given number N determines the number of bounds per power of tenth (i.e. N == 2 results in something like 1.0, 5.0, 10.0, 50.0, etc., If this second number is None, then it will be chosen such that we have around 11 boundaries but at least one per power of ten.
symlog: The same as log but symmetric around 0. If the number N is None, then we have around 12 boundaries but at least one per power of ten

int

Specifies how many ticks to use with the 'rounded' option. I.e. if integer i, then this is the same as ['rounded', i].

matplotlib.colors.Normalize

A matplotlib normalization instance

Examples

Plot 11 bounds over the whole data range:

>>> plotter.update(bounds='rounded')

which is equivalent to:

>>> plotter.update(bounds={'method': 'rounded'})

Plot 7 ticks over the whole data range where the maximal and minimal tick matches the data maximum and minimum:
```
>>> plotter.update(bounds=['minmax', 7])
```
which is equivaluent to:
```
>>> plotter.update(bounds={'method': 'minmax', 'N': 7})
```

chop the first and last five percentiles:

>>> plotter.update(bounds=['rounded', None, 5, 95])

which is equivalent to:

>>> plotter.update(bounds={'method': 'rounded', 'percmin': 5,
...                        'percmax': 95})

Plot 3 bounds per power of ten:
```
>>> plotter.update(bounds=['log', 3])
```

Plot continuous logarithmic bounds:

>>> from matplotlib.colors import LogNorm
>>> plotter.update(bounds=LogNorm())

See also

cmap: Specifies the colormap

vcbar

Specify the position of the vector plot colorbars

Possible types

bool

True: defaults to ‘b’ False: Don’t draw any colorbar

str

The string can be a combination of one of the following strings: {‘fr’, ‘fb’, ‘fl’, ‘ft’, ‘b’, ‘r’, ‘sv’, ‘sh’}

‘b’, ‘r’ stand for bottom and right of the axes
‘fr’, ‘fb’, ‘fl’, ‘ft’ stand for bottom, right, left and top of the figure
‘sv’ and ‘sh’ stand for a vertical or horizontal colorbar in a separate figure

list

A containing one of the above positions

vcbarspacing

Specify the spacing of the bounds in the colorbar

Possible types

str {‘uniform’, ‘proportional’}: if 'uniform', every color has exactly the same width in the colorbar, if 'proportional', the size is chosen according to the data

vclabel

Show the colorbar label of the vector plot

Set the label of the colorbar. You can insert any meta key from the xarray.DataArray.attrs via a string like '%(key)s'. Furthermore there are some special cases:

Strings like '%Y', '%b', etc. will be replaced using the datetime.datetime.strftime() method as long as the data has a time coordinate and this can be converted to a datetime object.
'%(x)s', '%(y)s', '%(z)s', '%(t)s' will be replaced by the value of the x-, y-, z- or time coordinate (as long as this coordinate is one-dimensional in the data)
any attribute of one of the above coordinates is inserted via axis + key (e.g. the name of the x-coordinate can be inserted via '%(xname)s').
Labels defined in the psyplot.rcParams 'texts.labels' key are also replaced when enclosed by ‘{}’. The standard labels are
- tinfo: %H:%M
- dtinfo: %B %d, %Y. %H:%M
- dinfo: %B %d, %Y
- desc: %(long_name)s [%(units)s]
- sdesc: %(name)s [%(units)s]

Possible types

str: The title for the set_label() method.

vclabelprops

Properties of the Vector colorbar label

Specify the font properties of the figure title manually.

Possible types

dict: Items may be any valid text property

vclabelsize

Set the size of the Vector colorbar label

Possible types

float: The absolute font size in points (e.g., 12)
string: Strings might be ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’.

vclabelweight

Set the fontweight of the Vector colorbar label

Possible types

float: a float between 0 and 1000
string: Possible strings are one of ‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’.

vcmap

Specify the color map

This formatoption specifies the color coding of the data via a matplotlib.colors.Colormap

Possible types

str

Strings may be any valid colormap name suitable for the matplotlib.cm.get_cmap() function or one of the color lists defined in the ‘colors.cmaps’ key of the psyplot.rcParams dictionary (including their reversed color maps given via the ‘_r’ extension).

matplotlib.colors.Colormap: The colormap instance to use

See also

bounds: specifies the boundaries of the colormap

vcticklabels

Specify the colorbar ticklabels

Possible types

str: A formatstring like '%Y' for plotting the year (in the case that time is shown on the axis) or ‘%i’ for integers
array: An array of strings to use for the ticklabels

vctickprops

Specify the font properties of the colorbar ticklabels

Possible types

dict: Items may be anything of the matplotlib.pyplot.tick_params() function

vcticks

Specify the tick locations of the vector colorbar

Possible types

None

use the default ticks

numeric array

specifies the ticks manually

str or list [str, …]

A list of the below mentioned values of the mapping like [method, N, percmin, percmax, vmin, vmax], where only the first one is absolutely necessary

dict

Automatically determine the ticks corresponding to the data. The mapping can have the following keys, but only method is not optional.

N

An integer describing the number of boundaries (or ticks per power of ten, see log and symlog above)

percmin

The percentile to use for the minimum (by default, 0, i.e. the minimum of the array)

percmax

The percentile to use for the maximum (by default, 100, i.e. the maximum of the array)

vmin

The minimum to use (in which case it is not calculated from the specified method)

vmax

The maximum to use (in which case it is not calculated from the specified method)

method

A string that defines how minimum and maximum shall be set. This argument is not optional and can be one of the following:

data: plot the ticks exactly where the data is.
mid: plot the ticks in the middle of the data.
rounded: Sets the minimum and maximum of the ticks to the rounded data minimum or maximum. Ticks are rounded to the next 0.5 value with to the difference between data max- and minimum. The minimal tick will always be lower or equal than the data minimum, the maximal tick will always be higher or equal than the data maximum.
roundedsym: Same as rounded above but the ticks are chose such that they are symmetric around zero
minmax: Uses the minimum as minimal tick and maximum as maximal tick
sym: Same as minmax but symmetric around zero
log: Use logarithmic bounds. In this case, the given number N determines the number of bounds per power of tenth (i.e. N == 2 results in something like 1.0, 5.0, 10.0, 50.0, etc., If this second number is None, then it will be chosen such that we have around 11 boundaries but at least one per power of ten.
symlog: The same as log but symmetric around 0. If the number N is None, then we have around 12 boundaries but at least one per power of ten
bounds: let the bounds keyword determine the ticks. An additional integer i may be specified to only use every i-th bound as a tick (see also int below)
midbounds: Same as bounds but in the middle between two bounds

int

Specifies how many ticks to use with the 'bounds' option. I.e. if integer i, then this is the same as ['bounds', i].

See also

cticklabels, vcticklabels

vcticksize

Specify the font size of the colorbar ticklabels

Possible types

float: The absolute font size in points (e.g., 12)
string: Strings might be ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’.

vctickweight

Specify the fontweight of the colorbar ticklabels

Possible types

float: a float between 0 and 1000
string: Possible strings are one of ‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’.

vplot

Choose the vector plot type

Possible types

str

Plot types can be either

quiver: to make a quiver plot
stream: to make a stream plot

vtransect

xgrid

Draw vertical grid lines (meridians)

This formatoption specifies at which longitudes to draw the meridians.

Possible types

None

Don’t draw gridlines (same as False)

bool

True: draw gridlines and determine position automatically False: don’t draw gridlines

numeric array

specifies the ticks manually

str or list [str, …]

A list of the below mentioned values of the mapping like [method, N, percmin, percmax, vmin, vmax], where only the first one is absolutely necessary

dict

Automatically determine the ticks corresponding to the data. The mapping can have the following keys, but only method is not optional.

N

An integer describing the number of boundaries (or ticks per power of ten, see log and symlog above)

percmin

The percentile to use for the minimum (by default, 0, i.e. the minimum of the array)

percmax

The percentile to use for the maximum (by default, 100, i.e. the maximum of the array)

vmin

The minimum to use (in which case it is not calculated from the specified method)

vmax

The maximum to use (in which case it is not calculated from the specified method)

method

A string that defines how minimum and maximum shall be set. This argument is not optional and can be one of the following:

data: plot the ticks exactly where the data is.
mid: plot the ticks in the middle of the data.
rounded: Sets the minimum and maximum of the ticks to the rounded data minimum or maximum. Ticks are rounded to the next 0.5 value with to the difference between data max- and minimum. The minimal tick will always be lower or equal than the data minimum, the maximal tick will always be higher or equal than the data maximum.
roundedsym: Same as rounded above but the ticks are chose such that they are symmetric around zero
minmax: Uses the minimum as minimal tick and maximum as maximal tick
sym: Same as minmax but symmetric around zero
log: Use logarithmic bounds. In this case, the given number N determines the number of bounds per power of tenth (i.e. N == 2 results in something like 1.0, 5.0, 10.0, 50.0, etc., If this second number is None, then it will be chosen such that we have around 11 boundaries but at least one per power of ten.
symlog: The same as log but symmetric around 0. If the number N is None, then we have around 12 boundaries but at least one per power of ten

int

Specifies how many ticks to use with the 'rounded' option. I.e. if integer i, then this is the same as ['rounded', i].

See also

ygrid, grid_color, grid_labels

ygrid

Draw horizontal grid lines (parallels)

This formatoption specifies at which latitudes to draw the parallels.

Possible types

None

Don’t draw gridlines (same as False)

bool

True: draw gridlines and determine position automatically False: don’t draw gridlines

numeric array

specifies the ticks manually

str or list [str, …]

A list of the below mentioned values of the mapping like [method, N, percmin, percmax, vmin, vmax], where only the first one is absolutely necessary

dict

Automatically determine the ticks corresponding to the data. The mapping can have the following keys, but only method is not optional.

N

An integer describing the number of boundaries (or ticks per power of ten, see log and symlog above)

percmin

The percentile to use for the minimum (by default, 0, i.e. the minimum of the array)

percmax

The percentile to use for the maximum (by default, 100, i.e. the maximum of the array)

vmin

The minimum to use (in which case it is not calculated from the specified method)

vmax

The maximum to use (in which case it is not calculated from the specified method)

method

A string that defines how minimum and maximum shall be set. This argument is not optional and can be one of the following:

data: plot the ticks exactly where the data is.
mid: plot the ticks in the middle of the data.
rounded: Sets the minimum and maximum of the ticks to the rounded data minimum or maximum. Ticks are rounded to the next 0.5 value with to the difference between data max- and minimum. The minimal tick will always be lower or equal than the data minimum, the maximal tick will always be higher or equal than the data maximum.
roundedsym: Same as rounded above but the ticks are chose such that they are symmetric around zero
minmax: Uses the minimum as minimal tick and maximum as maximal tick
sym: Same as minmax but symmetric around zero
log: Use logarithmic bounds. In this case, the given number N determines the number of bounds per power of tenth (i.e. N == 2 results in something like 1.0, 5.0, 10.0, 50.0, etc., If this second number is None, then it will be chosen such that we have around 11 boundaries but at least one per power of ten.
symlog: The same as log but symmetric around 0. If the number N is None, then we have around 12 boundaries but at least one per power of ten

int

Specifies how many ticks to use with the 'rounded' option. I.e. if integer i, then this is the same as ['rounded', i].

See also

xgrid, grid_color, grid_labels

class psy_transect.maps.HorizontalTransectFieldPlotter(*args, **kwargs)

Bases: HorizontalTransectPlotterMixin, FieldPlotter

Attributes:

`allowed_dims`	The number of allowed dimensions in the for the visualization.
`sliders`

Axes formatoptions:

`background`	The background color for the matplotlib axes.
`tight`	Automatically adjust the plots.
`transpose`	Transpose the data before plotting

Color coding formatoptions:

`bounds`	Specify the boundaries of the colorbar
`cbar`	Specify the position of the colorbars
`cbarspacing`	Specify the spacing of the bounds in the colorbar
`cmap`	Specify the color map
`ctickprops`	Specify the font properties of the colorbar ticklabels
`cticksize`	Specify the font size of the colorbar ticklabels
`ctickweight`	Specify the fontweight of the colorbar ticklabels
`extend`	Draw arrows at the side of the colorbar
`levels`	The levels for the contour plot
`miss_color`	Set the color for missing values

Label formatoptions:

`clabel`	Show the colorbar label
`clabelprops`	Properties of the Colorbar label
`clabelsize`	Set the size of the Colorbar label
`clabelweight`	Set the fontweight of the Colorbar label
`figtitle`	Plot a figure title
`figtitleprops`	Properties of the figure title
`figtitlesize`	Set the size of the figure title
`figtitleweight`	Set the fontweight of the figure title
`text`	Add text anywhere on the plot
`title`	Show the title
`titleprops`	Properties of the title
`titlesize`	Set the size of the title
`titleweight`	Set the fontweight of the title

Miscallaneous formatoptions:

`clat`	Set the center latitude of the plot
`clip`	Clip the part outside the latitudes of the map extent
`clon`	Set the center longitude of the plot
`datagrid`
`google_map_detail`	Show a map of google on the plot.
`grid_color`	Set the color of the grid
`grid_labels`	Display the labels of the grid
`grid_labelsize`	Modify the size of the grid tick labels
`grid_settings`	Modify the settings of the grid explicitly
`interp_bounds`	Interpolate grid cell boundaries for 2D plots
`lonlatbox`
`lsm`	Draw the continents
`map_extent`	Set the extent of the map
`mask_datagrid`	Mask the datagrid where the array is NaN
`projection`	Specify the projection for the plot
`stock_img`	Display a stock image on the map
`transect`	Transect along a vertical level
`transform`	Specify the coordinate system of the data
`xgrid`	Draw vertical grid lines (meridians)
`ygrid`	Draw horizontal grid lines (parallels)

Axis tick formatoptions:

`cticklabels`	Specify the colorbar ticklabels
`cticks`	Specify the tick locations of the colorbar

Masking formatoptions:

`mask`	Mask the data where a certain condition is True
`maskbetween`	Mask data points between two numbers
`maskgeq`	Mask data points greater than or equal to a number
`maskgreater`	Mask data points greater than a number
`maskleq`	Mask data points smaller than or equal to a number
`maskless`	Mask data points smaller than a number

Plot formatoptions:

plot

Post processing formatoptions:

`post`	Apply your own postprocessing script
`post_timing`	Determine when to run the `post` formatoption

allowed_dims = 3: The number of allowed dimensions in the for the visualization. If the array is unstructured, one dimension will be subtracted

background

The background color for the matplotlib axes.

Possible types

‘rc’: to use matplotlibs rc params
None: to use a transparent color
color: Any possible matplotlib color

bounds

Specify the boundaries of the colorbar

Possible types

None

make no normalization

numeric array

specifies the ticks manually

str or list [str, …]

A list of the below mentioned values of the mapping like [method, N, percmin, percmax, vmin, vmax], where only the first one is absolutely necessary

dict

Automatically determine the ticks corresponding to the data. The mapping can have the following keys, but only method is not optional.

N

An integer describing the number of boundaries (or ticks per power of ten, see log and symlog above)

percmin

The percentile to use for the minimum (by default, 0, i.e. the minimum of the array)

percmax

The percentile to use for the maximum (by default, 100, i.e. the maximum of the array)

vmin

The minimum to use (in which case it is not calculated from the specified method)

vmax

The maximum to use (in which case it is not calculated from the specified method)

method

A string that defines how minimum and maximum shall be set. This argument is not optional and can be one of the following:

data: plot the ticks exactly where the data is.
mid: plot the ticks in the middle of the data.
rounded: Sets the minimum and maximum of the ticks to the rounded data minimum or maximum. Ticks are rounded to the next 0.5 value with to the difference between data max- and minimum. The minimal tick will always be lower or equal than the data minimum, the maximal tick will always be higher or equal than the data maximum.
roundedsym: Same as rounded above but the ticks are chose such that they are symmetric around zero
minmax: Uses the minimum as minimal tick and maximum as maximal tick
sym: Same as minmax but symmetric around zero
log: Use logarithmic bounds. In this case, the given number N determines the number of bounds per power of tenth (i.e. N == 2 results in something like 1.0, 5.0, 10.0, 50.0, etc., If this second number is None, then it will be chosen such that we have around 11 boundaries but at least one per power of ten.
symlog: The same as log but symmetric around 0. If the number N is None, then we have around 12 boundaries but at least one per power of ten

int

Specifies how many ticks to use with the 'rounded' option. I.e. if integer i, then this is the same as ['rounded', i].

matplotlib.colors.Normalize

A matplotlib normalization instance

Examples

Plot 11 bounds over the whole data range:

>>> plotter.update(bounds='rounded')

which is equivalent to:

>>> plotter.update(bounds={'method': 'rounded'})

Plot 7 ticks over the whole data range where the maximal and minimal tick matches the data maximum and minimum:
```
>>> plotter.update(bounds=['minmax', 7])
```
which is equivaluent to:
```
>>> plotter.update(bounds={'method': 'minmax', 'N': 7})
```

chop the first and last five percentiles:

>>> plotter.update(bounds=['rounded', None, 5, 95])

which is equivalent to:

>>> plotter.update(bounds={'method': 'rounded', 'percmin': 5,
...                        'percmax': 95})

Plot 3 bounds per power of ten:
```
>>> plotter.update(bounds=['log', 3])
```

Plot continuous logarithmic bounds:

>>> from matplotlib.colors import LogNorm
>>> plotter.update(bounds=LogNorm())

See also

cmap: Specifies the colormap

cbar

Specify the position of the colorbars

Possible types

bool

True: defaults to ‘b’ False: Don’t draw any colorbar

str

The string can be a combination of one of the following strings: {‘fr’, ‘fb’, ‘fl’, ‘ft’, ‘b’, ‘r’, ‘sv’, ‘sh’}

‘b’, ‘r’ stand for bottom and right of the axes
‘fr’, ‘fb’, ‘fl’, ‘ft’ stand for bottom, right, left and top of the figure
‘sv’ and ‘sh’ stand for a vertical or horizontal colorbar in a separate figure

list

A containing one of the above positions

Examples

Draw a colorbar at the bottom and left of the axes:

>>> plotter.update(cbar='bl')

cbarspacing

Specify the spacing of the bounds in the colorbar

Possible types

str {‘uniform’, ‘proportional’}: if 'uniform', every color has exactly the same width in the colorbar, if 'proportional', the size is chosen according to the data

clabel

Show the colorbar label

Set the label of the colorbar. You can insert any meta key from the xarray.DataArray.attrs via a string like '%(key)s'. Furthermore there are some special cases:

Strings like '%Y', '%b', etc. will be replaced using the datetime.datetime.strftime() method as long as the data has a time coordinate and this can be converted to a datetime object.
'%(x)s', '%(y)s', '%(z)s', '%(t)s' will be replaced by the value of the x-, y-, z- or time coordinate (as long as this coordinate is one-dimensional in the data)
any attribute of one of the above coordinates is inserted via axis + key (e.g. the name of the x-coordinate can be inserted via '%(xname)s').
Labels defined in the psyplot.rcParams 'texts.labels' key are also replaced when enclosed by ‘{}’. The standard labels are
- tinfo: %H:%M
- dtinfo: %B %d, %Y. %H:%M
- dinfo: %B %d, %Y
- desc: %(long_name)s [%(units)s]
- sdesc: %(name)s [%(units)s]

Possible types

str: The title for the set_label() method.

clabelprops

Properties of the Colorbar label

Specify the font properties of the figure title manually.

Possible types

dict: Items may be any valid text property

See also

clabel, clabelsize, clabelweight

clabelsize

Set the size of the Colorbar label

Possible types

float: The absolute font size in points (e.g., 12)
string: Strings might be ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’.

See also

clabel, clabelweight, clabelprops

clabelweight

Set the fontweight of the Colorbar label

Possible types

float: a float between 0 and 1000
string: Possible strings are one of ‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’.

See also

clabel, clabelsize, clabelprops

clat

Set the center latitude of the plot

Parameters:

None – Let the lonlatbox formatoption determine the center
float – Specifiy the center manually
str – A pattern that matches any of the keys in the psyplot.rcParams 'extents.boxes' item (contains user-defined longitude-latitude boxes) or the psyplot.plotter.boxes.lonlatboxes dictionary (contains longitude-latitude boxes of different countries and continents)

clip

Clip the part outside the latitudes of the map extent

Possible types

None: Clip if all longitudes are shown (i.e. the extent goes from -180 to 180) and the projection is orthographic or stereographic
bool: True, clip, else, don’t

Notes

If the plot is clipped. You might need to update with replot=True!

clon

Set the center longitude of the plot

Parameters:

None – Let the lonlatbox formatoption determine the center
float – Specifiy the center manually
str – A pattern that matches any of the keys in the psyplot.rcParams 'extents.boxes' item (contains user-defined longitude-latitude boxes) or the psyplot.plotter.boxes.lonlatboxes dictionary (contains longitude-latitude boxes of different countries and continents)

cmap

Specify the color map

This formatoption specifies the color coding of the data via a matplotlib.colors.Colormap

Possible types

str

Strings may be any valid colormap name suitable for the matplotlib.cm.get_cmap() function or one of the color lists defined in the ‘colors.cmaps’ key of the psyplot.rcParams dictionary (including their reversed color maps given via the ‘_r’ extension).

matplotlib.colors.Colormap: The colormap instance to use

See also

bounds: specifies the boundaries of the colormap

cticklabels

Specify the colorbar ticklabels

Possible types

str: A formatstring like '%Y' for plotting the year (in the case that time is shown on the axis) or ‘%i’ for integers
array: An array of strings to use for the ticklabels

See also

cticks, cticksize, ctickweight, ctickprops, vcticks, vcticksize, vctickweight, vctickprops

ctickprops

Specify the font properties of the colorbar ticklabels

Possible types

dict: Items may be anything of the matplotlib.pyplot.tick_params() function

See also

cticksize, ctickweight, cticklabels, cticks, vcticksize, vctickweight, vcticklabels, vcticks

cticks

Specify the tick locations of the colorbar

Possible types

None

use the default ticks

numeric array

specifies the ticks manually

str or list [str, …]

A list of the below mentioned values of the mapping like [method, N, percmin, percmax, vmin, vmax], where only the first one is absolutely necessary

dict

Automatically determine the ticks corresponding to the data. The mapping can have the following keys, but only method is not optional.

N

An integer describing the number of boundaries (or ticks per power of ten, see log and symlog above)

percmin

The percentile to use for the minimum (by default, 0, i.e. the minimum of the array)

percmax

The percentile to use for the maximum (by default, 100, i.e. the maximum of the array)

vmin

The minimum to use (in which case it is not calculated from the specified method)

vmax

The maximum to use (in which case it is not calculated from the specified method)

method

A string that defines how minimum and maximum shall be set. This argument is not optional and can be one of the following:

data: plot the ticks exactly where the data is.
mid: plot the ticks in the middle of the data.
rounded: Sets the minimum and maximum of the ticks to the rounded data minimum or maximum. Ticks are rounded to the next 0.5 value with to the difference between data max- and minimum. The minimal tick will always be lower or equal than the data minimum, the maximal tick will always be higher or equal than the data maximum.
roundedsym: Same as rounded above but the ticks are chose such that they are symmetric around zero
minmax: Uses the minimum as minimal tick and maximum as maximal tick
sym: Same as minmax but symmetric around zero
log: Use logarithmic bounds. In this case, the given number N determines the number of bounds per power of tenth (i.e. N == 2 results in something like 1.0, 5.0, 10.0, 50.0, etc., If this second number is None, then it will be chosen such that we have around 11 boundaries but at least one per power of ten.
symlog: The same as log but symmetric around 0. If the number N is None, then we have around 12 boundaries but at least one per power of ten
bounds: let the bounds keyword determine the ticks. An additional integer i may be specified to only use every i-th bound as a tick (see also int below)
midbounds: Same as bounds but in the middle between two bounds

int

Specifies how many ticks to use with the 'bounds' option. I.e. if integer i, then this is the same as ['bounds', i].

See also

cticklabels

cticksize

Specify the font size of the colorbar ticklabels

Possible types

float: The absolute font size in points (e.g., 12)
string: Strings might be ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’.

See also

ctickweight, ctickprops, cticklabels, cticks, vctickweight, vctickprops, vcticklabels, vcticks

ctickweight

Specify the fontweight of the colorbar ticklabels

Possible types

float: a float between 0 and 1000
string: Possible strings are one of ‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’.

See also

cticksize, ctickprops, cticklabels, cticks, vcticksize, vctickprops, vcticklabels, vcticks

datagrid

extend

Draw arrows at the side of the colorbar

Possible types

str {‘neither’, ‘both’, ‘min’ or ‘max’}: If not ‘neither’, make pointed end(s) for out-of-range values

figtitle

Plot a figure title

Set the title of the figure. You can insert any meta key from the xarray.DataArray.attrs via a string like '%(key)s'. Furthermore there are some special cases:

Strings like '%Y', '%b', etc. will be replaced using the datetime.datetime.strftime() method as long as the data has a time coordinate and this can be converted to a datetime object.
'%(x)s', '%(y)s', '%(z)s', '%(t)s' will be replaced by the value of the x-, y-, z- or time coordinate (as long as this coordinate is one-dimensional in the data)
any attribute of one of the above coordinates is inserted via axis + key (e.g. the name of the x-coordinate can be inserted via '%(xname)s').
Labels defined in the psyplot.rcParams 'texts.labels' key are also replaced when enclosed by ‘{}’. The standard labels are
- tinfo: %H:%M
- dtinfo: %B %d, %Y. %H:%M
- dinfo: %B %d, %Y
- desc: %(long_name)s [%(units)s]
- sdesc: %(name)s [%(units)s]

Possible types

str: The title for the suptitle() function

Notes

If the plotter is part of a psyplot.project.Project and multiple plotters of this project are on the same figure, the replacement attributes (see above) are joined by a delimiter. If the delimiter attribute of this Figtitle instance is not None, it will be used. Otherwise the rcParams[‘texts.delimiter’] item is used.
This is the title of the whole figure! For the title of this specific subplot, see the title formatoption.

figtitleprops

Properties of the figure title

Specify the font properties of the figure title manually.

Possible types

dict: Items may be any valid text property

figtitlesize

Set the size of the figure title

Possible types

float: The absolute font size in points (e.g., 12)
string: Strings might be ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’.

figtitleweight

Set the fontweight of the figure title

Possible types

float: a float between 0 and 1000
string: Possible strings are one of ‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’.

google_map_detail

Show a map of google on the plot.

Possible types

None: Do not show anything
int: The level of detail to show (usually between 6 and 9, must be greater than or equal to 0).

grid_color

Set the color of the grid

Possible types

None: Choose the default line color
color: Any valid color for matplotlib (see the matplotlib.pyplot.plot() documentation)

grid_labels

Display the labels of the grid

Possible types

None: Grid labels are draw if possible
bool: If True, labels are drawn and if this is not possible, a warning is raised

grid_labelsize

Modify the size of the grid tick labels

Possible types

float: The absolute font size in points (e.g., 12)
string: Strings might be ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’.

grid_settings

Modify the settings of the grid explicitly

Possible types

dict: Items may be any key-value-pair of the matplotlib.collections.LineCollection class

interp_bounds

Interpolate grid cell boundaries for 2D plots

This formatoption can be used to tell enable and disable the interpolation of grid cell boundaries. Usually, netCDF files only contain the centered coordinates. In this case, we interpolate the boundaries between the grid cell centers.

Possible types

None: Interpolate the boundaries, except for circumpolar grids
bool: If True (the default), the grid cell boundaries are inter- and extrapolated. Otherwise, if False, the coordinate centers are used and the default behaviour of matplotlib cuts of the most outer row and column of the 2D-data. Note that this results in a slight shift of the data

levels

The levels for the contour plot

This formatoption sets the levels for the filled contour plot and only has an effect if the plot Formatoption is set to 'contourf'

Possible types

None

Use the settings from the bounds formatoption and if this does not specify boundaries, use 11

numeric array

specifies the ticks manually

str or list [str, …]

A list of the below mentioned values of the mapping like [method, N, percmin, percmax, vmin, vmax], where only the first one is absolutely necessary

dict

Automatically determine the ticks corresponding to the data. The mapping can have the following keys, but only method is not optional.

N

An integer describing the number of boundaries (or ticks per power of ten, see log and symlog above)

percmin

The percentile to use for the minimum (by default, 0, i.e. the minimum of the array)

percmax

The percentile to use for the maximum (by default, 100, i.e. the maximum of the array)

vmin

The minimum to use (in which case it is not calculated from the specified method)

vmax

The maximum to use (in which case it is not calculated from the specified method)

method

A string that defines how minimum and maximum shall be set. This argument is not optional and can be one of the following:

data: plot the ticks exactly where the data is.
mid: plot the ticks in the middle of the data.
rounded: Sets the minimum and maximum of the ticks to the rounded data minimum or maximum. Ticks are rounded to the next 0.5 value with to the difference between data max- and minimum. The minimal tick will always be lower or equal than the data minimum, the maximal tick will always be higher or equal than the data maximum.
roundedsym: Same as rounded above but the ticks are chose such that they are symmetric around zero
minmax: Uses the minimum as minimal tick and maximum as maximal tick
sym: Same as minmax but symmetric around zero
log: Use logarithmic bounds. In this case, the given number N determines the number of bounds per power of tenth (i.e. N == 2 results in something like 1.0, 5.0, 10.0, 50.0, etc., If this second number is None, then it will be chosen such that we have around 11 boundaries but at least one per power of ten.
symlog: The same as log but symmetric around 0. If the number N is None, then we have around 12 boundaries but at least one per power of ten

int

Specifies how many ticks to use with the 'rounded' option. I.e. if integer i, then this is the same as ['rounded', i].

lonlatbox

lsm

Draw the continents

Possible types

bool

True: draw the coastlines with a line width of 1 False: don’t draw anything

float

Specifies the linewidth of the coastlines

str

The resolution of the land-sea mask (see the cartopy.mpl.geoaxes.GeoAxesSubplot.coastlines() method. Must be one of ('110m', '50m', '10m').

list [str or bool, float]

The resolution and the linewidth

dict

A dictionary with any of the following keys

coast: The color for the coastlines
land: The fill color for the continents
ocean: The fill color for the oceans
res: The resolution (see above)
linewidth: The linewidth of the coastlines (see above)

map_extent

Set the extent of the map

Possible types

None: The map extent is specified by the data (i.e. by the lonlatbox formatoption)
‘global’: The whole globe is shown
‘data’: The extent is set to the longitude-latitute box defined by the lonlatbox formatoption
str: A pattern that matches any of the keys in the psyplot.rcParams 'extents.boxes' item (contains user-defined longitude-latitude boxes) or the psyplot.plotter.boxes.lonlatboxes dictionary (contains longitude-latitude boxes of different countries and continents)
[lonmin, lonmax, latmin, latmax]: The surrounding longitude-latitude that shall be used. Values can be either a float or a string as above

Notes

This formatoption sets the extent of the plot. For choosing the region for the data, see the lonlatbox formatoption

See also

lonlatbox

mask

Mask the data where a certain condition is True

This formatoption can be used to mask the plotting data based on another array. This array can be the name of a variable in the base dataset, or it can be a numeric array. Note that the data needs to be on exactly the same coordinates as the data shown here

Possible types

None

Apply no mask

str

The name of a variable in the base dataset to use.

dimensions that are in the given mask but not in the visualized base variable will be aggregated using numpy.any()
if the given mask misses dimensions that are in the visualized data (i.e. the data of this plotter), we broadcast the mask to match the shape of the data
dimensions that are in mask and the base variable, but not in the visualized data will be matched against each other

str

The path to a netCDF file that shall be loaded

xr.DataArray or np.ndarray

An array that can be broadcasted to the shape of the data

mask_datagrid

Mask the datagrid where the array is NaN

This boolean formatoption enables to mask the grid of the datagrid formatoption where the data is NaN

Possible types

bool: Either True, to not display the data grid for cells with NaN, or False

See also

datagrid

maskbetween

Mask data points between two numbers

Possible types

float: The floating number to mask above

maskgeq

Mask data points greater than or equal to a number

Possible types

float: The floating number to mask above

maskgreater

Mask data points greater than a number

Possible types

float: The floating number to mask above

maskleq

Mask data points smaller than or equal to a number

Possible types

float: The floating number to mask below

maskless

Mask data points smaller than a number

Possible types

float: The floating number to mask below

miss_color

Set the color for missing values

Possible types

None: Use the default from the colormap
string, tuple.: Defines the color of the grid.

plot

post

Apply your own postprocessing script

This formatoption let’s you apply your own post processing script. Just enter the script as a string and it will be executed. The formatoption will be made available via the self variable

Possible types

None: Don’t do anything
str: The post processing script as string

Note

This formatoption uses the built-in exec() function to compile the script. Since this poses a security risk when loading psyplot projects, it is by default disabled through the Plotter.enable_post attribute. If you are sure that you can trust the script in this formatoption, set this attribute of the corresponding Plotter to True

Examples

Assume, you want to manually add the mean of the data to the title of the matplotlib axes. You can simply do this via

from psyplot.plotter import Plotter
from xarray import DataArray

plotter = Plotter(DataArray([1, 2, 3]))
# enable the post formatoption
plotter.enable_post = True
plotter.update(post="self.ax.set_title(str(self.data.mean()))")
plotter.ax.get_title()
"2.0"

By default, the post formatoption is only ran, when it is explicitly updated. However, you can use the post_timing formatoption, to run it automatically. E.g. for running it after every update of the plotter, you can set

plotter.update(post_timing="always")

See also

post_timing: Determine the timing of this formatoption

post_timing

Determine when to run the post formatoption

This formatoption determines, whether the post formatoption should be run never, after replot or after every update.

Possible types

‘never’: Never run post processing scripts
‘always’: Always run post processing scripts
‘replot’: Only run post processing scripts when the data changes or a replot is necessary

See also

post: The post processing formatoption

projection

Specify the projection for the plot

This formatoption defines the projection of the plot

Possible types

cartopy.crs.CRS

A cartopy projection instance (e.g. cartopy.crs.PlateCarree)

str

A string specifies the projection instance to use. The centered longitude and latitude are determined by the clon and clat formatoptions. Possible strings are (each standing for the specified projection)

cf	try to decode the CF-conventions
cyl	`cartopy.crs.PlateCarree`
robin	`cartopy.crs.Robinson`
moll	`cartopy.crs.Mollweide`
geo	`cartopy.crs.Geostationary`
northpole	`cartopy.crs.NorthPolarStereo`
southpole	`cartopy.crs.SouthPolarStereo`
ortho	`cartopy.crs.Orthographic`
stereo	`cartopy.crs.Stereographic`
near	`cartopy.crs.NearsidePerspective`
rotated	`cartopy.crs.RotatedPole`

The special case 'cf' tries to decode the CF-conventions in the data. If this is not possible, we assume a standard lat-lon projection ('cyl')

See also

Grid-mappings of cf-conventions

Warning

An update of the projection clears the axes!

sliders: Dict[Axes, Slider]

stock_img

Display a stock image on the map

This formatoption uses the cartopy.mpl.geoaxes.GeoAxes.stock_img() method to display a downsampled version of the Natural Earth shaded relief raster on the map

Possible types

bool: If True, the image is displayed

text

Add text anywhere on the plot

This formatoption draws a text on the specified position on the figure. You can insert any meta key from the xarray.DataArray.attrs via a string like '%(key)s'. Furthermore there are some special cases:

Strings like '%Y', '%b', etc. will be replaced using the datetime.datetime.strftime() method as long as the data has a time coordinate and this can be converted to a datetime object.
'%(x)s', '%(y)s', '%(z)s', '%(t)s' will be replaced by the value of the x-, y-, z- or time coordinate (as long as this coordinate is one-dimensional in the data)
any attribute of one of the above coordinates is inserted via axis + key (e.g. the name of the x-coordinate can be inserted via '%(xname)s').
Labels defined in the psyplot.rcParams 'texts.labels' key are also replaced when enclosed by ‘{}’. The standard labels are
- tinfo: %H:%M
- dtinfo: %B %d, %Y. %H:%M
- dinfo: %B %d, %Y
- desc: %(long_name)s [%(units)s]
- sdesc: %(name)s [%(units)s]

Possible types

str: If string s: this will be used as (1., 1., s, {‘ha’: ‘right’}) (i.e. a string in the upper right corner of the axes).
tuple or list of tuples (x,y,s[,coord.-system][,options]]): Each tuple defines a text instance on the plot. 0<=x, y<=1 are the coordinates. The coord.-system can be either the data coordinates (default, 'data') or the axes coordinates ('axes') or the figure coordinates (‘fig’). The string s finally is the text. options may be a dictionary to specify format the appearence (e.g. 'color', 'fontweight', 'fontsize', etc., see matplotlib.text.Text for possible keys). To remove one single text from the plot, set (x,y,’’[, coord.-system]) for the text at position (x,y)
empty list: remove all texts from the plot

See also

title, figtitle

tight

Automatically adjust the plots.

If set to True, the plots are automatically adjusted to fit to the figure limitations via the matplotlib.pyplot.tight_layout() function.

Possible types

bool: True for automatic adjustment

Warning

There is no update method to undo what happend after this formatoption is set to True!

title

Show the title

Set the title of the plot. You can insert any meta key from the xarray.DataArray.attrs via a string like '%(key)s'. Furthermore there are some special cases:

Strings like '%Y', '%b', etc. will be replaced using the datetime.datetime.strftime() method as long as the data has a time coordinate and this can be converted to a datetime object.
'%(x)s', '%(y)s', '%(z)s', '%(t)s' will be replaced by the value of the x-, y-, z- or time coordinate (as long as this coordinate is one-dimensional in the data)
any attribute of one of the above coordinates is inserted via axis + key (e.g. the name of the x-coordinate can be inserted via '%(xname)s').
Labels defined in the psyplot.rcParams 'texts.labels' key are also replaced when enclosed by ‘{}’. The standard labels are
- tinfo: %H:%M
- dtinfo: %B %d, %Y. %H:%M
- dinfo: %B %d, %Y
- desc: %(long_name)s [%(units)s]
- sdesc: %(name)s [%(units)s]

Possible types

str: The title for the title() function.

Notes

This is the title of this specific subplot! For the title of the whole figure, see the figtitle formatoption.

titleprops

Properties of the title

Specify the font properties of the figure title manually.

Possible types

dict: Items may be any valid text property

See also

title, titlesize, titleweight

titlesize

Set the size of the title

Possible types

float: The absolute font size in points (e.g., 12)
string: Strings might be ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’.

See also

title, titleweight, titleprops

titleweight

Set the fontweight of the title

Possible types

float: a float between 0 and 1000
string: Possible strings are one of ‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’.

See also

title, titlesize, titleprops

transect: HorizontalTransect

Transect along a vertical level

This formatoption takes a list of x-y tuples, the so-called transect, and extracts the raw data along this path.

Possible types

list of x-y tuples: The point coordinates of the transect.

transform

Specify the coordinate system of the data

This formatoption defines the coordinate system of the data (usually we expect a simple latitude longitude coordinate system)

Possible types

cartopy.crs.CRS

A cartopy projection instance (e.g. cartopy.crs.PlateCarree)

str

A string specifies the projection instance to use. The centered longitude and latitude are determined by the clon and clat formatoptions. Possible strings are (each standing for the specified projection)

cf	try to decode the CF-conventions
cyl	`cartopy.crs.PlateCarree`
robin	`cartopy.crs.Robinson`
moll	`cartopy.crs.Mollweide`
geo	`cartopy.crs.Geostationary`
northpole	`cartopy.crs.NorthPolarStereo`
southpole	`cartopy.crs.SouthPolarStereo`
ortho	`cartopy.crs.Orthographic`
stereo	`cartopy.crs.Stereographic`
near	`cartopy.crs.NearsidePerspective`
rotated	`cartopy.crs.RotatedPole`

The special case 'cf' tries to decode the CF-conventions in the data. If this is not possible, we assume a standard lat-lon projection ('cyl')

See also

Grid-mappings of cf-conventions

transpose

Transpose the data before plotting

This formatoption can be used in case the data order of the variable dimensions is (x, y) instead of (y, x)

xgrid

Draw vertical grid lines (meridians)

This formatoption specifies at which longitudes to draw the meridians.

Possible types

None

Don’t draw gridlines (same as False)

bool

True: draw gridlines and determine position automatically False: don’t draw gridlines

numeric array

specifies the ticks manually

str or list [str, …]

A list of the below mentioned values of the mapping like [method, N, percmin, percmax, vmin, vmax], where only the first one is absolutely necessary

dict

Automatically determine the ticks corresponding to the data. The mapping can have the following keys, but only method is not optional.

N

An integer describing the number of boundaries (or ticks per power of ten, see log and symlog above)

percmin

The percentile to use for the minimum (by default, 0, i.e. the minimum of the array)

percmax

The percentile to use for the maximum (by default, 100, i.e. the maximum of the array)

vmin

The minimum to use (in which case it is not calculated from the specified method)

vmax

The maximum to use (in which case it is not calculated from the specified method)

method

A string that defines how minimum and maximum shall be set. This argument is not optional and can be one of the following:

data: plot the ticks exactly where the data is.
mid: plot the ticks in the middle of the data.
rounded: Sets the minimum and maximum of the ticks to the rounded data minimum or maximum. Ticks are rounded to the next 0.5 value with to the difference between data max- and minimum. The minimal tick will always be lower or equal than the data minimum, the maximal tick will always be higher or equal than the data maximum.
roundedsym: Same as rounded above but the ticks are chose such that they are symmetric around zero
minmax: Uses the minimum as minimal tick and maximum as maximal tick
sym: Same as minmax but symmetric around zero
log: Use logarithmic bounds. In this case, the given number N determines the number of bounds per power of tenth (i.e. N == 2 results in something like 1.0, 5.0, 10.0, 50.0, etc., If this second number is None, then it will be chosen such that we have around 11 boundaries but at least one per power of ten.
symlog: The same as log but symmetric around 0. If the number N is None, then we have around 12 boundaries but at least one per power of ten

int

Specifies how many ticks to use with the 'rounded' option. I.e. if integer i, then this is the same as ['rounded', i].

See also

ygrid, grid_color, grid_labels

ygrid

Draw horizontal grid lines (parallels)

This formatoption specifies at which latitudes to draw the parallels.

Possible types

None

Don’t draw gridlines (same as False)

bool

True: draw gridlines and determine position automatically False: don’t draw gridlines

numeric array

specifies the ticks manually

str or list [str, …]

A list of the below mentioned values of the mapping like [method, N, percmin, percmax, vmin, vmax], where only the first one is absolutely necessary

dict

Automatically determine the ticks corresponding to the data. The mapping can have the following keys, but only method is not optional.

N

An integer describing the number of boundaries (or ticks per power of ten, see log and symlog above)

percmin

The percentile to use for the minimum (by default, 0, i.e. the minimum of the array)

percmax

The percentile to use for the maximum (by default, 100, i.e. the maximum of the array)

vmin

The minimum to use (in which case it is not calculated from the specified method)

vmax

The maximum to use (in which case it is not calculated from the specified method)

method

A string that defines how minimum and maximum shall be set. This argument is not optional and can be one of the following:

data: plot the ticks exactly where the data is.
mid: plot the ticks in the middle of the data.
rounded: Sets the minimum and maximum of the ticks to the rounded data minimum or maximum. Ticks are rounded to the next 0.5 value with to the difference between data max- and minimum. The minimal tick will always be lower or equal than the data minimum, the maximal tick will always be higher or equal than the data maximum.
roundedsym: Same as rounded above but the ticks are chose such that they are symmetric around zero
minmax: Uses the minimum as minimal tick and maximum as maximal tick
sym: Same as minmax but symmetric around zero
log: Use logarithmic bounds. In this case, the given number N determines the number of bounds per power of tenth (i.e. N == 2 results in something like 1.0, 5.0, 10.0, 50.0, etc., If this second number is None, then it will be chosen such that we have around 11 boundaries but at least one per power of ten.
symlog: The same as log but symmetric around 0. If the number N is None, then we have around 12 boundaries but at least one per power of ten

int

Specifies how many ticks to use with the 'rounded' option. I.e. if integer i, then this is the same as ['rounded', i].

See also

xgrid, grid_color, grid_labels

class psy_transect.maps.HorizontalTransectLonLatBox(key, plotter=None, index_in_list=None, additional_children=[], additional_dependencies=[], **kwargs)

Bases: LonLatBox

Attributes:

`dependencies`	list of str.
`transect`	transect Formatoption instance in the plotter
`transform`	transform Formatoption instance in the plotter
`transpose`	transpose Formatoption instance in the plotter

dependencies = ['transform', 'transpose', 'transect']: list of str. List of formatoptions that force an update of this formatoption if they are updated.

property transect: transect Formatoption instance in the plotter

property transform: transform Formatoption instance in the plotter

property transpose: transpose Formatoption instance in the plotter

class psy_transect.maps.HorizontalTransectPlotterMixin(*args, **kwargs)

Bases: object

Methods:

`connect_ax`(plotter_or_ax[, orientation, ...])	Connect this plotter to an axes and draw a slider on it.
`disconnect_ax`(ax)	Disconnect this plotter from an axes and remove the slider.
`get_enhanced_attrs`(args, *kwargs)

Attributes:

`sliders`
`transect`

connect_ax(plotter_or_ax: VerticalTransectPlotter | Axes, orientation: str = 'vertical', facecolor='none', edgecolor='red', track_color='none', initcolor='red', dragging=False, label='Vertical transect', **kwargs) → Slider

Connect this plotter to an axes and draw a slider on it.

When the slider changes, the plot here is updated.

Parameters:

plotter_or_ax (VerticalTransectPlotter or matplotlib.axes.Axes) – The plotter whose axes to draw on, or an matplotlib axes. If you pass in the plotter, we make sure that lasso selectors of the plotter still work after an update.
orientation (str) – The orientation of the slider (which is vertical by default).
``*args –
Any further arguments or keyword arguments that are parsed to the created Slider
**kwargs`` – Any further arguments or keyword arguments that are parsed to the created Slider

Returns:

The newly created slider

Return type:

matplotlib.widgets.Slider

disconnect_ax(ax: Axes): Disconnect this plotter from an axes and remove the slider.

get_enhanced_attrs(*args, **kwargs)

sliders: Dict[Axes, Slider]

transect: HorizontalTransect

class psy_transect.maps.HorizontalTransectVector(key, plotter=None, index_in_list=None, additional_children=[], additional_dependencies=[], **kwargs)

Bases: HorizontalTransect

Methods:

update_data_from_ds(ds)

update_data_from_ds(ds)

class psy_transect.maps.HorizontalTransectVectorPlotter(*args, **kwargs)

Bases: HorizontalTransectPlotterMixin, VectorPlotter

Attributes:

`allowed_dims`
`sliders`

Vector plot formatoptions:

`arrowsize`	Change the size of the arrows
`arrowstyle`	Change the style of the arrows
`density`	Change the density of the arrows

Axes formatoptions:

`background`	The background color for the matplotlib axes.
`tight`	Automatically adjust the plots.
`transpose`	Transpose the data before plotting

Color coding formatoptions:

`bounds`	Specify the boundaries of the vector colorbar
`cbar`	Specify the position of the vector plot colorbars
`cbarspacing`	Specify the spacing of the bounds in the colorbar
`cmap`	Specify the color map
`color`	Set the color for the arrows
`ctickprops`	Specify the font properties of the colorbar ticklabels
`cticksize`	Specify the font size of the colorbar ticklabels
`ctickweight`	Specify the fontweight of the colorbar ticklabels
`extend`	Draw arrows at the side of the colorbar

Label formatoptions:

`clabel`	Show the colorbar label
`clabelprops`	Properties of the Colorbar label
`clabelsize`	Set the size of the Colorbar label
`clabelweight`	Set the fontweight of the Colorbar label
`figtitle`	Plot a figure title
`figtitleprops`	Properties of the figure title
`figtitlesize`	Set the size of the figure title
`figtitleweight`	Set the fontweight of the figure title
`text`	Add text anywhere on the plot
`title`	Show the title
`titleprops`	Properties of the title
`titlesize`	Set the size of the title
`titleweight`	Set the fontweight of the title

Miscallaneous formatoptions:

`clat`	Set the center latitude of the plot
`clip`	Clip the part outside the latitudes of the map extent
`clon`	Set the center longitude of the plot
`datagrid`
`google_map_detail`	Show a map of google on the plot.
`grid_color`	Set the color of the grid
`grid_labels`	Display the labels of the grid
`grid_labelsize`	Modify the size of the grid tick labels
`grid_settings`	Modify the settings of the grid explicitly
`linewidth`	Change the linewidth of the arrows
`lonlatbox`	Set the longitude-latitude box of the data shown
`lsm`	Draw the continents
`map_extent`	Set the extent of the map
`mask_datagrid`	Mask the datagrid where the array is NaN
`projection`	Specify the projection for the plot
`stock_img`	Display a stock image on the map
`transect`
`transform`	Specify the coordinate system of the data
`xgrid`	Draw vertical grid lines (meridians)
`ygrid`	Draw horizontal grid lines (parallels)

Axis tick formatoptions:

`cticklabels`	Specify the colorbar ticklabels
`cticks`	Specify the tick locations of the vector colorbar

Masking formatoptions:

`mask`	Mask the data where a certain condition is True
`maskbetween`	Mask data points between two numbers
`maskgeq`	Mask data points greater than or equal to a number
`maskgreater`	Mask data points greater than a number
`maskleq`	Mask data points smaller than or equal to a number
`maskless`	Mask data points smaller than a number

Plot formatoptions:

plot

Choose the vector plot type

Post processing formatoptions:

`post`	Apply your own postprocessing script
`post_timing`	Determine when to run the `post` formatoption

allowed_dims = 4

arrowsize

Change the size of the arrows

Possible types

None: make no scaling
float: Factor scaling the size of the arrows

arrowstyle

Change the style of the arrows

Possible types

str: Any arrow style string (see FancyArrowPatch)

Notes

This formatoption only has an effect for stream plots

background

The background color for the matplotlib axes.

Possible types

‘rc’: to use matplotlibs rc params
None: to use a transparent color
color: Any possible matplotlib color

bounds

Specify the boundaries of the vector colorbar

Possible types

None

make no normalization

numeric array

specifies the ticks manually

str or list [str, …]

A list of the below mentioned values of the mapping like [method, N, percmin, percmax, vmin, vmax], where only the first one is absolutely necessary

dict

Automatically determine the ticks corresponding to the data. The mapping can have the following keys, but only method is not optional.

N

An integer describing the number of boundaries (or ticks per power of ten, see log and symlog above)

percmin

The percentile to use for the minimum (by default, 0, i.e. the minimum of the array)

percmax

The percentile to use for the maximum (by default, 100, i.e. the maximum of the array)

vmin

The minimum to use (in which case it is not calculated from the specified method)

vmax

The maximum to use (in which case it is not calculated from the specified method)

method

A string that defines how minimum and maximum shall be set. This argument is not optional and can be one of the following:

data: plot the ticks exactly where the data is.
mid: plot the ticks in the middle of the data.
rounded: Sets the minimum and maximum of the ticks to the rounded data minimum or maximum. Ticks are rounded to the next 0.5 value with to the difference between data max- and minimum. The minimal tick will always be lower or equal than the data minimum, the maximal tick will always be higher or equal than the data maximum.
roundedsym: Same as rounded above but the ticks are chose such that they are symmetric around zero
minmax: Uses the minimum as minimal tick and maximum as maximal tick
sym: Same as minmax but symmetric around zero
log: Use logarithmic bounds. In this case, the given number N determines the number of bounds per power of tenth (i.e. N == 2 results in something like 1.0, 5.0, 10.0, 50.0, etc., If this second number is None, then it will be chosen such that we have around 11 boundaries but at least one per power of ten.
symlog: The same as log but symmetric around 0. If the number N is None, then we have around 12 boundaries but at least one per power of ten

int

Specifies how many ticks to use with the 'rounded' option. I.e. if integer i, then this is the same as ['rounded', i].

matplotlib.colors.Normalize

A matplotlib normalization instance

Examples

Plot 11 bounds over the whole data range:

>>> plotter.update(bounds='rounded')

which is equivalent to:

>>> plotter.update(bounds={'method': 'rounded'})

Plot 7 ticks over the whole data range where the maximal and minimal tick matches the data maximum and minimum:
```
>>> plotter.update(bounds=['minmax', 7])
```
which is equivaluent to:
```
>>> plotter.update(bounds={'method': 'minmax', 'N': 7})
```

chop the first and last five percentiles:

>>> plotter.update(bounds=['rounded', None, 5, 95])

which is equivalent to:

>>> plotter.update(bounds={'method': 'rounded', 'percmin': 5,
...                        'percmax': 95})

Plot 3 bounds per power of ten:
```
>>> plotter.update(bounds=['log', 3])
```

Plot continuous logarithmic bounds:

>>> from matplotlib.colors import LogNorm
>>> plotter.update(bounds=LogNorm())

See also

cmap: Specifies the colormap

cbar

Specify the position of the vector plot colorbars

Possible types

bool

True: defaults to ‘b’ False: Don’t draw any colorbar

str

The string can be a combination of one of the following strings: {‘fr’, ‘fb’, ‘fl’, ‘ft’, ‘b’, ‘r’, ‘sv’, ‘sh’}

‘b’, ‘r’ stand for bottom and right of the axes
‘fr’, ‘fb’, ‘fl’, ‘ft’ stand for bottom, right, left and top of the figure
‘sv’ and ‘sh’ stand for a vertical or horizontal colorbar in a separate figure

list

A containing one of the above positions

cbarspacing

Specify the spacing of the bounds in the colorbar

Possible types

str {‘uniform’, ‘proportional’}: if 'uniform', every color has exactly the same width in the colorbar, if 'proportional', the size is chosen according to the data

clabel

Show the colorbar label

Set the label of the colorbar. You can insert any meta key from the xarray.DataArray.attrs via a string like '%(key)s'. Furthermore there are some special cases:

Strings like '%Y', '%b', etc. will be replaced using the datetime.datetime.strftime() method as long as the data has a time coordinate and this can be converted to a datetime object.
'%(x)s', '%(y)s', '%(z)s', '%(t)s' will be replaced by the value of the x-, y-, z- or time coordinate (as long as this coordinate is one-dimensional in the data)
any attribute of one of the above coordinates is inserted via axis + key (e.g. the name of the x-coordinate can be inserted via '%(xname)s').
Labels defined in the psyplot.rcParams 'texts.labels' key are also replaced when enclosed by ‘{}’. The standard labels are
- tinfo: %H:%M
- dtinfo: %B %d, %Y. %H:%M
- dinfo: %B %d, %Y
- desc: %(long_name)s [%(units)s]
- sdesc: %(name)s [%(units)s]

Possible types

str: The title for the set_label() method.

clabelprops

Properties of the Colorbar label

Specify the font properties of the figure title manually.

Possible types

dict: Items may be any valid text property

See also

clabel, clabelsize, clabelweight

clabelsize

Set the size of the Colorbar label

Possible types

float: The absolute font size in points (e.g., 12)
string: Strings might be ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’.

See also

clabel, clabelweight, clabelprops

clabelweight

Set the fontweight of the Colorbar label

Possible types

float: a float between 0 and 1000
string: Possible strings are one of ‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’.

See also

clabel, clabelsize, clabelprops

clat

Set the center latitude of the plot

Parameters:

None – Let the lonlatbox formatoption determine the center
float – Specifiy the center manually
str – A pattern that matches any of the keys in the psyplot.rcParams 'extents.boxes' item (contains user-defined longitude-latitude boxes) or the psyplot.plotter.boxes.lonlatboxes dictionary (contains longitude-latitude boxes of different countries and continents)

clip

Clip the part outside the latitudes of the map extent

Possible types

None: Clip if all longitudes are shown (i.e. the extent goes from -180 to 180) and the projection is orthographic or stereographic
bool: True, clip, else, don’t

Notes

If the plot is clipped. You might need to update with replot=True!

clon

Set the center longitude of the plot

Parameters:

None – Let the lonlatbox formatoption determine the center
float – Specifiy the center manually
str – A pattern that matches any of the keys in the psyplot.rcParams 'extents.boxes' item (contains user-defined longitude-latitude boxes) or the psyplot.plotter.boxes.lonlatboxes dictionary (contains longitude-latitude boxes of different countries and continents)

cmap

Specify the color map

This formatoption specifies the color coding of the data via a matplotlib.colors.Colormap

Possible types

str

Strings may be any valid colormap name suitable for the matplotlib.cm.get_cmap() function or one of the color lists defined in the ‘colors.cmaps’ key of the psyplot.rcParams dictionary (including their reversed color maps given via the ‘_r’ extension).

matplotlib.colors.Colormap: The colormap instance to use

See also

bounds: specifies the boundaries of the colormap

color

Set the color for the arrows

This formatoption can be used to set a single color for the vectors or define the color coding

Possible types

float

Determines the greyness

color

Defines the same color for all arrows. The string can be either a html hex string (e.g. ‘#eeefff’), a single letter (e.g. ‘b’: blue, ‘g’: green, ‘r’: red, ‘c’: cyan, ‘m’: magenta, ‘y’: yellow, ‘k’: black, ‘w’: white) or any other color

string {‘absolute’, ‘u’, ‘v’}

Strings may define how the formatoption is calculated. Possible strings are

absolute: for the absolute wind speed
u: for the u component
v: for the v component

2D-array

The values determine the color for each plotted arrow. Note that the shape has to match the one of u and v.

cticklabels

Specify the colorbar ticklabels

Possible types

str: A formatstring like '%Y' for plotting the year (in the case that time is shown on the axis) or ‘%i’ for integers
array: An array of strings to use for the ticklabels

See also

cticks, cticksize, ctickweight, ctickprops, vcticks, vcticksize, vctickweight, vctickprops

ctickprops

Specify the font properties of the colorbar ticklabels

Possible types

dict: Items may be anything of the matplotlib.pyplot.tick_params() function

See also

cticksize, ctickweight, cticklabels, cticks, vcticksize, vctickweight, vcticklabels, vcticks

cticks

Specify the tick locations of the vector colorbar

Possible types

None

use the default ticks

numeric array

specifies the ticks manually

str or list [str, …]

A list of the below mentioned values of the mapping like [method, N, percmin, percmax, vmin, vmax], where only the first one is absolutely necessary

dict

Automatically determine the ticks corresponding to the data. The mapping can have the following keys, but only method is not optional.

N

An integer describing the number of boundaries (or ticks per power of ten, see log and symlog above)

percmin

The percentile to use for the minimum (by default, 0, i.e. the minimum of the array)

percmax

The percentile to use for the maximum (by default, 100, i.e. the maximum of the array)

vmin

The minimum to use (in which case it is not calculated from the specified method)

vmax

The maximum to use (in which case it is not calculated from the specified method)

method

A string that defines how minimum and maximum shall be set. This argument is not optional and can be one of the following:

data: plot the ticks exactly where the data is.
mid: plot the ticks in the middle of the data.
rounded: Sets the minimum and maximum of the ticks to the rounded data minimum or maximum. Ticks are rounded to the next 0.5 value with to the difference between data max- and minimum. The minimal tick will always be lower or equal than the data minimum, the maximal tick will always be higher or equal than the data maximum.
roundedsym: Same as rounded above but the ticks are chose such that they are symmetric around zero
minmax: Uses the minimum as minimal tick and maximum as maximal tick
sym: Same as minmax but symmetric around zero
log: Use logarithmic bounds. In this case, the given number N determines the number of bounds per power of tenth (i.e. N == 2 results in something like 1.0, 5.0, 10.0, 50.0, etc., If this second number is None, then it will be chosen such that we have around 11 boundaries but at least one per power of ten.
symlog: The same as log but symmetric around 0. If the number N is None, then we have around 12 boundaries but at least one per power of ten
bounds: let the bounds keyword determine the ticks. An additional integer i may be specified to only use every i-th bound as a tick (see also int below)
midbounds: Same as bounds but in the middle between two bounds

int

Specifies how many ticks to use with the 'bounds' option. I.e. if integer i, then this is the same as ['bounds', i].

See also

cticklabels, vcticklabels

cticksize

Specify the font size of the colorbar ticklabels

Possible types

float: The absolute font size in points (e.g., 12)
string: Strings might be ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’.

See also

ctickweight, ctickprops, cticklabels, cticks, vctickweight, vctickprops, vcticklabels, vcticks

ctickweight

Specify the fontweight of the colorbar ticklabels

Possible types

float: a float between 0 and 1000
string: Possible strings are one of ‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’.

See also

cticksize, ctickprops, cticklabels, cticks, vcticksize, vctickprops, vcticklabels, vcticks

datagrid

density

Change the density of the arrows

Possible types

float: Scales the density of the arrows in x- and y-direction (1.0 means no scaling)
tuple (x, y): Defines the scaling in x- and y-direction manually

extend

Draw arrows at the side of the colorbar

Possible types

str {‘neither’, ‘both’, ‘min’ or ‘max’}: If not ‘neither’, make pointed end(s) for out-of-range values

figtitle

Plot a figure title

Set the title of the figure. You can insert any meta key from the xarray.DataArray.attrs via a string like '%(key)s'. Furthermore there are some special cases:

Strings like '%Y', '%b', etc. will be replaced using the datetime.datetime.strftime() method as long as the data has a time coordinate and this can be converted to a datetime object.
'%(x)s', '%(y)s', '%(z)s', '%(t)s' will be replaced by the value of the x-, y-, z- or time coordinate (as long as this coordinate is one-dimensional in the data)
any attribute of one of the above coordinates is inserted via axis + key (e.g. the name of the x-coordinate can be inserted via '%(xname)s').
Labels defined in the psyplot.rcParams 'texts.labels' key are also replaced when enclosed by ‘{}’. The standard labels are
- tinfo: %H:%M
- dtinfo: %B %d, %Y. %H:%M
- dinfo: %B %d, %Y
- desc: %(long_name)s [%(units)s]
- sdesc: %(name)s [%(units)s]

Possible types

str: The title for the suptitle() function

Notes

If the plotter is part of a psyplot.project.Project and multiple plotters of this project are on the same figure, the replacement attributes (see above) are joined by a delimiter. If the delimiter attribute of this Figtitle instance is not None, it will be used. Otherwise the rcParams[‘texts.delimiter’] item is used.
This is the title of the whole figure! For the title of this specific subplot, see the title formatoption.

figtitleprops

Properties of the figure title

Specify the font properties of the figure title manually.

Possible types

dict: Items may be any valid text property

figtitlesize

Set the size of the figure title

Possible types

float: The absolute font size in points (e.g., 12)
string: Strings might be ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’.

figtitleweight

Set the fontweight of the figure title

Possible types

float: a float between 0 and 1000
string: Possible strings are one of ‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’.

google_map_detail

Show a map of google on the plot.

Possible types

None: Do not show anything
int: The level of detail to show (usually between 6 and 9, must be greater than or equal to 0).

grid_color

Set the color of the grid

Possible types

None: Choose the default line color
color: Any valid color for matplotlib (see the matplotlib.pyplot.plot() documentation)

grid_labels

Display the labels of the grid

Possible types

None: Grid labels are draw if possible
bool: If True, labels are drawn and if this is not possible, a warning is raised

grid_labelsize

Modify the size of the grid tick labels

Possible types

float: The absolute font size in points (e.g., 12)
string: Strings might be ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’.

grid_settings

Modify the settings of the grid explicitly

Possible types

dict: Items may be any key-value-pair of the matplotlib.collections.LineCollection class

linewidth

Change the linewidth of the arrows

Possible types

float

give the linewidth explicitly

string {‘absolute’, ‘u’, ‘v’}

Strings may define how the formatoption is calculated. Possible strings are

absolute: for the absolute wind speed
u: for the u component
v: for the v component

tuple (string, float)

string may be one of the above strings, float may be a scaling factor

2D-array

The values determine the linewidth for each plotted arrow. Note that the shape has to match the one of u and v.

lonlatbox

Set the longitude-latitude box of the data shown

This formatoption extracts the data that matches the specified box.

Possible types

None: Use the full data
str: A pattern that matches any of the keys in the psyplot.rcParams 'extents.boxes' item (contains user-defined longitude-latitude boxes) or the psyplot.plotter.boxes.lonlatboxes dictionary (contains longitude-latitude boxes of different countries and continents)
[lonmin, lonmax, latmin, latmax]: The surrounding longitude-latitude that shall be used. Values can be either a float or a string as above

Notes

For only specifying the region of the plot, see the map_extent formatoption
If the coordinates are two-dimensional (e.g. for a circumpolar grid), than the data is not extracted but values outside the specified longitude-latitude box are set to NaN

See also

map_extent

lsm

Draw the continents

Possible types

bool

True: draw the coastlines with a line width of 1 False: don’t draw anything

float

Specifies the linewidth of the coastlines

str

The resolution of the land-sea mask (see the cartopy.mpl.geoaxes.GeoAxesSubplot.coastlines() method. Must be one of ('110m', '50m', '10m').

list [str or bool, float]

The resolution and the linewidth

dict

A dictionary with any of the following keys

coast: The color for the coastlines
land: The fill color for the continents
ocean: The fill color for the oceans
res: The resolution (see above)
linewidth: The linewidth of the coastlines (see above)

map_extent

Set the extent of the map

Possible types

None: The map extent is specified by the data (i.e. by the lonlatbox formatoption)
‘global’: The whole globe is shown
‘data’: The extent is set to the longitude-latitute box defined by the lonlatbox formatoption
str: A pattern that matches any of the keys in the psyplot.rcParams 'extents.boxes' item (contains user-defined longitude-latitude boxes) or the psyplot.plotter.boxes.lonlatboxes dictionary (contains longitude-latitude boxes of different countries and continents)
[lonmin, lonmax, latmin, latmax]: The surrounding longitude-latitude that shall be used. Values can be either a float or a string as above

Notes

This formatoption sets the extent of the plot. For choosing the region for the data, see the lonlatbox formatoption

See also

lonlatbox

mask

Mask the data where a certain condition is True

This formatoption can be used to mask the plotting data based on another array. This array can be the name of a variable in the base dataset, or it can be a numeric array. Note that the data needs to be on exactly the same coordinates as the data shown here

Possible types

None

Apply no mask

str

The name of a variable in the base dataset to use.

dimensions that are in the given mask but not in the visualized base variable will be aggregated using numpy.any()
if the given mask misses dimensions that are in the visualized data (i.e. the data of this plotter), we broadcast the mask to match the shape of the data
dimensions that are in mask and the base variable, but not in the visualized data will be matched against each other

str

The path to a netCDF file that shall be loaded

xr.DataArray or np.ndarray

An array that can be broadcasted to the shape of the data

mask_datagrid

Mask the datagrid where the array is NaN

This boolean formatoption enables to mask the grid of the datagrid formatoption where the data is NaN

Possible types

bool: Either True, to not display the data grid for cells with NaN, or False

See also

datagrid

maskbetween

Mask data points between two numbers

Possible types

float: The floating number to mask above

maskgeq

Mask data points greater than or equal to a number

Possible types

float: The floating number to mask above

maskgreater

Mask data points greater than a number

Possible types

float: The floating number to mask above

maskleq

Mask data points smaller than or equal to a number

Possible types

float: The floating number to mask below

maskless

Mask data points smaller than a number

Possible types

float: The floating number to mask below

plot

Choose the vector plot type

Possible types

str

Plot types can be either

quiver: to make a quiver plot
stream: to make a stream plot

post

Apply your own postprocessing script

This formatoption let’s you apply your own post processing script. Just enter the script as a string and it will be executed. The formatoption will be made available via the self variable

Possible types

None: Don’t do anything
str: The post processing script as string

Note

This formatoption uses the built-in exec() function to compile the script. Since this poses a security risk when loading psyplot projects, it is by default disabled through the Plotter.enable_post attribute. If you are sure that you can trust the script in this formatoption, set this attribute of the corresponding Plotter to True

Examples

Assume, you want to manually add the mean of the data to the title of the matplotlib axes. You can simply do this via

from psyplot.plotter import Plotter
from xarray import DataArray

plotter = Plotter(DataArray([1, 2, 3]))
# enable the post formatoption
plotter.enable_post = True
plotter.update(post="self.ax.set_title(str(self.data.mean()))")
plotter.ax.get_title()
"2.0"

By default, the post formatoption is only ran, when it is explicitly updated. However, you can use the post_timing formatoption, to run it automatically. E.g. for running it after every update of the plotter, you can set

plotter.update(post_timing="always")

See also

post_timing: Determine the timing of this formatoption

post_timing

Determine when to run the post formatoption

This formatoption determines, whether the post formatoption should be run never, after replot or after every update.

Possible types

‘never’: Never run post processing scripts
‘always’: Always run post processing scripts
‘replot’: Only run post processing scripts when the data changes or a replot is necessary

See also

post: The post processing formatoption

projection

Specify the projection for the plot

This formatoption defines the projection of the plot

Possible types

cartopy.crs.CRS

A cartopy projection instance (e.g. cartopy.crs.PlateCarree)

str

A string specifies the projection instance to use. The centered longitude and latitude are determined by the clon and clat formatoptions. Possible strings are (each standing for the specified projection)

cf	try to decode the CF-conventions
cyl	`cartopy.crs.PlateCarree`
robin	`cartopy.crs.Robinson`
moll	`cartopy.crs.Mollweide`
geo	`cartopy.crs.Geostationary`
northpole	`cartopy.crs.NorthPolarStereo`
southpole	`cartopy.crs.SouthPolarStereo`
ortho	`cartopy.crs.Orthographic`
stereo	`cartopy.crs.Stereographic`
near	`cartopy.crs.NearsidePerspective`
rotated	`cartopy.crs.RotatedPole`

The special case 'cf' tries to decode the CF-conventions in the data. If this is not possible, we assume a standard lat-lon projection ('cyl')

See also

Grid-mappings of cf-conventions

Warning

An update of the projection clears the axes!

sliders: Dict[Axes, Slider]

stock_img

Display a stock image on the map

This formatoption uses the cartopy.mpl.geoaxes.GeoAxes.stock_img() method to display a downsampled version of the Natural Earth shaded relief raster on the map

Possible types

bool: If True, the image is displayed

text

Add text anywhere on the plot

This formatoption draws a text on the specified position on the figure. You can insert any meta key from the xarray.DataArray.attrs via a string like '%(key)s'. Furthermore there are some special cases:

Strings like '%Y', '%b', etc. will be replaced using the datetime.datetime.strftime() method as long as the data has a time coordinate and this can be converted to a datetime object.
'%(x)s', '%(y)s', '%(z)s', '%(t)s' will be replaced by the value of the x-, y-, z- or time coordinate (as long as this coordinate is one-dimensional in the data)
any attribute of one of the above coordinates is inserted via axis + key (e.g. the name of the x-coordinate can be inserted via '%(xname)s').
Labels defined in the psyplot.rcParams 'texts.labels' key are also replaced when enclosed by ‘{}’. The standard labels are
- tinfo: %H:%M
- dtinfo: %B %d, %Y. %H:%M
- dinfo: %B %d, %Y
- desc: %(long_name)s [%(units)s]
- sdesc: %(name)s [%(units)s]

Possible types

str: If string s: this will be used as (1., 1., s, {‘ha’: ‘right’}) (i.e. a string in the upper right corner of the axes).
tuple or list of tuples (x,y,s[,coord.-system][,options]]): Each tuple defines a text instance on the plot. 0<=x, y<=1 are the coordinates. The coord.-system can be either the data coordinates (default, 'data') or the axes coordinates ('axes') or the figure coordinates (‘fig’). The string s finally is the text. options may be a dictionary to specify format the appearence (e.g. 'color', 'fontweight', 'fontsize', etc., see matplotlib.text.Text for possible keys). To remove one single text from the plot, set (x,y,’’[, coord.-system]) for the text at position (x,y)
empty list: remove all texts from the plot

See also

title, figtitle

tight

Automatically adjust the plots.

If set to True, the plots are automatically adjusted to fit to the figure limitations via the matplotlib.pyplot.tight_layout() function.

Possible types

bool: True for automatic adjustment

Warning

There is no update method to undo what happend after this formatoption is set to True!

title

Show the title

Set the title of the plot. You can insert any meta key from the xarray.DataArray.attrs via a string like '%(key)s'. Furthermore there are some special cases:

Strings like '%Y', '%b', etc. will be replaced using the datetime.datetime.strftime() method as long as the data has a time coordinate and this can be converted to a datetime object.
'%(x)s', '%(y)s', '%(z)s', '%(t)s' will be replaced by the value of the x-, y-, z- or time coordinate (as long as this coordinate is one-dimensional in the data)
any attribute of one of the above coordinates is inserted via axis + key (e.g. the name of the x-coordinate can be inserted via '%(xname)s').
Labels defined in the psyplot.rcParams 'texts.labels' key are also replaced when enclosed by ‘{}’. The standard labels are
- tinfo: %H:%M
- dtinfo: %B %d, %Y. %H:%M
- dinfo: %B %d, %Y
- desc: %(long_name)s [%(units)s]
- sdesc: %(name)s [%(units)s]

Possible types

str: The title for the title() function.

Notes

This is the title of this specific subplot! For the title of the whole figure, see the figtitle formatoption.

titleprops

Properties of the title

Specify the font properties of the figure title manually.

Possible types

dict: Items may be any valid text property

See also

title, titlesize, titleweight

titlesize

Set the size of the title

Possible types

float: The absolute font size in points (e.g., 12)
string: Strings might be ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’.

See also

title, titleweight, titleprops

titleweight

Set the fontweight of the title

Possible types

float: a float between 0 and 1000
string: Possible strings are one of ‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’.

See also

title, titlesize, titleprops

transect: HorizontalTransect

transform

Specify the coordinate system of the data

This formatoption defines the coordinate system of the data (usually we expect a simple latitude longitude coordinate system)

Possible types

cartopy.crs.CRS

A cartopy projection instance (e.g. cartopy.crs.PlateCarree)

str

A string specifies the projection instance to use. The centered longitude and latitude are determined by the clon and clat formatoptions. Possible strings are (each standing for the specified projection)

cf	try to decode the CF-conventions
cyl	`cartopy.crs.PlateCarree`
robin	`cartopy.crs.Robinson`
moll	`cartopy.crs.Mollweide`
geo	`cartopy.crs.Geostationary`
northpole	`cartopy.crs.NorthPolarStereo`
southpole	`cartopy.crs.SouthPolarStereo`
ortho	`cartopy.crs.Orthographic`
stereo	`cartopy.crs.Stereographic`
near	`cartopy.crs.NearsidePerspective`
rotated	`cartopy.crs.RotatedPole`

The special case 'cf' tries to decode the CF-conventions in the data. If this is not possible, we assume a standard lat-lon projection ('cyl')

See also

Grid-mappings of cf-conventions

transpose

Transpose the data before plotting

This formatoption can be used in case the data order of the variable dimensions is (x, y) instead of (y, x)

xgrid

Draw vertical grid lines (meridians)

This formatoption specifies at which longitudes to draw the meridians.

Possible types

None

Don’t draw gridlines (same as False)

bool

True: draw gridlines and determine position automatically False: don’t draw gridlines

numeric array

specifies the ticks manually

str or list [str, …]

A list of the below mentioned values of the mapping like [method, N, percmin, percmax, vmin, vmax], where only the first one is absolutely necessary

dict

Automatically determine the ticks corresponding to the data. The mapping can have the following keys, but only method is not optional.

N

An integer describing the number of boundaries (or ticks per power of ten, see log and symlog above)

percmin

The percentile to use for the minimum (by default, 0, i.e. the minimum of the array)

percmax

The percentile to use for the maximum (by default, 100, i.e. the maximum of the array)

vmin

The minimum to use (in which case it is not calculated from the specified method)

vmax

The maximum to use (in which case it is not calculated from the specified method)

method

A string that defines how minimum and maximum shall be set. This argument is not optional and can be one of the following:

data: plot the ticks exactly where the data is.
mid: plot the ticks in the middle of the data.
rounded: Sets the minimum and maximum of the ticks to the rounded data minimum or maximum. Ticks are rounded to the next 0.5 value with to the difference between data max- and minimum. The minimal tick will always be lower or equal than the data minimum, the maximal tick will always be higher or equal than the data maximum.
roundedsym: Same as rounded above but the ticks are chose such that they are symmetric around zero
minmax: Uses the minimum as minimal tick and maximum as maximal tick
sym: Same as minmax but symmetric around zero
log: Use logarithmic bounds. In this case, the given number N determines the number of bounds per power of tenth (i.e. N == 2 results in something like 1.0, 5.0, 10.0, 50.0, etc., If this second number is None, then it will be chosen such that we have around 11 boundaries but at least one per power of ten.
symlog: The same as log but symmetric around 0. If the number N is None, then we have around 12 boundaries but at least one per power of ten

int

Specifies how many ticks to use with the 'rounded' option. I.e. if integer i, then this is the same as ['rounded', i].

See also

ygrid, grid_color, grid_labels

ygrid

Draw horizontal grid lines (parallels)

This formatoption specifies at which latitudes to draw the parallels.

Possible types

None

Don’t draw gridlines (same as False)

bool

True: draw gridlines and determine position automatically False: don’t draw gridlines

numeric array

specifies the ticks manually

str or list [str, …]

A list of the below mentioned values of the mapping like [method, N, percmin, percmax, vmin, vmax], where only the first one is absolutely necessary

dict

Automatically determine the ticks corresponding to the data. The mapping can have the following keys, but only method is not optional.

N

An integer describing the number of boundaries (or ticks per power of ten, see log and symlog above)

percmin

The percentile to use for the minimum (by default, 0, i.e. the minimum of the array)

percmax

The percentile to use for the maximum (by default, 100, i.e. the maximum of the array)

vmin

The minimum to use (in which case it is not calculated from the specified method)

vmax

The maximum to use (in which case it is not calculated from the specified method)

method

A string that defines how minimum and maximum shall be set. This argument is not optional and can be one of the following:

data: plot the ticks exactly where the data is.
mid: plot the ticks in the middle of the data.
rounded: Sets the minimum and maximum of the ticks to the rounded data minimum or maximum. Ticks are rounded to the next 0.5 value with to the difference between data max- and minimum. The minimal tick will always be lower or equal than the data minimum, the maximal tick will always be higher or equal than the data maximum.
roundedsym: Same as rounded above but the ticks are chose such that they are symmetric around zero
minmax: Uses the minimum as minimal tick and maximum as maximal tick
sym: Same as minmax but symmetric around zero
log: Use logarithmic bounds. In this case, the given number N determines the number of bounds per power of tenth (i.e. N == 2 results in something like 1.0, 5.0, 10.0, 50.0, etc., If this second number is None, then it will be chosen such that we have around 11 boundaries but at least one per power of ten.
symlog: The same as log but symmetric around 0. If the number N is None, then we have around 12 boundaries but at least one per power of ten

int

Specifies how many ticks to use with the 'rounded' option. I.e. if integer i, then this is the same as ['rounded', i].

See also

xgrid, grid_color, grid_labels

class psy_transect.maps.MapTransectDataGrid(*args, **kwargs)

Bases: MapDataGrid

Attributes:

`mask_datagrid`	mask_datagrid Formatoption instance in the plotter
`plot`	plot Formatoption instance in the plotter
`raw_data`	The original data of the plotter of this formatoption
`transform`	transform Formatoption instance in the plotter

property mask_datagrid: mask_datagrid Formatoption instance in the plotter

property plot: plot Formatoption instance in the plotter

property raw_data: The original data of the plotter of this formatoption

property transform: transform Formatoption instance in the plotter

class psy_transect.maps.MapTransectMapPlot2D(*args, **kwargs)

Bases: MapPlot2D

Attributes:

`bounds`	bounds Formatoption instance in the plotter
`clip`	clip Formatoption instance in the plotter
`cmap`	cmap Formatoption instance in the plotter
`data_dependent`	`bool` or a callable.
`interp_bounds`	interp_bounds Formatoption instance in the plotter
`levels`	levels Formatoption instance in the plotter
`lonlatbox`	lonlatbox Formatoption instance in the plotter
`raw_data`	The original data of the plotter of this formatoption
`transform`	transform Formatoption instance in the plotter

property bounds: bounds Formatoption instance in the plotter

property clip: clip Formatoption instance in the plotter

property cmap: cmap Formatoption instance in the plotter

data_dependent = True: bool or a callable. This attribute indicates whether this Formatoption depends on the data and should be updated if the data changes. If it is a callable, it must accept one argument: the new data. (Note: This is automatically set to True for plot formatoptions)

property interp_bounds: interp_bounds Formatoption instance in the plotter

property levels: levels Formatoption instance in the plotter

property lonlatbox: lonlatbox Formatoption instance in the plotter

property raw_data: The original data of the plotter of this formatoption

property transform: transform Formatoption instance in the plotter