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, 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".

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
lognorm	bool	Whether to display the image in a log color scale.	False
ax	Axes	The axis to plot the image in. This will default to plt if none is explicitly passed.	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

Fitting functions

extra.utils.fit_gaussian

fit_gaussian(ydata, xdata=None, p0=None, norm=False, A_sign=0, **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 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.	required
xdata	array_like	Optional x-values corresponding to ydata.	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
**kwargs		All other keyword arguments will be passed to curve_fit().	{}