erlab.accessors.general

Defines miscellaneous accessors for general data manipulation and visualization.

Classes

InfoDataArrayAccessor(xarray_obj)

xarray.DataArray.qinfo accessor for displaying information about the data.

InteractiveDataArrayAccessor(xarray_obj)

xarray.DataArray.qshow accessor for interactive visualization.

InteractiveDatasetAccessor(xarray_obj)

xarray.Dataset.qshow accessor for interactive visualization.

PlotAccessor(xarray_obj)

xarray.DataArray.qplot accessor for plotting data.

SelectionAccessor(xarray_obj)

xarray.DataArray.qsel accessor for convenient selection and aggregation.
class erlab.accessors.general.InfoDataArrayAccessor(xarray_obj)[source]

Bases: ERLabDataArrayAccessor

xarray.DataArray.qinfo accessor for displaying information about the data.

get_value(attr_or_coord_name)[source]

Get the value of the specified attribute or coordinate.

If the attribute or coordinate is not found, None is returned.

Parameters:

attr_or_coord_name (str) – The name of the attribute or coordinate.

class erlab.accessors.general.InteractiveDataArrayAccessor(xarray_obj)[source]

Bases: ERLabDataArrayAccessor

xarray.DataArray.qshow accessor for interactive visualization.

__call__(*args, **kwargs)[source]

Visualize the data interactively.

Data with two to four dimensions is opened with erlab.interactive.imagetool.itool(). Other dimensionalities are passed to DataArray.hvplot and require hvplot.

Parameters:

  • *args – Positional arguments passed onto the interactive visualization function.

  • **kwargs – Keyword arguments passed onto the interactive visualization function.

Returns:

object – The return value from erlab.interactive.imagetool.itool() or DataArray.hvplot, depending on the number of dimensions.

itool(*args, **kwargs)[source]

Shortcut for erlab.interactive.imagetool.itool().

Parameters:

  • *args – Positional arguments passed onto itool.

  • **kwargs – Keyword arguments passed onto itool.

hvplot(*args, **kwargs)[source]

hvplot-based interactive visualization.

This method is a convenience wrapper that handles importing hvplot.

Parameters:

  • *args – Positional arguments passed onto DataArray.hvplot.

  • **kwargs – Keyword arguments passed onto DataArray.hvplot.

Raises:

ImportError –

If hvplot is not installed.

class erlab.accessors.general.InteractiveDatasetAccessor(xarray_obj)[source]

Bases: ERLabDatasetAccessor

xarray.Dataset.qshow accessor for interactive visualization.

__call__(*args, **kwargs)[source]

Visualize the data interactively.

An xarray-lmfit result is passed to fit(). Other datasets are passed to itool().

Parameters:

  • *args – Positional arguments passed onto the interactive visualization function.

  • **kwargs – Keyword arguments passed onto the interactive visualization function.

Returns:

object – The return value from fit() or itool(), depending on the data variables in the dataset.

itool(*args, **kwargs)[source]

Shortcut for erlab.interactive.imagetool.itool().

Parameters:

  • *args – Positional arguments passed onto itool.

  • **kwargs – Keyword arguments passed onto itool.

hvplot(*args, **kwargs)[source]

hvplot-based interactive visualization.

This method is a convenience wrapper that handles importing hvplot.

Parameters:

  • *args – Positional arguments passed onto Dataset.hvplot.

  • **kwargs – Keyword arguments passed onto Dataset.hvplot.

Raises:

ImportError –

If hvplot is not installed.

fit(plot_components=False, data_var=None)[source]

Interactive visualization of fit results.

Parameters:

  • plot_components (bool, default: False) – If True, plot the components of the fit. Default is False. Requires the Dataset to have a modelfit_results variable.

  • data_var (str | None, default: None) – The name of the data variable to visualize. Required only if the Dataset contains fits across multiple data variables.

Returns:

panel.layout.Column – A panel containing the interactive visualization.

params(data_var=None)[source]

Plot the coefficients and standard errors for each fitting parameter.

Parameters:

data_var (str | None, default: None) – The name of the data variable to visualize. Required only if the Dataset contains fits across multiple data variables.

class erlab.accessors.general.PlotAccessor(xarray_obj)[source]

Bases: ERLabDataArrayAccessor

xarray.DataArray.qplot accessor for plotting data.

__call__(*args, **kwargs)[source]

Plot the data.

Plots two-dimensional data using plot_array. For non-two-dimensional data, the method falls back to xarray.DataArray.plot(). Positional and keyword arguments are passed to the selected plotting function.

Parameters:

  • *args – Positional arguments to be passed to the plotting function.

  • **kwargs – Keyword arguments to be passed to the plotting function.

Returns:

matplotlib artist or sequence of artists – For two-dimensional data, the image artist returned by erlab.plotting.plot_array(). For other dimensionalities, the return value from xarray.DataArray.plot().

Notes

Axis labels are formatted with erlab.plotting.fancy_labels() after the data is plotted.

class erlab.accessors.general.SelectionAccessor(xarray_obj)[source]

Bases: ERLabDataArrayAccessor

xarray.DataArray.qsel accessor for convenient selection and aggregation.

__call__(indexers=None, *, func='mean', **indexers_kwargs)[source]

