Reference on kuibit.visualize_matplotlib

The visualize_matplotlib module provides methods to plot kuibit objects with matplotlib and other convenience functions.

Utilities:

  • setup_matplotlib() adjusts the configuration in matplotlib.

  • add_text_to_corner() adds a label near an edge or a corner of a figure (useful for annotations like time).

  • save() saves the figure, optionally with tikzplotlib.

  • save_from_dir_filename_ext() saves the figure and assembles the name automatically from the output directory, file name and extension.

  • set_axis_limits() sets the range on the two axes of a given axis. set_axis_limits_from_args() does the same but reading the data from a given args (from ArgParse).

Two decorators:

  • preprocess_plot(). The goal of this is to add support to the keyword arguments figure and axis. If you decorate a function with preprocess_plot() and the function takes those two arguments, then the decorator will automatically check if the arguments were passed and if not set the correct default.

  • preprocess_plot_grid(). This decorator takes some form of grid data and returns a NumPy array (and other useful quantities). Functions decorated with preprocess_plot_grid() automatically gain support for HierarchicalGridData and UniformGridData, so they only need to worry about plotting NumPy arrays. Functions have to take a positional argument data and a keyword argument coordinates.

Grid data:

Horizons:

  • plot_horizon() to plot a given shape in 2D.

  • plot_horizon_on_plane_at_iteration() to plot a given horizon

    at a given iteration in 2D.

  • plot_horizon_on_plane_at_time() to plot a given horizon

    at a given time in 2D.

Most of the functions here take optional arguments figure and axis. You can specify them, or the current ones will be used.

kuibit.visualize_matplotlib.get_figname(args, default)[source]

Return the figure name checking if the user has passed one.

If it is defined, return args.figname, otherwise return default.

Parameters:

  • args (argparse.Namespace) – Options provided by the user.

  • default (str) – Default name if figname is not in args.

Returns:

Name of the output figure.

Return type:

str

kuibit.visualize_matplotlib.plot_color(data, **kwargs)[source]

Plot the given data.

You can pass (everything is processed by preprocess_plot_grid() so that at the end we have a 2D NumPy array): - A 2D NumPy array, - A UniformGridData, - A HierarchicalGridData, - A BaseOneGridFunction.

Depending on what you pass, you might need additional arguments.

If you pass a BaseOneGridFunction, you need also to pass iteration, and shape. If you pass HierarchicalGridData, you also need to pass shape. In all cases you can also pass x0 and x1 to define origin and corner of the grid. You can pass the option resample=True if you want to do bilinear resampling at the grid data level, otherwise, nearest neighbor resampling is done. When you pass the NumPy array, passing coordinates will argument will make sure that those coordinates are used.

All the unknown arguments are passed to imshow.

Parameters:

  • data (2D NumPy array, or object that can be cast to 2D NumPy array.) – Data that has to be plotted. The function expects a 2D NumPy array, but the decorator preprocess_plot_grid() allows it to take different kind of data.

  • x0 (2D array or list) – Lowermost leftmost coordinate to plot. If passed, resampling will be performed.

  • x1 (2D array or list) – Uppermost rightmost coordinate to plot. If passed, resampling will be performed.

  • coordiantes – Coordinates to use for the plot. Used only if data is a NumPy array.

  • shape (tuple or list) – Resolution of the image. This parameter is used if resampling is needed or requested.

  • iteration (int) – Iteration to plot. Relevant only if data is a BaseOneGridData.

  • resample (bool) – If resampling has to be done, do bilinear resampling at the level of the grid data. If not passed, use nearest neighbors.

  • logscale (bool) – If True, take the log10 of the data before plotting.

  • colorbar (bool) – If True, add a colorbar.

  • vmin (float) – Remove all the data below this value. If logscale, this has to be the log10.

  • vmax (float) – Remove all the data above this value. If logscale, this has to be the log10.

  • xlabel (str) – Label of the x axis. If None (or not passed), no label is placed.

  • ylabel (str) – Label of the y axis. If None (or not passed), no label is placed.

  • aspect_ratio (str) – Aspect ratio of the plot, as passed to the function set_aspect_ratio in matplotlib.

  • figure (matplotlib.pyplot.figure) – If passed, plot on this figure. If not passed (or if None), use the current figure.

  • axis (matplotlib.pyplot.axis) – If passed, plot on this axis. If not passed (or if None), use the current axis.

  • kwargs (dict) – All the unknown arguments are passed to imshow.

