ozzy.plot

In order to set ozzy's aesthetic options as defaults, and to have access to its color maps, color schemes and fonts, the plotting submodule must be imported:

import ozzy.plot as oplt

Defaults

The default plotting options loaded as matplotlib rcParams by ozzy can be printed with:

import ozzy.plot as oplt
print(oplt.ozparams)

The remaining defaults are:

Defaults
Curve color scheme	'tol.muted'
Sequential colormap	'cmc.lipari'
Diverging colormap	'cmc.vik'
Font	Noto Serif

Functions

imovie

imovie(
    da,
    tvar="t",
    clim="first",
    colormap=None,
    widget_location="bottom",
    **kwargs
)

Creates an interactive movie/animation plot from a DataArray using HoloViews.

Parameters:

Name	Type	Description	Default
da	DataArray	Input data array to animate.	required
tvar	str	Name of the time coordinate in the DataArray.	't'
clim	str | tuple of float	Color limits specification. Can be: - "first": Use min/max of first time step - "global": Use global min/max across all time steps - None: Color scale changes at every time step - tuple of (min, max) values	'first'
colormap	str	Name of colormap to use. If None, automatically selects: - "cmc.lipari" for single-signed data - "cmc.vik" for data crossing zero	None
widget_location	str	Location of the time selection widget.	'bottom'
**kwargs	dict	Additional keyword arguments passed to hvplot.	{}

Returns:

Type	Description
HoloMap	Interactive HoloViews plot object.

Raises:

Type	Description
ValueError	If specified time variable is not found in coordinates. If clim is invalid type or wrong length.

Examples:

Basic usage with default settings

import ozzy as oz
import ozzy.plot as oplt
import numpy as np

# Create sample data
time = np.arange(10)
data = np.random.rand(10, 20, 30)
da = oz.DataArray(data, coords={'t': time, 'y': range(20), 'x': range(30)})

# Create interactive plot
oplt.imovie(da)

Custom time coordinate and color limits

... # see example above

# Create data with custom time coordinate
da = oz.DataArray(data, coords={'time': time, 'y': range(20), 'x': range(30)})

# Plot with custom settings
oplt.imovie(da, tvar='time', clim=(-1, 1), colormap='cmc.lisbon')

movie

movie(
    fig,
    plot_objs,
    filename,
    fps=5,
    dpi=300,
    t_range=None,
    xlim=None,
    ylim=None,
    clim=None,
    clim_fixed=True,
    plot_func=None,
    writer="ffmpeg",
    **kwargs
)

Create an animation from matplotlib figure objects.

Parameters:

Name	Type	Description	Default
fig	Figure	The matplotlib Figure object to animate.	required
plot_objs	dict[Artist, tuple[DataArray, str]] | dict[Artist, DataArray]	A dictionary mapping matplotlib Artist objects to either tuples containing a DataArray and the name of its time coordinate, or to a DataArray (where the time coordinate is assumed to be 't').	required
filename	str	The output file name or path for the animation. If the path doesn't exist, missing folders will be created.	required
fps	int	Frames per second for the animation.	5
dpi	int	Dots-per-inch resolution for the output.	300
t_range	tuple[float, float] | None	The time range for the animation. If None, the full time range of the data will be used.	None
xlim	tuple[float, float] | None | dict[Artist, tuple[float, float]]	The horizontal axis limits. Can be a tuple, None, or a dictionary mapping Artists to their respective limits.	None
ylim	tuple[float, float] | None | dict[Artist, tuple[float, float]]	The vertical axis limits. Can be a tuple, None, or a dictionary mapping Artists to their respective limits.	None
clim	tuple[float, float] | None | dict[Artist, tuple[float, float]]	The color scale limits. Can be a tuple, None, or a dictionary mapping Artists to their respective limits.	None
clim_fixed	bool	If False, color scale limits vary for each time step.	True
plot_func	Callable | dict[Artist, Callable] | None	A function or dictionary of functions to customize the plot at each time step. Each function must take 5 arguments in this order: ax (matplotlib Axes), imo (matplotlib Artist), da (DataArray), tvar (str), tval (float), and return None. The function overrides axis limits.	None
writer	str	The matplotlib animation writer to use. Options are 'ffmpeg', 'pillow', 'html', 'imagemagick', and 'frames_png'. When 'frames_png' is selected, no writer is used and the animation frames are saved to a folder in PNG format. Info The FFMpeg library must be installed on the system in order to use matplotlib's FFMpeg writer.	'ffmpeg'
**kwargs		Additional keyword arguments to pass to the matplotlib animation writer. Note For writer='ffmpeg', a constant rate factor of 18 is set by default via extra_args=['-crf', '18']. See FFMpegWriter.	{}

Returns:

Type	Description
None

Examples:

Basic usage with a single plot object

import matplotlib.pyplot as plt
import numpy as np

import ozzy as oz
import ozzy.plot as oplt