Select and aggregate data along specified dimensions.

Parameters:

  • indexers (Mapping[Hashable, float | Collection[float] | slice] | None, default: None) –

    Dictionary specifying the dimensions and their values or slices. Position along a dimension can be specified in three ways:

    • As a scalar value or a collection of scalar values: alpha=-1.2 or alpha=[-1.2, 0.0, 1.2]:

      If no width is specified, the data is selected along the nearest value for each element. It is equivalent to calling xarray.DataArray.sel() with method='nearest'. When a collection is provided, multiple selections are made and concatenated along the dimension. In this case, the width may also be provided as a collection with the same length.

    • As a value and width: alpha=5, alpha_width=0.5

      The data is aggregated over a slice of width alpha_width, centered at alpha. The center and width use the units of the selected coordinate. Label-based slice endpoints are inclusive. If alpha is a collection, the data is aggregated over multiple slices and concatenated along the dimension.

    • As a slice: alpha=slice(-10, 10)

      The data is selected over the specified slice. No averaging is performed. This is equivalent to calling xarray.DataArray.sel() with a slice.

    One of indexers or indexers_kwargs must be provided.

  • **indexers_kwargs – The keyword arguments form of indexers. One of indexers or indexers_kwargs must be provided.

  • func ({"mean", "min", "max", "sum"}, optional) – Function used when qsel aggregates over width-based selections. Must be one of "mean", "min", "max", or "sum". "mean" by default. This argument only affects reduced data; reduced numeric coordinates are still represented by their mean.

Returns:

DataArray – The selected or aggregated data. A scalar selection or one width-based aggregation removes the selected dimension. If the dimension has a coordinate, its selected or mean value is retained as a scalar coordinate. A collection of centers preserves the dimension with one coordinate value for each selection. Numeric coordinates that depend on an aggregated dimension are reduced with their mean. The data name and attributes are retained.

Return type:

DataArray

Note

Unlike xarray.DataArray.sel(), this method treats all dimensions without coordinates as equivalent to having coordinates assigned from 0 to n-1, where n is the size of the dimension. For example:

da = xr.DataArray(np.random.rand(10), dims=("x",))

da.sel(x=slice(2, 3))  # This works

da.sel(x=slice(2.0, 3.0))  # This raises a TypeError

da.qsel(x=slice(2.0, 3.0))  # This works
mean(dim=None)[source]

Return the mean over dimensions while keeping their coordinates.

Dimensions removed from the data are retained as scalar coordinates with the mean of their coordinate values. Numeric coordinates that depend on reduced dimensions are averaged as well.

Parameters:

dim (str | Sequence[Hashable] | None, default: None) – The dimension(s) along which to average the data. If None, all dimensions are averaged.

Returns:

DataArray – The data averaged along the specified dimension(s).

Return type:

DataArray

average(dim=None)[source]

Alias for qsel.mean.

New code should use qsel.mean.

min(dim=None)[source]

Return the minimum over dimensions while keeping their coordinates.

Data values are reduced with xarray.DataArray.min(). Dimensions removed from the data are retained as scalar coordinates with the mean of their coordinate values. Numeric coordinates that depend on reduced dimensions are averaged as well.

max(dim=None)[source]

Return the maximum over dimensions while keeping their coordinates.

Data values are reduced with xarray.DataArray.max(). Dimensions removed from the data are retained as scalar coordinates with the mean of their coordinate values. Numeric coordinates that depend on reduced dimensions are averaged as well.

sum(dim=None)[source]

Return the sum over dimensions while keeping their coordinates.

Data values are reduced with xarray.DataArray.sum(). Dimensions removed from the data are retained as scalar coordinates with the mean of their coordinate values. Numeric coordinates that depend on reduced dimensions are averaged as well.

around(radius, *, boundary=True, invert=False, drop=False, average=True, **sel_kw)[source]

Average data within a specified radius of a specified point.

For instance, consider an ARPES map with dimensions 'kx', 'ky', and 'eV'. Providing 'kx' and 'ky' points will average the data within a cylindrical region centered at that point. The radius of the cylinder is specified by radius.

If different radii are given for kx and ky, the region will be elliptic.

Parameters:

  • radius (float | dict[Hashable, float]) – The radius of the region. If a single number, the same radius is used for all dimensions. If a dictionary, keys must be valid dimension names and the values are the radii for the corresponding dimensions.

  • boundary (bool, default: True) – Whether to consider points on the boundary to be inside the mask. Default is True.

  • invert (bool, default: False) – If True, invert the mask so that points inside are masked and points outside are kept. This is applied after the mask is created.

  • drop (bool, default: False) – If True, drop coordinate labels along dims for which all values are masked. This argument is ignored if average=True.

  • average (bool, default: True) – If True, return the mean value of the data within the region. If False, return the masked data.

  • **sel_kw – The center of the spherical region. Must be a mapping of valid dimension names to coordinate values.

Returns:

DataArray – The mean value of the data within the region if average=True, else the masked data.

Return type:

DataArray

Note

Depending on the radius and dimensions provided, the mask will be hyperellipsoid in the dimensions specified in sel_kw.

See also

erlab.analysis.mask.mask_with_radius()