kuibit.visualize_matplotlib.plot_contour(data, levels=5, **kwargs)[source]

Plot the given data drawing the contours.

You can pass (everything is processed by preprocess_plot_grid() so that at the end we have a 2D NumPy array): - A 2D NumPy array, - A UniformGridData, - A HierarchicalGridData, - A BaseOneGridFunction.

Depending on what you pass, you might need additional arguments.

If you pass a BaseOneGridFunction, you need also to pass iteration, and shape. If you pass HierarchicalGridData, you also need to pass shape. In all cases you can also pass x0 and x1 to define origin and corner of the grid. You can pass the option resample=True if you want to do bilinear resampling at the grid data level, otherwise, nearest neighbor resampling is done. When you pass the NumPy array, you also have to pass the coordinates.

levels can be an integer (the number of levels), or an array with the specific values where to put the levels.

All the unknown arguments are passed to contour.

Parameters:

  • data (2D NumPy array, or object that can be cast to 2D NumPy array.) – Data that has to be plotted. The function expects a 2D NumPy array, but the decorator preprocess_plot_grid() allows it to take different kind of data.

  • x0 (2D array or list) – Lowermost leftmost coordinate to plot. If passed, resampling will be performed.

  • x1 (2D array or list) – Uppermost rightmost coordinate to plot. If passed, resampling will be performed.

  • coordiantes – Coordinates to use for the plot. Used only if data is a NumPy array.

  • shape (tuple or list) – Resolution of the image. This parameter is used if resampling is needed or requested.

  • iteration (int) – Iteration to plot. Relevant only if data is a BaseOneGridData.

  • resample (bool) – If resampling has to be done, do bilinear resampling at the level of the grid data. If not passed, use nearest neighbors.

  • logscale (bool) – If True, take the log10 of the data before plotting.

  • colorbar (bool) – If True, add a colorbar.

  • vmin (float) – Remove all the data below this value. If logscale, this has to be the log10.

  • vmax (float) – Remove all the data above this value. If logscale, this has to be the log10.

  • xlabel (str) – Label of the x axis. If None (or not passed), no label is placed.

  • ylabel (str) – Label of the y axis. If None (or not passed), no label is placed.

  • levels (int or list) – If int, the number of levels, if array, the specific levels where to place the contour lines.

  • aspect_ratio (str) – Aspect ratio of the plot, as passed to the function set_aspect_ratio in matplotlib.

  • figure (matplotlib.pyplot.figure) – If passed, plot on this figure. If not passed (or if None), use the current figure.

  • axis (matplotlib.pyplot.axis) – If passed, plot on this axis. If not passed (or if None), use the current axis.

  • kwargs (dict) – All the unknown arguments are passed to imshow.

kuibit.visualize_matplotlib.plot_contourf(data, **kwargs)[source]

Plot the given data drawing filled contours.

You can pass (everything is processed by preprocess_plot_grid() so that at the end we have a 2D NumPy array): - A 2D NumPy array, - A UniformGridData, - A HierarchicalGridData, - A BaseOneGridFunction.

Depending on what you pass, you might need additional arguments.

If you pass a BaseOneGridFunction, you need also to pass iteration, and shape. If you pass HierarchicalGridData, you also need to pass shape. In all cases you can also pass x0 and x1 to define origin and corner of the grid. You can pass the option resample=True if you want to do bilinear resampling at the grid data level, otherwise, nearest neighbor resampling is done. When you pass the NumPy array, you also have to pass the coordinates.

All the unknown arguments are passed to contourf.

