angular_average_nd

powerbox.tools.angular_average_nd(field, coords, bins, n=None, weights=1, average=True, bin_ave=True, get_variance=False, log_bins=False)

Average the first n dimensions of a given field within radial bins.

This function be used to take “hyper-cylindrical” averages of fields. For a 3D field, with n=2, this is exactly a cylindrical average. This function can be used in fields of arbitrary dimension (memory permitting), and the field need not be centred at the origin. The averaging assumes that the grid cells fall completely into the bin which encompasses the co-ordinate point for the cell (i.e. there is no weighted splitting of cells if they intersect a bin edge).

It is optimized for applying a set of weights, and obtaining the variance of the mean, at the same time as averaging.

Parameters:

field : md-array

An array of arbitrary dimension specifying the field to be angularly averaged.

coords : list of n arrays

A list of 1D arrays specifying the co-ordinates in each dimension to be average.

bins : int or array.

Specifies the radial bins for the averaged dimensions. Can be an int or array specifying radial bin edges.

n : int, optional

The number of dimensions to be averaged. By default, all dimensions are averaged. Always uses the first n dimensions.

weights : array, optional

An array of the same shape as the first n dimensions of field, giving a weight for each entry.

average : bool, optional

Whether to take the (weighted) average. If False, returns the (unweighted) sum.

bin_ave : bool, optional

Whether to return the bin co-ordinates as the (weighted) average of cells within the bin (if True), or the linearly spaced edges of the bins

get_variance : bool, optional

Whether to also return an estimate of the variance of the power in each bin.

log_bins : bool, optional

Whether to create bins in log-space.

Returns:

field : (m-n+1)-array

The angularly-averaged field. The first dimension corresponds to bins, while the rest correspond to the unaveraged dimensions.

bins : 1D-array

The radial co-ordinates of the bins. Either the mean co-ordinate from the input data, or the regularly spaced bins, dependent on bin_ave.

var : (m-n+1)-array, optional

The variance of the averaged field (same shape as field), estimated from the mean standard error. Only returned if get_variance is True.

Examples

Create a 3D radial function, and average over radial bins. Equivalent to calling angular_average():

>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> x = np.linspace(-5,5,128)   # Setup a grid
>>> X,Y,Z = np.meshgrid(x,x,x)  # ""
>>> r = np.sqrt(X**2+Y**2+Z**2) # Get the radial co-ordinate of grid
>>> field = np.exp(-r**2)       # Generate a radial field
>>> avgfunc, bins, _ = angular_average_nd(field,[x,x,x],bins=100)   # Call angular_average
>>> plt.plot(bins, np.exp(-bins**2), label="Input Function")   # Plot input function versus ang. avg.
>>> plt.plot(bins, avgfunc, label="Averaged Function")

Create a 2D radial function, extended to 3D, and average over first 2 dimensions (cylindrical average):

>>> r = np.sqrt(X**2+Y**2)
>>> field = np.exp(-r**2)    # 2D field
>>> field = np.repeat(field,len(x)).reshape((len(x),)*3)   # Extended to 3D
>>> avgfunc, avbins, coords = angular_average_nd(field, [x,x,x], bins=50, n=2)
>>> plt.plot(avbins, np.exp(-avbins**2), label="Input Function")
>>> plt.plot(avbins, avgfunc[:,0], label="Averaged Function")