Utilities

This module holds bits of code that are quite generic and don't fit anywhere else.

Mathematical functions

extra.utils.gaussian

gaussian(x, y0, A, μ, σ, norm=True)

Gaussian profile.

If norm=True the profile is normalized in the sense that:

\[ \int_{-\infty}^{\infty} gaussian(x, 0, A, \mu, \sigma > 0) \; dx = A \]

Parameters:

Name	Type	Description	Default
x	(array_like, float)	Function argument	required
y0	float	Vertical offset	required
A	float	Amplitude	required
μ	float	Expected value	required
σ	float	Standard deviation	required
norm	bool	Whether to normalize the Gaussian	True

Returns:

Type	Description
array_like	Function value(s)

extra.utils.gaussian2d

gaussian2d(x, y, z0, A, μ_x, μ_y, σ_x, σ_y)

Normalized 2D Gaussian profile.

The profile is normalized in the sense that

\[ \iint_{-\infty}^{\infty} gaussian2d(x, y, 0, A, \mu_x, \mu_y, \sigma_x > 0, \sigma_y > 0) \; dx \; dy = A \]

Parameters:

Name	Type	Description	Default
x	(array_like, float)	Function arguments	required
y	(array_like, float)	Function arguments	required
z0	float	Vertical offset	required
μ_x	float	Expected x value	required
μ_y	float	Expected y value	required
σ_x	float	Standard deviation for x	required
σ_y	float	Standard deviation for y	required

Returns:

Type	Description
array_like	Function value(s)

extra.utils.lorentzian

lorentzian(x, y0, A, x0, γ)

Normalized Lorentzian profile.

The profile is normalized in the sense that:

\[ \int_{-\infty}^{\infty} lorentzian(x, 0, A, x0 \in \mathbb{R}, y > 0) \; dx = A \]

Parameters:

Name	Type	Description	Default
x	(array_like, float)	Function argument	required
y0	float	Vertical offset	required
A	float	Amplitude	required
x0	float	Location parameter	required
γ	float	Scale parameter	required

Returns:

Type	Description
array_like	Function value

Array functions

extra.utils.find_nearest_index

find_nearest_index(array, value: Any) -> np.int64

Find array index for the nearest value.

Parameters:

Name	Type	Description	Default
array	array_like	Array to search.	required
value	Any	Value to search.	required

Returns:

Type	Description
int64	Index of the nearest array value.

extra.utils.find_nearest_value

find_nearest_value(array, value: Any) -> Any

Find the nearest array value.

Parameters:

Name	Type	Description	Default
array	array_like	Array to search.	required
value	Any	Value to search.	required

Returns:

Type	Description
Any	Nearest array value.

extra.utils.reorder_axes_to_shape

reorder_axes_to_shape(a, target_shape)

Transpose an array to match the axis order specified by a shape tuple.

All dimensions must have different sizes. One axis in target_shape may be None, a wildcard for the remainining axis in the array shape.

Plotting functions

extra.utils.imshow2

imshow2(image, *args, colorbar=True, lognorm=False, ax=None, **kwargs)

Display an image with reasonable defaults.

This function wraps plt.imshow() to automatically set some defaults:

• Try to set vmin/vmax to reasonable values. Note that setting vmin/vmax is incompatible with the norm argument, so they will only be set if norm is not passed.
• Use an auto aspect ratio if the images aspect ratio is too skewed (useful for displaying heatmaps).
• Set interpolation="none".
• Draw a colorbar.

All arguments other than the ones listed below are passed to plt.imshow(), and explicitly passing any of vmin/vmax/aspect/interpolation will override the defaults.

Parameters:

Name	Type	Description	Default
image	array_like	The image to display.	required
colorbar	bool	Whether to draw a colorbar.	True
lognorm	bool	Whether to display the image in a log color scale.	False
ax	Axes	The axis to plot the image in.	None

extra.utils.hyperslicer2

hyperslicer2(arr, *args, ax=None, lognorm=False, colorbar=True, **kwargs)

