pyValEIA.eia.detection

Functions to detect the EIA.

Functions

`eia_complete`(lat, density, den_type[, filt, ...])	Detect and classify EIAs in plasma density data.
`process_zlats`(z_lat, lat, den[, lat_base])	Detect valid latitude locations.
`evaluate_eia_gradient`(lat, grad_dat[, edge_lat])	Evaluate the density gradient for intersections revealing the EIA state.
`flat_rules`(p1, tec, lat[, zero_slope])	Determine if a peak is actually flat along with direciton.
`third_peak`(z_lat, tec, lat[, ghosts])	Identify a third peak, if present.
`peak_span`(pm, tec, lat[, trough_tec, trough_lat, div])	Calculate the latitudinal span of the peak.
`toomanymax`(z_lat, lat, tec[, max_lat])	Reduce the number of peaks.
`getzlopes`(z_lat_ends, lat, tec)	Calculate slopes between zero points.
`find_maxima`(zlope, ztec, ilocz)	Find the local maxima based on the slopes.
`find_second_maxima`(zlope, zdens, ilocz)	Find the secondary maxima.
`zero_max`(lat, dens, zlats[, maxes])	Identify potential peaks using the maxima.

Module Contents

pyValEIA.eia.detection.eia_complete(lat, density, den_type, filt='', interpolate=1, barrel_envelope=False, envelope_lower=0.6, envelope_upper=0.2, barrel_radius=3, window_lat=3)[source]

Detect and classify EIAs in plasma density data.

Parameters:

