Hv#

class discretisedfield.plotting.Hv(key_dims, callback, vdim_guess_callback=None)#

Holoviews-based plotting methods.

Plots based on Holoviews can be created without prior slicing. Instead, a slider is created for the directions not shown in the plot. This class should not be accessed directly. Use field.hv to use the different plotting methods.

Data in the plots is filtered based on field.valid. Only cells where valid==True are visible in the plots.

Parameters:

key_dims (dict[df.plotting.util.hv_key_dim]) – Key dimensions of the plot (kdims and dynamic kdims [for which holoviews will create widgets]) in a dictionary. The keys are the names of the dimensions, values namedtuples containing the data and unit (can be an empty string) of the dimensions.
callback (callable) – Callback function to provide data. It must accept arbitrary keyword arguments and will be called with all dynamic kdims and their current values.
vdims_guess_callback (callable, optional) – Callback function to provide (guess) vdims for the __call__ method if no vdims are passed in. This method is required because the order of key_dims is not defined.

Methods

`__call__`	Create an optimal plot combining `hv.scalar` and `hv.vector`.
`__dir__`	Default dir() implementation.
`__eq__`	Return self==value.
`__repr__`	Return repr(self).
`contour`	Plot contour lines of scalar fields or vector components.
`scalar`	Create an image plot for scalar data or individual components.
`vector`	Create a vector plot.

__call__(kdims, vdims=None, roi=None, scalar_kw=None, vector_kw=None)#

Create an optimal plot combining hv.scalar and hv.vector.

This is a convenience method for quick plotting. It combines hv.scalar and: hv.vector. Depending on the dimensionality of the object, it automatically determines the type of plot in the following order:

For scalar objects (no dimension with name 'vdims') only discretisedfield.plotting.Hv.scalar is used. The parameter vdims is ignored.
When vdims is specified a vector plot (without coloring) is created for the “in-plane” part of the vector field (defined via vdims). If the field has vector dimensionality larger than two an additional scalar plot is created for all remaining vector components (with a drop-down selection).
If vdims is not specified the method tries to guess the correct vdims from the kdims by matching spatial coordinates and vector components based on the order they are defined in. This only works if both have the same number of elements, e.g. a 3d vector field in 3d space.
For all other vector fields a scalar plot with a drop-down selection for the individual vector components is created.

Based on the norm of the object (absolute values for scalar fields) automatic filtering is applied, i.e. all cells where the norm is zero are excluded from the plot. To manually filter out parts of the plot (e.g. areas where the norm of the field is zero) an additional roi can be passed. It can take an xarray.DataArray or a discretisedfield.Field and hides all points where roi is 0. It relies on xarray``s broadcasting and the object passed to ``roi must only have the same dimensions as the ones specified as kdims.

All default values of hv.scalar and hv.vector can be changed by passing dictionaries to scalar_kw and vector_kw, which are then used in subplots. To understand the meaning of the keyword arguments which can be passed to this method, please refer to discretisedfield.plotting.Hv.scalar and discretisedfield.plotting.Hv.vector documentation.

To reduce the number of points in the plot a simple re-sampling is available. The parameter n in scalar_kw or vector_kw can be used to specify the number of points in different directions. A tuple of length 2 can be used to specify the number of points in the two kdims. Note, that the re-sampling method is very basic and does not do any sort of interpolation (it just picks the nearest point). The extreme points in each direction are always kept. Equidistant points are picked in between.

Parameters:

kdims (List[str]) – Names of the two geometrical directions forming the plane to be used for plotting the data.
vdims (List[str], optional) – Names of the components to be used for plotting the arrows. This information is used to associate field components and spatial directions. Optionally, one of the list elements can be None if the field has no component in that direction.
roi (xarray.DataArray, discretisedfield.Field, optional) – Filter out certain areas in the plot. Only cells where the roi is non-zero are included in the output.
scalar_kw (dict) – Additional keyword arguments that are passed to discretisedfield.plotting.Hv.scalar
vector_kw (dict) – Additional keyword arguments that are passed to discretisedfield.plotting.Hv.vector

Returns:

A holoviews.DynamicMap that “creates” a combined plot for each slider value.

Return type:

holoviews.DynamicMap