Interactively visualize arrays of images.

This is a lightweight wrapper around hyperslicer() with some useful defaults:

• Try to set vmin/vmax to reasonable values. Note that setting vmin/vmax is incompatible with the norm argument, so they will only be set if norm is not passed.
• Set interpolation="none".
• Enable the play buttons.
• Draw a colorbar.

Example usage:

plt.figure()
# Note the trailing semi-colon to swallow the return value. hyperslicer2()
# returns a `controls` object by default that displays the play buttons, so
# returning it from a notebook cell will end up displaying the play buttons
# twice.
hyperslicer2(images);

All arguments other than the ones listed below are passed to hyperslicer(), and explicitly passing any of vmin/vmax/interpolation/play_buttons will override the defaults.

Parameters:

Name	Type	Description	Default
arr	array_like	The array of images to display. Should have at least three dimensions.	required
ax	Axes	The axis to plot the image in.	None
lognorm	bool	Whether to display the images in a log color scale.	False
colorbar	bool	Whether to display a colorbar.	True

extra.utils.ridgeplot

ridgeplot(data, *, fig=None, overlap=0.5, xlabel=None, ylabel='Per-line values', ylim=None, yline=None, stack_label=None, stack_ticklabels=None)

Make a ridgeline plot showing a sequence of similar lines

A ridgeline plot spreads out the different lines vertically to make their order clear, but allowing them to overlap. It's an alternative to a heatmap, especially if there are relatively few rows (around 5-20).

Parameters:

Name	Type	Description	Default
data	array_like	A 2D array, each row of which will be plotted as one line, starting at the top of the plot. Pass an xarray DataArray to use its labels by default.	required
fig	Figure	Plot into an existing matplotlib figure.	None
overlap	float	Number from 0 (no overlap) to 1, the fraction of each plot's area covered by the next plot.	0.5
xlabel	str	Label for the shared x axis.	None
ylabel	str	Label for the y axis (drawn on the bottom plot).	'Per-line values'
ylim	tuple	Lower & upper limits for the y axis of each line.	None
yline	float	Y value at which to draw a horizontal marker for each line.	None
stack_label	str	Label for the stacking axis (shown on the right)	None
stack_ticklabels	array_like	Labels for each line (shown on the right next to the zero line of each plot).	None

Fitting functions

extra.utils.fit_gaussian

fit_gaussian(ydata, xdata=None, p0=None, norm=False, A_sign=0, nans_on_failure=False, **kwargs)

Fit a Gaussian to some data.

This uses curve_fit() to fit a Gaussian (from gaussian()) to ydata. If p0 is not passed the function will set them to reasonable defaults. It will return None (or an array of NaNs if nans_on_failure=True) if fitting fails, or if there are no finite values in ydata.

Note

By default this will only return the popt array from curve_fit(), if you want pcov or any other output you must pass full_output=True.

Note

When visualizing the fit results with gaussian() make sure the norm parameters match. i.e. if you're using the default of fitting an unnormalized Gaussian: gaussian(xdata, *popt, norm=False).

Parameters:

Name	Type	Description	Default
ydata	array_like	The data to fit. NaN's and infs will automatically be masked before fitting. If a DataArray is passed the underlying numpy array will be used.	required
xdata	array_like	Optional x-values corresponding to ydata. If a DataArray is passed the underlying numpy array will be used.	None
p0	list	A list of [y0, A, μ, σ] to match the arguments to gaussian().	None
norm	bool	Whether to fit a normalized or unnormalized Gaussian.	False
A_sign	int	Sign of the amplitude (A) parameter for the Gaussian. 1 for an upwards peak, -1 for downwards. 0 (default) allows either, using a faster algorithm. Passing bounds= overrides this.	0
nans_on_failure	bool	If True the function will return an array of NaNs of the same length as p0. This is useful when e.g. fitting in a loop and saving the output.	False
**kwargs		All other keyword arguments will be passed to curve_fit().	{}