powerbox.tools.angular_average

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

Perform a radial histogram – averaging within radial bins – of a field.

Parameters:

field : array

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

coords : array

The magnitude of the co-ordinates at each point of field. Must be the same size as field.

bins : float or array.

The bins argument provided to histogram. Can be an int or array specifying 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 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.

Returns:

field_1d : array

The field averaged angularly (finally 1D)

binavg : array

The mean co-ordinate in each radial bin.

var : array

The variance of the averaged field, estimated from the mean standard error. Only returned if get_variance is True.

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 estimated 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")