Examples

Simple combined scalar and vector plot with hv.

>>> import discretisedfield as df
...
>>> p1 = (0, 0, 0)
>>> p2 = (100, 100, 100)
>>> n = (10, 10, 10)
>>> mesh = df.Mesh(p1=p1, p2=p2, n=n)
>>> field = df.Field(mesh, nvdim=1, value=2)
...
>>> field.hv(kdims=['x', 'y'])
:DynamicMap...

contour(kdims, roi=None, n=None, levels=10, **kwargs)#

Plot contour lines of scalar fields or vector components.

This method creates a dynamic holoviews plot (holoviews.DynamicMap) based on holoviews.Contours. The plot shows the plane defined with the two spatial directions passed to kdims. If a vector field is passed (that means the field dimension is greater than 1) an additional panel.Select widget for the field components is created automatically. It is not necessary to create a cut-plane first.

To filter out parts of the plot (e.g. areas where the norm of the field is zero) an additional roi can be passed. It can take an xarray.DataArray or a discretisedfield.Field and hides all points where roi is 0. It relies on xarray``s broadcasting and the object passed to ``roi must only have the same dimensions as the ones specified as kdims. No automatic filtering is applied.

To reduce the number of points in the plot a simple re-sampling is available. The parameter n can be used to specify the number of points in different directions. A tuple of length 2 can be used to specify the number of points in the two kdims. Note, that the re-sampling method is very basic and does not do any sort of interpolation (it just picks the nearest point). The extreme points in each direction are always kept. Equidistant points are picked in between.

