pyfvcom2.plotting package

Module contents

Plotting subpackage for pyfvcom2

This module exports the plotting classes and helper functions. Users can import from pyfvcom2.plotting for a cleaner API.

class pyfvcom2.plotting.CMEMSPlotter(cmems_file_name: str, font_size: int | None = 10, line_width: float | None = 0.2)[source]

Bases: PyFVCOM2Plotter

Class for plotting CMEMS data

Args:: cmems_file_name (str): Path to a CMEMS NetCDF file. font_size (int, optional): Font size for plot text. Default 10. line_width (float, optional): Default line width for plotting. Default 0.2.

Map the supplied field

Additional plotting options are passed to matplotlib.pyplot.pcolormesh. See the matplotlib documentation for a full list of supported options.

Args:: ax (matplotlib.axes.Axes): Axes object. field (np.ndarray): The field to plot. configure (bool, optional): If true, configure the plot by setting plot extents, drawing coastlines etc. Default: True. add_colour_bar (bool, optional): If true, draw a colour bar. Default: True. cb_label (str, optional): The colour bar label. tick_inc (bool, optional): Add coordinate axes (i.e. lat/long). Default: True. extents (list, optional): Four element numpy array giving lon/lat limits (e.g. [-4.56, -3.76, 49.96, 50.44]). Default: None. draw_coastlines (bool, optional): Draw coastlines. Default: False. resolution (str, optional): Resolution to use when plotting the coastline. Only used when draw_coastline=True. Default: ‘10m’. **kwargs: Additional keyword arguments passed to matplotlib pcolormesh.
Returns:: tuple: (axes, plot) - Axes object and PolyCollection plot object.

Create a CMEMS-specific scatter plot using the provided x and y values

Args:: ax (matplotlib.axes.Axes): Axes object x (np.ndarray): Array of longitude positions. y (np.ndarray): Array of latitude positions. c (np.ndarray, optional): Array of colour values for each point. configure (bool, optional): If true, configure the plot by setting extents, coastlines etc. extents (list, optional): Four element list giving lon/lat limits transform (ccrs.Projection, optional): Transform for geographic projections (uses self.transform if None) draw_coastlines (bool, optional): Draw coastlines. resolution (str, optional): Coastline resolution. Default: ‘10m’. tick_inc (bool, optional): Draw ticks. **kwargs: Additional keyword arguments passed to matplotlib scatter
Returns:: tuple: (ax, scatter_plot) - Axes object and scatter plot collection

Bases: PyFVCOM2Plotter

Create FVCOM plot objects based on FVCOM model outputs or Grid objects

Class to assist in the creation of plots and animations based on FVCOM data. Grid information can be provided either from a FVCOM NetCDF file or from a pre-existing Grid object.

Args:

fvcom_source (Union[str, Path, Grid]): Either a path to a FVCOM NetCDF file: (as string or Path object) or a Grid object containing the mesh information.
geographic_coords (bool, optional): Whether to use geographic coordinates.: Default True. Ignored if fvcom_source is a Grid object.

font_size (int, optional): Font size for plot text. Default 10. line_width (float, optional): Default line width for plotting. Default 0.2.

draw_grid(ax: Axes, **kwargs)[source]

Draw the underlying grid or mesh

Args:: ax (matplotlib.axes.Axes): Axes object **kwargs: Additional keyword arguments passed to matplotlib triplot
Returns:: matplotlib.axes.Axes: Axes object

Map the supplied field

The field must be defined on the same triangular mesh that was used to initialise the plotter.

Additional plotting options are passed to matplotlib.pyplot.pcolormesh. See the matplotlib documentation for a full list of supported options.

Args:

ax (matplotlib.axes.Axes): Axes object field (np.ndarray): The field to plot. update (bool, optional): If true, update the existing plot. Specifically, the axes will be checked to see if it contains a

PolyCollection object, as generated by tripcolor. If found, the associated data array will be updated with the supplied field data. This is faster than drawing a new map

configure (bool, optional): If true, configure the plot by setting plot extents, drawing coastlines etc. This can be: useful when overlaying plots, and you only want to incur the cost of configuring the plot once. The default is True, with the expectation that in most circumstances users will draw any underlying field data before overlaying particle tracks. Default: True.