latarray-like: Magnetic latitude in degrees
densityarray-like: Plasma density data, e.g., TEC, electron density, or ion density
den_typestr: String specifying ‘tec’ if density is TEC or ‘ne’ for ion or electron density
filtstr: Filter method(s) for density. An empty string means no filtering, and and underscore combines two methods in the order they are specified. Valid methods include ‘barrel’, ‘median’, ‘mean’, and ‘average’ (default=’’)
interpolateint: Interpolate data to a higher resolution; the integer determines the number of data points in the interpolated output (e.g., len(density) * `interpolate), so a value of one or less means there will not be any interpolation (default=1)
barrel_envelopebool kwarg: if True, barrel roll will include points inside an envelope, if false (default) no envelope will be used
envelope_lowerdouble kwarg: lower limit of envelope default 0.6 (6%) of min value from contact points
envelope_upperdouble kwarg: upper limit of envelope default 0.2 (2%) of max value from contact points
barrel_radiusdouble kwarg: latitudinal radius of barrel
window_latdouble kwarg: latitudinal width of moving window (default: 3 degrees maglat)

Returns:

lat_usearray-like: latitudes either original lat returned or interpolated lat depending on interpolate
den_filt2array-like: filtered density
eia_type_slopestr: EIA type see eia_slope_state for types
z_latarray-like: zero latitudes found for checking purposes
platsarrray-like: latitudes of peaks found from eia_slope_state
p3latsarray-like: Additional peak latitudes, if additional peak(s) are between the EIA double peaks and the type is not ghost; these are likely artifacts

Raises:

ValueError: If inputs do not allow for EIA detection.

pyValEIA.eia.detection.process_zlats(z_lat, lat, den, lat_base=3)[source]

Detect valid latitude locations.

Parameters:

z_latarray-like: Latitudes where the density gradient is zero
latarray-like: All latitudes for the density measurments
denarray-like: Plasma denisty measurements
lat_baseint: Number of degrees latitude to round to when filtering (default=3)
Returns
——
z_latarray-like: Quality checked array of zero-density gradient latitudes

pyValEIA.eia.detection.evaluate_eia_gradient(lat, grad_dat, edge_lat=5)[source]

Evaluate the density gradient for intersections revealing the EIA state.

Parameters:

latarray-like: Apex latitude in degrees
grad_datarray-like: Plasma density gradient data in density units
edge_latdouble: Latitude from edge to exclude (default=5)

Returns:

zero_latarray-like: Locations of EIA peaks and troughs in degrees latitude

Raises:

ValueError: If lat and grad_dat have different shapes

pyValEIA.eia.detection.flat_rules(p1, tec, lat, zero_slope=0.5)[source]

Determine if a peak is actually flat along with direciton.

Parameters:

p1array-like of length 1: index of maxima
latarray-like: latitude
tecarray-like: tec or ne
zero_slopefloat: Threshold for the zero-slope value (default=0.5)

Returns:

flatint: 1 is flat_north, -1 is flat south, 0 is not flat 2 if trough

pyValEIA.eia.detection.third_peak(z_lat, tec, lat, ghosts=False)[source]

Identify a third peak, if present.

Parameters:

z_latint: single index of first maxima
latarray-like: latitude
tecarray-like: tec or ne
ghostsbool: if False, don’t look for ghosts, if True look for ghosts (default=False)

Returns:

p_thirdlist-like: List of latitudes if 3 peaks are found

pyValEIA.eia.detection.peak_span(pm, tec, lat, trough_tec=-99, trough_lat=-99, div=0.5)[source]

Calculate the latitudinal span of the peak.

Parameters:

pmint: peak index
tec: array-like: tec or ne
lat: array-like: latitude
trough_tecint or float: TEC at trough, minimum TEC for double or triple peaks, or unspecified if set to -99 (default=-99)
trough_latint or float: Latitude of trough if trough_tec is also supplied (default=-99)
divfloat: Decimal between 0 and 1 indicating desired peak width location; e.g., 0.5 indicates the half-width (default=0.5)

Returns:

north_pointfloat: northern latitude of peak width
south_pointfloat: southern latitude of peak width

pyValEIA.eia.detection.toomanymax(z_lat, lat, tec, max_lat=None)[source]

Reduce the number of peaks.

Parameters:

z_latarray-like: array of latitudes at zero gradient points
latarray-like: array of latitudes in degrees
tecarray-like: Totel electron content or plasma density
max_latarray-like or NoneType: if a peak is already found, it can be input to guarantee it is in the array new array (default=None)

Returns:

z_latarray-like: a new array of latitudes zero points
z_lat_newlist-like: A list that will contain a maximum of 5 values: south edge, closest south, equator max, closest north, and north edge.

pyValEIA.eia.detection.getzlopes(z_lat_ends, lat, tec)[source]

Calculate slopes between zero points.

Parameters:

z_lat_endsarray-like: gradient zero latitudes including end points
latarray-like: latitude
tecarray-like: tec

Returns:

zlopelist-like: slope between zero points length is lengeth of z_lat_ends-1
zteclist-like: closest tec of z_lat_ends
zlatlist-like: closest latitude of z_lat_ends

Notes

This function returns the slopes, latitudes, and TEC or density nearest to the z points.

pyValEIA.eia.detection.find_maxima(zlope, ztec, ilocz)[source]

Find the local maxima based on the slopes.

Parameters:

zlopearray-like: slopes outputted from getzlopes
ztecarray-like: tec of zero locations
ilocz: array-like: indices of zero locations

Returns:

zmaximalist-like: Maximum TEC
zmaxi: list-like: Indices of maximum TEC
zminimalist-like: Minimum TEC
zminilist-like: Indices of minimum TEC

pyValEIA.eia.detection.find_second_maxima(zlope, zdens, ilocz)[source]

Find the secondary maxima.

Parameters:

zlopearray-like: Slopes outputted from getzlopes
zdensarray-like: tec of zero locations
ilocz: array-like: indices of zero locations

Returns:

sec_maxarray-like: secondary maxima tec
sec_maxiarray-like: indices of secondary maxima

pyValEIA.eia.detection.zero_max(lat, dens, zlats, maxes=None)[source]

Identify potential peaks using the maxima.

Parameters:

latarray-like: Magnetic latitudes in degrees
densarray-like: Plasma density as TEC, electron density, or ion density
zlatsarray-like: Latitudes of potential peaks
maxeslist-like or NoneType: Indices of identified peaks or None (default=None)

Returns:

p1int or NoneType: Index of the first peak, or None if not found
p2int or NoneType: Index of the second peak, or None if not found