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, μ, σ)

Normalized Gaussian profile.

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

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.

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

Fitting functions

extra.utils.fit_gaussian

fit_gaussian(ydata, xdata=None, p0=None, **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.

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
**kwargs		All other keyword arguments will be passed to curve_fit().	{}