add_colour_bar (bool, optional): If true, draw a colour bar. cb_label (str, optional): The colour bar label. tick_inc (bool, optional): Add coordinate axes (i.e. lat/long). extents (list, optional): Four element numpy array giving lon/lat limits (e.g. [-4.56, -3.76, 49.96, 50.44]) draw_coastlines (bool, optional): Draw coastlines. Default False. resolution (str, optional): Resolution to use when plotting the coastline. Only used when draw_coastline=True. Default: ‘10m’. **kwargs: Additional keyword arguments passed to matplotlib tripcolor

Returns:

tuple: (axes, plot) - Axes object and PolyCollection plot object

Produce a quiver plot of the supplied velocity field.

Args:

ax (matplotlib.axes.Axes): Axes object on which to plot. u (np.ndarray): 1D array of u velocity components defined at element centres. v (np.ndarray): 1D array of v velocity components defined at element centres. configure (bool, optional): If True, configure the plot by setting plot extents, drawing coastlines etc. Default: True. update (bool, optional): If True, update the existing plot. Specifically, the axes will be checked to see if

it contains a Quiver object. If found, the associated data arrays will be updated with the supplied u and v data. This is faster than drawing a new map. Default: False.

tick_inc (bool, optional): Add coordinate axes (i.e. lat/long). Default: True. extents (np.ndarray, optional): Four element numpy array giving lon/lat limits (e.g. [-4.56, -3.76, 49.96, 50.44]).

If None, will use default extents from the grid. Default: None.

draw_coastlines (bool, optional): Draw coastlines. Only used if geographic_coords is True. Default: False. resolution (str, optional): Resolution to use when plotting the coastline. Only used when draw_coastlines=True.

Default: ‘10m’.

point_res (int, optional): Plot every n-th arrow, where n = point_res. Default: 1 (plot every arrow). scale (float, optional): Scaling factor for quiver plot. Default: 0.5. quiver_key_x (float, optional): X position for quiver key in axes coordinates. Default: 0.9. quiver_key_y (float, optional): Y position for quiver key in axes coordinates. Default: 0.9. quiver_key_value (float, optional): Reference velocity value for the quiver key. Default: 0.5. quiver_key_label (str, optional): Custom label for the quiver key. If None, will use default format. Default: None. **kwargs: Additional keyword arguments passed to matplotlib’s quiver function.

Returns:

matplotlib.axes.Axes: The axes object with the quiver plot.

Raises:

ValueError: If u and v arrays have different shapes, are not 1D, or don’t match the number of elements. RuntimeError: If update=True but no existing Quiver object is found on the axes.

Create an FVCOM-specific scatter plot using the provided x and y values

Args:: ax (matplotlib.axes.Axes): Axes object x (np.ndarray): Array of ‘x’ positions. If plotting in geographic coords, these should be longitudes. y (np.ndarray): Array of ‘y’ positions. If plotting in geographic coords, these should be latitudes. c (np.ndarray, optional): Array of colour values for each point. configure (bool, optional): If true, configure the plot by setting extents, coastlines etc. extents (list, optional): Four element list giving lon/lat limits transform (ccrs.Projection, optional): Transform for geographic projections draw_coastlines (bool, optional): Draw coastlines? Only used if geographic_coords is True. resolution (str, optional): Coastline resolution. Default: ‘10m’. tick_inc (bool, optional): Draw ticks? Only used if geographic_coords is True. **kwargs: Additional keyword arguments passed to matplotlib scatter
Returns:: tuple: (ax, scatter_plot) - Axes object and scatter plot collection

class pyfvcom2.plotting.PyFVCOM2Plotter(geographic_coords: bool | None = True, font_size: int | None = 10, line_width: float | None = 0.2)[source]

Bases: object

Base class for PyFVCOM2 plotters

Class to assist in the creation of plots and animations. The class can be used to create a set of basic plot objects. Plots that overlay particle trajectories on top of underlying field data should be created using the appropriate derived class.

Args:

geographic_coords (bool, optional): Boolean specifying whether or not to use cartopy to create a 2D map: on top of which the data will be plotted. The default option is True. If False, a simple Cartesian grid is drawn instead.

font_size (int, optional): Font size to use when rendering plot text line_width (float, optional): Default line width to use when plotting

abstractmethod plot_field(ax: Axes, field: ndarray, **kwargs) → Axes[source]

