pyValEIA.eia.detection ====================== .. py:module:: pyValEIA.eia.detection .. autoapi-nested-parse:: Functions to detect the EIA. .. !! processed by numpydoc !! Functions --------- .. autoapisummary:: pyValEIA.eia.detection.eia_complete pyValEIA.eia.detection.process_zlats pyValEIA.eia.detection.evaluate_eia_gradient pyValEIA.eia.detection.flat_rules pyValEIA.eia.detection.third_peak pyValEIA.eia.detection.peak_span pyValEIA.eia.detection.toomanymax pyValEIA.eia.detection.getzlopes pyValEIA.eia.detection.find_maxima pyValEIA.eia.detection.find_second_maxima pyValEIA.eia.detection.zero_max Module Contents --------------- .. py:function:: 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) Detect and classify EIAs in plasma density data. :Parameters: **lat** : array-like Magnetic latitude in degrees **density** : array-like Plasma density data, e.g., TEC, electron density, or ion density **den_type** : str String specifying 'tec' if density is TEC or 'ne' for ion or electron density **filt** : str 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='') **interpolate** : int 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_envelope** : bool kwarg if True, barrel roll will include points inside an envelope, if false (default) no envelope will be used **envelope_lower** : double kwarg lower limit of envelope default 0.6 (6%) of min value from contact points **envelope_upper** : double kwarg upper limit of envelope default 0.2 (2%) of max value from contact points **barrel_radius** : double kwarg latitudinal radius of barrel **window_lat** : double kwarg latitudinal width of moving window (default: 3 degrees maglat) :Returns: **lat_use** : array-like latitudes either original lat returned or interpolated lat depending on interpolate **den_filt2** : array-like filtered density **eia_type_slope** : str EIA type see eia_slope_state for types **z_lat** : array-like zero latitudes found for checking purposes **plats** : arrray-like latitudes of peaks found from eia_slope_state **p3lats** : array-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. .. !! processed by numpydoc !! .. py:function:: process_zlats(z_lat, lat, den, lat_base=3) Detect valid latitude locations. :Parameters: **z_lat** : array-like Latitudes where the density gradient is zero **lat** : array-like All latitudes for the density measurments **den** : array-like Plasma denisty measurements **lat_base** : int Number of degrees latitude to round to when filtering (default=3) **Returns** .. **------** .. **z_lat** : array-like Quality checked array of zero-density gradient latitudes .. !! processed by numpydoc !! .. py:function:: evaluate_eia_gradient(lat, grad_dat, edge_lat=5) Evaluate the density gradient for intersections revealing the EIA state. :Parameters: **lat** : array-like Apex latitude in degrees **grad_dat** : array-like Plasma density gradient data in density units **edge_lat** : double Latitude from edge to exclude (default=5) :Returns: **zero_lat** : array-like Locations of EIA peaks and troughs in degrees latitude :Raises: ValueError If `lat` and `grad_dat` have different shapes .. !! processed by numpydoc !! .. py:function:: flat_rules(p1, tec, lat, zero_slope=0.5) Determine if a peak is actually flat along with direciton. :Parameters: **p1** : array-like of length 1 index of maxima **lat** : array-like latitude **tec** : array-like tec or ne **zero_slope** : float Threshold for the zero-slope value (default=0.5) :Returns: **flat** : int 1 is flat_north, -1 is flat south, 0 is not flat 2 if trough .. !! processed by numpydoc !! .. py:function:: third_peak(z_lat, tec, lat, ghosts=False) Identify a third peak, if present. :Parameters: **z_lat** : int single index of first maxima **lat** : array-like latitude **tec** : array-like tec or ne **ghosts** : bool if False, don't look for ghosts, if True look for ghosts (default=False) :Returns: **p_third** : list-like List of latitudes if 3 peaks are found .. !! processed by numpydoc !! .. py:function:: peak_span(pm, tec, lat, trough_tec=-99, trough_lat=-99, div=0.5) Calculate the latitudinal span of the peak. :Parameters: **pm** : int peak index **tec: array-like** tec or ne **lat: array-like** latitude **trough_tec** : int or float TEC at trough, minimum TEC for double or triple peaks, or unspecified if set to -99 (default=-99) **trough_lat** : int or float Latitude of trough if `trough_tec` is also supplied (default=-99) **div** : float Decimal between 0 and 1 indicating desired peak width location; e.g., 0.5 indicates the half-width (default=0.5) :Returns: **north_point** : float northern latitude of peak width **south_point** : float southern latitude of peak width .. !! processed by numpydoc !! .. py:function:: toomanymax(z_lat, lat, tec, max_lat=None) Reduce the number of peaks. :Parameters: **z_lat** : array-like array of latitudes at zero gradient points **lat** : array-like array of latitudes in degrees **tec** : array-like Totel electron content or plasma density **max_lat** : array-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_lat** : array-like a new array of latitudes zero points **z_lat_new** : list-like A list that will contain a maximum of 5 values: south edge, closest south, equator max, closest north, and north edge. .. !! processed by numpydoc !! .. py:function:: getzlopes(z_lat_ends, lat, tec) Calculate slopes between zero points. :Parameters: **z_lat_ends** : array-like gradient zero latitudes including end points **lat** : array-like latitude **tec** : array-like tec :Returns: **zlope** : list-like slope between zero points length is lengeth of z_lat_ends-1 **ztec** : list-like closest tec of z_lat_ends **zlat** : list-like closest latitude of z_lat_ends .. rubric:: Notes This function returns the slopes, latitudes, and TEC or density nearest to the z points. .. !! processed by numpydoc !! .. py:function:: find_maxima(zlope, ztec, ilocz) Find the local maxima based on the slopes. :Parameters: **zlope** : array-like slopes outputted from getzlopes **ztec** : array-like tec of zero locations **ilocz: array-like** indices of zero locations :Returns: **zmaxima** : list-like Maximum TEC zmaxi: list-like Indices of maximum TEC **zminima** : list-like Minimum TEC **zmini** : list-like Indices of minimum TEC .. !! processed by numpydoc !! .. py:function:: find_second_maxima(zlope, zdens, ilocz) Find the secondary maxima. :Parameters: **zlope** : array-like Slopes outputted from `getzlopes` **zdens** : array-like tec of zero locations **ilocz: array-like** indices of zero locations :Returns: **sec_max** : array-like secondary maxima tec **sec_maxi** : array-like indices of secondary maxima .. !! processed by numpydoc !! .. py:function:: zero_max(lat, dens, zlats, maxes=None) Identify potential peaks using the maxima. :Parameters: **lat** : array-like Magnetic latitudes in degrees **dens** : array-like Plasma density as TEC, electron density, or ion density **zlats** : array-like Latitudes of potential peaks **maxes** : list-like or NoneType Indices of identified peaks or None (default=None) :Returns: **p1** : int or NoneType Index of the first peak, or None if not found **p2** : int or NoneType Index of the second peak, or None if not found .. !! processed by numpydoc !!