angular_average

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

Average a given field within radial bins.

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: nd-array

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

coords: nd-array or list of n arrays.

Either the magnitude of the co-ordinates at each point of field, or a list of 1D arrays specifying the co-ordinates in each dimension.

bins: float or array.

The bins argument provided to histogram. Can be an int or array specifying radial bin edges.

weights: array, optional

An array of the same shape as 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 regularly 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_1d : 1D-array

The angularly-averaged field.

bins : 1D-array

Array of same shape as field_1d specifying 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 : 1D-array, optional

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

See also

angular_average_nd

Perform an angular average in a subset of the total dimensions.

Notes

If desired, the variance is calculated as the weight unbiased variance, using the formula at https://en.wikipedia.org/wiki/Weighted_arithmetic_mean#Reliability_weights for the variance in each cell, and normalising by a factor of \(V_2/V_1^2\) to estimate the variance of the average.

Examples

Create a 3D radial function, and average over radial bins:

>>> 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(field,r,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")