Map the supplied field

Additional plotting options are passed to matplotlib.pyplot.pcolormesh. See the matplotlib documentation for a full list of supported options.

Args:: ax (matplotlib.axes.Axes): Axes object field (np.ndarray): The field to plot.
Returns:: matplotlib.axes.Axes: Axes object

plot_lines(ax: Axes, x: ndarray, y: ndarray, transform: cartopy.crs.Projection | None = None, **kwargs)[source]

Plot path lines.

In addition to the listed parameters, the function accepts all keyword arguments taken by the Matplotlib plot command.

Args:: ax (matplotlib.axes.Axes): Axes object x (np.ndarray): Array of x coordinates to plot. y (np.ndarray): Array of y coordinates to plot. transform (ccrs.Projection, optional): Transform for geographic projections **kwargs: Additional keyword arguments passed to matplotlib plot
Returns:: tuple: (axes, line_plots) - Axes object and list of line plot objects

remove_line_plots(line_plots: list)[source]

Remove line plots

Useful when updating plots for animations.

Args:: line_plots (list): List of line plot objects created during call to plot_lines()

Create a scatter plot using the provided x and y values

If geographic_coords is True, x and y should be geographic (lat, lon) coordinates. If not, x any y should be given as cartesian coordinates.

See Matplotlib’s scatter documentation for a list of additional key word arguments.

Args:: ax (matplotlib.axes.Axes): Axes object x (np.ndarray): Array of ‘x’ positions. If plotting in geographic coords, these should be longitudes. y (np.ndarray): Array of ‘y’ positions. If plotting in geographic coords, these should be latitudes. c (np.ndarray, optional): Array of colour values for each point. If provided, this will be used to colour the points in the scatter plot. configure (bool, optional): If true, configure the plot by setting plot extents, drawing coastlines etc. Default: False. extents (list, optional): Four element list giving lon/lat limits (e.g. [-4.56, -3.76, 55.12, 55.84]) transform (ccrs.Projection, optional): The type of transform to perform if geographic_coords is True. draw_coastlines (bool, optional): Draw coastlines? Only used if geographic_coords is True. resolution (str, optional): Resolution to use when plotting the coastline. Only used when draw_coastline=True. Default: ‘10m’. tick_inc (bool, optional): Draw ticks? Only used if geographic_coords is True. **kwargs: Additional keyword arguments passed to matplotlib scatter
Returns:: tuple: (ax, scatter_plot) - Axes object and scatter plot collection

set_title(ax, title)[source]

Set the title

Args:: ax (matplotlib.axes.Axes): Axes object title (str): Plot title

pyfvcom2.plotting.cm2inch(value: float) → float[source]

Convert centimetres to inches.

Args:: value (float): Length in cm.
Returns:: float: Length in inches.

pyfvcom2.plotting.colourmap(variable: str) → Colormap[source]

Use a predefined colour map for a given variable.

Leverages the cmocean package for perceptually uniform colour maps.

Args:

variable (str): For the given variable name, return the appropriate colour: palette from the cmocean/matplotlib colour maps. If the variable is not in the pre-defined variables here, the returned values will be viridis.

Returns:

matplotlib.colors.Colormap: The colour map for the variable given.

pyfvcom2.plotting.create_cbar_ax(ax: Axes)[source]

Create colorbar axis alligned with plot axis y limits

Args:: ax (matplotlib.axes.Axes): Plot axes instance
Returns:: matplotlib.axes.Axes: Colorbar plot axis

Create a Figure object

Args:: figure_size (tuple, optional): Figure size in cm. This is only used if a new Figure object is created. font_size (int, optional): Font size to use for axis labels axis_position (list, optional): Array giving axis dimensions projection (ccrs.Projection, optional): Cartopy projection to use for the plot. If None, a projection will not be used. bg_color (str, optional): Colour to use for the axis background. Default is white. When

creating a figure for plotting FVCOM outputs, it can be useful to set this to gray. When FVCOM is fitted to a coastline, the gray areas mark the land boundary used by the model. This provides a fast alternative to plotting a high resolution (e.g. res = f) land boundary using methods provided by the Basemap class instance.
Returns:: tuple: (figure, axes) - Figure and Axes objects

pyfvcom2.plotting package

Submodules

Module contents