Parameters:

  • data (2D NumPy array, or object that can be cast to 2D NumPy array.) – Data that has to be plotted. The function expects a 2D NumPy array, but the decorator preprocess_plot_grid() allows it to take different kind of data.

  • x0 (2D array or list) – Lowermost leftmost coordinate to plot. If passed, resampling will be performed.

  • x1 (2D array or list) – Uppermost rightmost coordinate to plot. If passed, resampling will be performed.

  • coordiantes – Coordinates to use for the plot. Used only if data is a NumPy array.

  • shape (tuple or list) – Resolution of the image. This parameter is used if resampling is needed or requested.

  • iteration (int) – Iteration to plot. Relevant only if data is a BaseOneGridData.

  • resample (bool) – If resampling has to be done, do bilinear resampling at the level of the grid data. If not passed, use nearest neighbors.

  • logscale (bool) – If True, take the log10 of the data before plotting.

  • colorbar (bool) – If True, add a colorbar.

  • vmin (float) – Remove all the data below this value. If logscale, this has to be the log10.

  • vmax (float) – Remove all the data above this value. If logscale, this has to be the log10.

  • xlabel (str) – Label of the x axis. If None (or not passed), no label is placed.

  • ylabel (str) – Label of the y axis. If None (or not passed), no label is placed.

  • aspect_ratio (str) – Aspect ratio of the plot, as passed to the function set_aspect_ratio in matplotlib.

  • figure (matplotlib.pyplot.figure) – If passed, plot on this figure. If not passed (or if None), use the current figure.

  • axis (matplotlib.pyplot.axis) – If passed, plot on this axis. If not passed (or if None), use the current axis.

  • kwargs (dict) – All the unknown arguments are passed to imshow.

kuibit.visualize_matplotlib.preprocess_plot(func)[source]

Decorator to set-up plot functions.

When we plot anything, there is always some boilerplate that has to be executed. For example, we want to provide an axis keyword so that the user can specify where to plot, but if the keyword is not provided, we want to plot on the current figure.

Essentially, this decorator sets default values. Why don’t we do axis=plt.gca() then? The problem is that the default values are set when the function is defined, not when it is called. So, this will not work.

This decorator takes care of everything.

  1. It handles the axis keyword setting it to plt.gca() if it was not provided.

  2. It handles the figure keyword setting it to plt.gcf() if it was not provided.

func has to take as keyword arguments: 1. ‘axis=None’, where the plot will be plot, or plt.gca() if None 2. ‘figure=None’, where the plot will be plot, or plt.gcf() if None

kuibit.visualize_matplotlib.preprocess_plot_grid(func)[source]

Decorator to set-up plot functions that plot grid data.

This decorator extends preprocess_plot() for specific functions.

  1. It handles differt types to plot what intuitively one would want to plot.

1a. If the data is a NumPy array with shape 2, just pass the data,

otherwise raise an error

1b. If the data is a NumPy array, just pass the data. 1c. If data is UniformGridData, pass the data and the

coordinates.

1d. If data is HierarchicalGridData, read resample it to

the given grid, then pass do 1c.

1e. If data is a BaseOneGridFunction, we read the iteration

and pass to 1d.

func has to take as keyword arguments (in addition to the ones in :py:func`~.preprocess_plot`): 1. ‘data’. data will be passed as a NumPy array, unless it is

already so.

  1. ‘coordinates=None’. coordinates will be passed as a list of NumPy

    arrays, unless it is not None. Each NumPy array is the coordinates along one axis.

kuibit.visualize_matplotlib.setup_matplotlib(params=None, rc_par_file=None)[source]

Setup matplotlib with some reasonable defaults for better plots.

If params is provided, add these parameters to matplotlib’s settings (params updates matplotlib.rcParams).

If rc_par_file is provided, first set the parameters reading the values from the rc_par_file. (params has the precedence over the parameters read from the file.)

Matplotlib behaves differently on different machines. With this, we make sure that we set all the relevant paramters that we care of to the value we prefer. The default values are highly opinionated.

Parameters:

  • params (dict) – Parameters to update matplotlib with.

  • rc_par_file (str) – File where to read parameters. The file has to use matplotlib’s configuration language. params overwrites the values set from this file, but this file overrides the default values set in this function.

Return type:

None