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 givenargs
(fromArgParse
).
Two decorators:
preprocess_plot()
. The goal of this is to add support to the keyword argumentsfigure
andaxis
. If you decorate a function withpreprocess_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 withpreprocess_plot_grid()
automatically gain support forHierarchicalGridData
andUniformGridData
, so they only need to worry about plotting NumPy arrays. Functions have to take a positional argumentdata
and a keyword argumentcoordinates
.
Grid data:
plot_color()
to plot directly some data with its value.plot_contourf()
to draw a filled contour plot using the data.
Horizons:
plot_horizon()
to plot a given shape in 2D.plot_horizon_on_plane_at_iteration()
to plot a given horizonat a given iteration in 2D.
plot_horizon_on_plane_at_time()
to plot a given horizonat 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 inargs
.
- 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, - AUniformGridData
, - AHierarchicalGridData
, - ABaseOneGridFunction
.Depending on what you pass, you might need additional arguments.
If you pass a
BaseOneGridFunction
, you need also to passiteration
, andshape
. If you passHierarchicalGridData
, you also need to passshape
. In all cases you can also passx0
andx1
to define origin and corner of the grid. You can pass the optionresample=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, passingcoordinates
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, - AUniformGridData
, - AHierarchicalGridData
, - ABaseOneGridFunction
.Depending on what you pass, you might need additional arguments.
If you pass a
BaseOneGridFunction
, you need also to passiteration
, andshape
. If you passHierarchicalGridData
, you also need to passshape
. In all cases you can also passx0
andx1
to define origin and corner of the grid. You can pass the optionresample=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 thecoordinates
.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, - AUniformGridData
, - AHierarchicalGridData
, - ABaseOneGridFunction
.Depending on what you pass, you might need additional arguments.
If you pass a
BaseOneGridFunction
, you need also to passiteration
, andshape
. If you passHierarchicalGridData
, you also need to passshape
. In all cases you can also passx0
andx1
to define origin and corner of the grid. You can pass the optionresample=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 thecoordinates
.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.
It handles the axis keyword setting it to plt.gca() if it was not provided.
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.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 thecoordinates.
- 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.
- ‘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
updatesmatplotlib.rcParams
).If
rc_par_file
is provided, first set the parameters reading the values from therc_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