Additional keyword arguments are directly forwarded to the .opts method of: the holoviews.DynamicMap. Please refer to the documentation of holoviews (in particular holoviews.Contours`) for available options and additional documentation on how to modify the plot after creation.

Parameters:

kdims (List[str]) – Names of the two geometrical directions forming the plane to be used for plotting the data.
roi (xarray.DataArray, discretisedfield.Field, optional) – Field to filter out certain areas in the plot. Only cells where the roi is non-zero are included in the output.
n (array_like(2), optional) – Re-sampling of the array with the given number of points. If an array-like is passed it must have length 2 and the values are used for the two kdims. If not specified no re-sampling is done.
levels (int, optional) – The number of contour lines, defaults to 10.
kwargs – Additional keyword arguments that are forwarded to .opts of the holoviews.DynamicMap object.

Returns:

A holoviews.DynamicMap that “creates” a holoviews.Contours object for each slider value.

Return type:

holoviews.DynamicMap

Raises:

ValueError – If kdims has not length 2 or contains strings that are not part of the geometrical directions of the field.

Examples

Simple contour-line plot with hv.

>>> import discretisedfield as df
...
>>> p1 = (0, 0, 0)
>>> p2 = (100, 100, 100)
>>> n = (10, 10, 10)
>>> mesh = df.Mesh(p1=p1, p2=p2, n=n)
>>> field = df.Field(mesh, nvdim=1, value=2)
...
>>> field.hv.contour(kdims=['y', 'z'])
:DynamicMap...

scalar(kdims, roi=None, n=None, **kwargs)#

Create an image plot for scalar data or individual components.

This method creates a dynamic holoviews plot (holoviews.DynamicMap) based on holoviews.Image objects. The plot shows the plane defined with the two spatial directions passed to kdims. If a vector field is passed (that means the field dimension ‘vdims’ is greater than 1) an additional panel.Select widget for the field components is created automatically. It is not necessary to create a cut-plane first.

Additional keyword arguments are directly forwarded to the .opts method of the resulting holoviews.Image. Please refer to the documentation of `holoviews (in particular holoviews.Image) for available options and additional documentation on how to modify the plot after creation.

Parameters:

kdims (List[str]) – Names of the two geometrical directions forming the plane to be used for plotting the data.
roi (xarray.DataArray, discretisedfield.Field, optional) – Field to filter out certain areas in the plot. Only cells where the roi is non-zero are included in the output.
n (array_like(2), optional) – Re-sampling of the array with the given number of points. If not specified no re-sampling is done.
kwargs – Additional keyword arguments that are forwarded to .opts of the holoviews.Image object.

Returns:

A holoviews.DynamicMap that “creates” a holoviews.Image for each slider value.

Return type:

holoviews.DynamicMap

Raises:

ValueError – If kdims does not have length 2 or contains strings that are not part of the geometrical directions of the field.

Examples

Simple scalar plot with hv.

>>> import discretisedfield as df
...
>>> p1 = (0, 0, 0)
>>> p2 = (100, 100, 100)
>>> n = (10, 10, 10)
>>> mesh = df.Mesh(p1=p1, p2=p2, n=n)
>>> field = df.Field(mesh, nvdim=1, value=2)
...
>>> field.hv.scalar(kdims=['x', 'z'])
:DynamicMap...

vector(kdims, vdims=None, cdim=None, roi=None, n=None, use_color=True, **kwargs)#

Create a vector plot.

This method creates a dynamic holoviews plot (holoviews.DynamicMap) based on holoviews.VectorField objects. The plot shows the plane defined with the two spatial directions passed to kdims. The length of the arrows corresponds to the norm of the in-plane component of the field. It is not necessary to create a cut-plane first.

vdims co-relates the vector directions with the geometrical direction defined with kdims. If not specified, kdims is used to guess the values.

For 3d vector fields the color by default encodes the out-of-plane component. Other fields cannot be colored automatically. To assign a non-uniform color manually use cdim. It either accepts a string to select one of the field vector components or a scalar discretisedfield.Field or xarray.DataArray. Coloring can be disabled with use_color=False.

To filter out parts of the plot (e.g. areas where the norm of the field is zero) an additional roi can be passed. It can take an xarray.DataArray or a discretisedfield.Field and hides all points where roi is zero. It relies on xarray``s broadcasting and the object passed to ``roi must only have the same dimensions as the ones specified as kdims. No automatic filtering is applied.

This method is based on holoviews.VectorPlot. Additional keyword arguments are directly forwarded to the .opts() method of the holoviews.Image object. Please refer to the documentation of holoviews (in particular holoviews.VectorField) for available options and additional documentation on how to modify the plot after creation.

Parameters:

kdims (List[str]) – Names of the two geometrical directions forming the plane to be used for plotting the data.
vdims (List[str], optional) – Names of the components to be used for plotting the arrows. This information is used to associate field components and spatial directions. Optionally, one of the list elements can be None if the field has no component in that direction. If vdims is not specified the method tries to guess the correct vdims from the kdims by matching spatial coordinates and vector components based on the order they are defined in. This only works if both have the same number of elements, e.g. a 3d vector field in 3d space.
cdim (str, xarray.DataArray, discretisedfield.Field, optional) – A string can be used to select one of the vector components of the field. To color according to different data scalar discretisedfield.Field or xarray.DataArray can be used to color the arrows. This option has no effect when use_color=False. If not passed the out-of-plane component is used for 3d vector fields. Otherwise, a warning is show and automatic coloring is disabled.
roi (xarray.DataArray, discretisedfield.Field, optional) – Field to filter out certain areas in the plot. Only cells where the roi is non-zero are included in the output.
n (array_like, optional) – Re-sampling of the array with the given number of points. If not specified no re-sampling is done.
use_color (bool, optional) – If True the field is colored according to the out-of-plane component. If False all arrows have a uniform color, by default black. To change the uniform color pass e.g.``color= ‘blue’. Defaults to ``True.
kwargs – Additional keyword arguments that are forwarded to holoviews.VectorField.opts().

Returns:

A holoviews.DynamicMap that “creates” a holoviews.VectorField for each slider value.

Return type:

holoviews.DynamicMap

Raises:

ValueError – If kdims does not have length 2 or contains strings that are not part of the geometrical directions of the field. If the object has no dimension vdims that defines the vector components.

Examples

Simple vector plot with hv.

>>> import discretisedfield as df
...
>>> p1 = (0, 0, 0)
>>> p2 = (100, 100, 100)
>>> n = (10, 10, 10)
>>> mesh = df.Mesh(p1=p1, p2=p2, n=n)
>>> field = df.Field(mesh, nvdim=3, value=(1, 2, 3))
...
>>> field.hv.vector(kdims=['x', 'y'], vdims=['x', 'y'])
:DynamicMap...