time = np.arange(0, 10, 0.1)
x = np.arange(-20, 0, 0.2)
X, T = np.meshgrid(x, time)
data = np.sin(X - 0.5 * T)
da = oz.DataArray(
    data, coords={"time": time, "x": x}, dims=["time", "x"], pic_data_type="grid"
)

# Create a figure and plot
fig, ax = plt.subplots()
line = da.isel(time=0).plot()

# Create the movie
oplt.movie(fig, {line[0]: (da, "time")}, "sine_wave.mp4")
# This will create an animation of a sine wave in 'sine_wave.mp4'

Using multiple plot objects and custom limits

import matplotlib.pyplot as plt
import numpy as np

import ozzy as oz
import ozzy.plot as oplt

time = np.arange(0, 10, 0.1)
x = np.arange(-20, 0, 0.2)
X, T = np.meshgrid(x, time)
data1 = np.sin(X - 0.5 * T)
data2 = np.cos(X - 0.5 * T)
da1 = oz.DataArray(
    data1, coords={"time": time, "x": x}, dims=["time", "x"], pic_data_type="grid"
)
da2 = oz.DataArray(
    data2, coords={"time": time, "x": x}, dims=["time", "x"], pic_data_type="grid"
)

# Create a figure with two subplots
fig, (ax1, ax2) = plt.subplots(2, 1)
(line1,) = da1.isel(time=0).plot(ax=ax1)
(line2,) = da2.isel(time=0).plot(ax=ax2)

# Create the movie with custom limits
oplt.movie(
    fig,
    {line1: (da1, "time"), line2: (da2, "time")},
    "trig_functions.mp4",
    xlim={line1: (-5, 0), line2: (-20, -5)},
    ylim=(-1.5, 1.5),
    fps=10,
)
# This will create an animation of sine and cosine waves
# with different x-axis limits for each subplot

set_cmap

set_cmap(
    general=None,
    qualitative=None,
    diverging=None,
    sequential=None,
)

Set the default colormaps for various types of plots.

Parameters:

Name	Type	Description	Default
general	str	The colormap to use for general plots.	None
qualitative	str | list[str]	The colormap or list of colors to use for qualitative plots (e.g., line plots).	None
diverging	str	The colormap to use for diverging plots.	None
sequential	str	The colormap to use for sequential plots.	None

Examples:

Set general colormap to viridis

import ozzy.plot as oplt
oplt.set_cmap(general='viridis')

Set diverging and sequential colormaps separately

import ozzy.plot as oplt
oplt.set_cmap(diverging='cmc.lisbon', sequential='tol.iridescent')

Set qualitative colormap to Paul Tol's Bright color scheme

import ozzy.plot as oplt
oplt.set_cmap(qualitative='tol.bright')

set_font

set_font(font)

Set the font family for all text in the plots.

Note

If you want all text in the plot to be rendered in LaTeX math font, as opposed to only the text surrounded by $...$, use the following commands:

import ozzy.plot as oplt
oplt.plt.rcParams['text.usetex'] = True

or

import ozzy.plot as oplt
import matplotlib.pyplot as plt
plt.rcParams["text.usetex"] = True

Parameters:

Name	Type	Description	Default
font	str	The name of the font family to use. The font must be installed on the system and recognized by matplotlib.font_manager.get_font_names().	required

Raises:

Type	Description
ValueError	If the specified font is not found in the list of available font names.

Examples:

Set font to DejaVu Sans

import ozzy.plot as oplt
oplt.set_font('DejaVu Sans')

Attempt to set an invalid font

import ozzy.plot as oplt
oplt.set_font('InvalidFontName')
# ValueError: Couldn't find font

show_cmaps

show_cmaps(library='all', category='all')

Display available colormaps from different libraries and categories.

Parameters:

Name	Type	Description	Default
library	str | list[str]	The library or libraries to display colormaps from. Options are 'mpl' (Matplotlib), 'cmc' (Scientific colour maps by F. Crameri), 'tol' (Paul Tol's colormaps), and 'all'.	'all'
category	str | list[str]	The category or categories of colormaps to display. Options are 'sequential', 'diverging', 'qualitative', 'cyclical', and 'all'.	'all'

Examples:

Show all available colormaps

import ozzy.plot as oplt
oplt.show_cmaps()

Show sequential colormaps from Matplotlib

import ozzy.plot as oplt
oplt.show_cmaps(library='mpl', category='sequential')

Show diverging colormaps from Paul Tol and Scientific colour maps

import ozzy.plot as oplt
oplt.show_cmaps(library=['tol', 'cmc'], category='diverging')

show_fonts

show_fonts(samples=False, fontsize=18)

Display a list of fonts bundled with ozzy and other fonts available on the system.

Parameters:

Name	Type	Description	Default
samples	bool	If True, display font samples in addition to the font names. Warning The font samples are rendered as an HTML object (only works with Jupyter).	False
fontsize	float	The font size to use for displaying font samples.	18

Examples:

Show font names only

import ozzy.plot as oplt
oplt.show_fonts()

Show font names and samples

import ozzy.plot as oplt
oplt.show_fonts(samples=True)