Defining Bins and Binning Data

esabin.esagrid

The esagrid module defines two types of binning scheme.

1. Equal-solid-angle bins (Esagrid)

2. Constant longitude bins (ConstantAzimuthalSpacingGrid)

EsagridBin(grid, flatind)	Class which abstractly represents one bin in a grid
ConstantLatitudeSpacingGrid(delta_lat, azi_coord)	Base class for constant latitude width bin grids
ConstantAzimuthalSpacingGrid(delta_lat, ...)	Constant longitude / local time bins class
Esagrid(delta_lat[, n_cap_bins, azi_coord])	Equal solid angle bins class

class esabin.esagrid.EsagridBin(grid, flatind)

Class which abstractly represents one bin in a grid

Parameters

• grid (esabin.esagrid.ConstantLatitudeSpacingGrid) – Object representing the particular grid used

• flatind (int) – The index (number) uniquely identifying this bin

class esabin.esagrid.ConstantLatitudeSpacingGrid(delta_lat, azi_coord)

Base class for constant latitude width bin grids

bin_locations(center_or_edges='edges')

Output the location of each bin

Parameters

center_or_edges ({'center','edges'}, optional) –

Returns

• binlats (np.ndarray) – [left_lat_edges,right_lat_edge] or center latitude of bin

• binlonorlt (np.ndarray) – [lower_longitude_lt_edge,upper_longitude_lt_edge] or center longitude or lt of bin

bin_stats(lat, lonorlt, data, statfun=<function mean>, center_or_edges='edges')

Divide data by bin and evaluate some function on each bin’s data

Parameters

• lat (np.ndarray) – Latitudes for each datapoint

• lonorlt (np.ndarray) – Longitudes or Local Times for each data point

• data (np.ndarray) – Values of each data point

• statfun (callable, optional) – Function evaluated on each bin’s data. Must take an array and return a scalar (default: numpy.nanmean)

• center_or_edges ({'center','edges'}, optional) – Return bin positions as bin centers (shape=(n,2)) or bin edges (shape=(n,))

Returns

• binlats (np.ndarray) – Latitudes of each bin

• binlonorlts (np.ndarray) – Longitudes or local times of each bin

• binstats (np.ndarray) – Result of evaluating statfun on data falling in each bin

binarea(bindims, r_km=6481.2)

Return bin surface area in km, assuming that the bin is a spherical rectangle on a sphere of radius r_km kilometers

Parameters

• bindims (list) – [lat_start,lat_end,lonorlt_start,lonorlt_end]

• r_km (float, optional) – The radius of the sphere, in kilometers, defaults to Re+110km, i.e. the hieght of the ionosphere

Returns

A – The surface area of the patch in km**2

Return type

float

abstract lonbins(lat_start, lat_end)

Subclasses must define this method, which returns the edges of the longitude bins which define a particular latitude band

whichbin(lat, lonorlt)

Find which bin each (lat,lon/localtime) location is in

Parameters

• lat (np.ndarray, shape=(n,)) – Array of ‘n’ latitudes

• lonorlt (np.ndarray, shape=(n,)) – Array of ‘n’ azimuthal coordinates (longitudes or localtimes)

Returns

• latbands (np.ndarray, dtype=int, shape=(n,)) – Array of index of the latitude band of each location

• lonbins (np.ndarray, dtype=int, shape=(n,)) – Array of index of longitude bin within the latitude band

• flat_inds (np.ndarray, dtype=int, shape=(n,)) – Array of index of bin (flat index)

class esabin.esagrid.ConstantAzimuthalSpacingGrid(delta_lat, delta_azi, azi_coord='lt')

Constant longitude / local time bins class

Parameters

• delta_lat (float) – The latitudinal width of the bins to be produced

• delta_azi (float) – The width of each azimuthal bins in degrees if azi_coord is lon, or hours if azi_coord is lt

• azi_coord ({'lon','lt'}, optional) – Which type of zonal/azimuthal/longitudinal coordinate to use. Defaults to ‘lt’

lonbins(lat_start, lat_end)

Return a constant number of longitude bins (defined by self.delta_azi) for any latitude

class esabin.esagrid.Esagrid(delta_lat, n_cap_bins=3, azi_coord='lt')

Equal solid angle bins class

Parameters

• delta_lat (float) – The latitudinal width of the bins to be produced

• n_cap_bins (int, optional) – The number of bins touching the northern pole, (or southern since symmetric)/ the minimum number of bins in a latitude band default is 3

• azi_coord ({'lon','lt'}, optional) – Which type of zonal/azimuthal/longitudinal coordinate to use. Defaults to ‘lt’

lonbins(lat_start, lat_end)

Finds the longitudinal boundaries of the bins which have latitude boundaries lat_start and lat_end, in units of radians. The number of bins per latitude band is determined by scaling the number of bins touching the northern pole (n_cap_bins), i.e. the smallest possible number of bins in a latitude band. The scaling factor is derived by staring from the differential form of the solid angle:

d(solid_angle) = sin(colat)d(colat)d(longitude)

Then performing the integration around all longitudes and from colat_1 to colat_2, to get the total solid angle of a band from colat_1 to colat_2.

Then a ratio is formed between the solid angle of an arbitrary band and the solid angle encompassed by the cap, i.e. the band between 0 colat and abs(colat_2-colat_1):

2*pi/N_min*(1-cos(colat_2-colat_1))=2*pi/N_(1,2)*(cos(colat_2)-cos(colat_1))

Finally, N_(1,2), the number of bins between colats 1 and 2 is solved for, as a function of N_min, the number of bins in the cap band.

Of course, this formula is not guaranteed to produce an integer, so the result is rounded, producing close to, but not exactly, equal solid angle bins. Larger values of n_cap_bins produce more nearly exactly the same solid angle per bin.