pyIntensityFeatures.proc.boundaries =================================== .. py:module:: pyIntensityFeatures.proc.boundaries .. autoapi-nested-parse:: Functions for identifying auroral oval luminosity boundaries. .. !! processed by numpydoc !! Functions --------- .. autoapisummary:: pyIntensityFeatures.proc.boundaries.locate_boundaries pyIntensityFeatures.proc.boundaries.calc_boundary_uncertainty pyIntensityFeatures.proc.boundaries.locate_single_peak_boundaries pyIntensityFeatures.proc.boundaries.locate_mult_peak_boundaries pyIntensityFeatures.proc.boundaries.get_eval_boundaries Module Contents --------------- .. py:function:: locate_boundaries(fit_coeff, fit_covar, dominant_fit, min_mlat, max_mlat, method='best', max_peak_diff=5.0, strict_fit=False) Locate auroral luminosity boundaries using the Longden method. :Parameters: **fit_coeff** : array-like Fit coefficients constant, quadratic multiplier for x, quadratic multiplier for x^2, and Gaussian amplitudes, x offsets, and exponential scalers for each Gaussian. The number of each Gaussian group must be the same; e.g., there must be two of each amplitude, x offset, and exponential scalers, but only one constant and quadratic multipliers. **fit_covar** : array-like Covarience matrix for the `fit_coeff` values **dominant_fit** : int Integer specifying whether the dominant fit is single (1), double (2), or multi (any integer) peaked. If the 'single' or 'mult' method is specified, this must correspond to the desired method or no boundaries will be calculated. **min_mlat** : float Minimum latitude used to obtain fit in degrees **max_mlat** : float Maximum latitude used to obtain fit in degrees **method** : str Specify which method to use, single Gaussian ('single'), multi-peak Gaussian ('mult'), or use `dominant_fit` to identify the most appropriate method ('best'). (default='best') **max_peak_diff** : float For multi-peak fits, the maximum allowable difference between peak locations to be considered for boundary selection relative to the primary peak (default=5.0) **strict_fit** : bool Enforce positive values for the x-offsets in `fit_coeff` (default=False) :Returns: **eq_bound** : float or array-like Equatorial boundary of the auroral oval, NaN if not calculated **po_bound** : float or array-like Poleward boundary of the auroral oval, NaN if not calculated **un_bound_eq** : float or array-like Uncertainty of the auroral oval equatorward boundary, NaN if not calculated **un_bound_po** : float or array-like Uncertainty of the auroral oval poleward boundary, NaN if not calculated :Raises: ValueError If an unknown method is provided .. rubric:: References Longden, N. S., et al. (2010) Estimating the location of the open-closed magnetic field line boundary from auroral images, 28 (9), p 1659-1678, doi:10.5194/angeo-28-1659-2010. .. only:: latex .. !! processed by numpydoc !! .. py:function:: calc_boundary_uncertainty(peak_number, fit_covar) Calculate the uncertainty of a boundary location. :Parameters: **peak_number** : int 1-offset number of the primary peak (e.g., 1, 2, 3) **fit_covar** : array-like Covarience matrix for the `fit_coeff` values :Returns: **un_bound** : float Boundary uncertainty .. !! processed by numpydoc !! .. py:function:: locate_single_peak_boundaries(fit_mu, fit_sigma, fit_covar, min_mlat, max_mlat, strict_fit=False) Locate auroral luminosity boundaries assuming a single peak. :Parameters: **fit_mu** : float Gaussian x offset from a single-peak fit, or dominant peak of a multi-peak fit. **fit_sigma** : float Gaussian exponential scalar from a single-peak fit, or dominant peak of a multi-peak fit. **fit_covar** : array-like Covarience matrix for the `fit_coeff` values **min_mlat** : float Minimum latitude used to obtain fit in degrees **max_mlat** : float Maximum latitude used to obtain fit in degrees **strict_fit** : bool Enforce positive values for `fit_sigma` (default=False) :Returns: **eq_bound** : float or array-like Equatorial boundary of the auroral oval, NaN if not calculated **po_bound** : float or array-like Poleward boundary of the auroral oval, NaN if not calculated **un_bound_eq** : float or array-like Uncertainty of the auroral oval equatorward boundary, NaN if not calculated **un_bound_po** : float or array-like Uncertainty of the auroral oval poleward boundary, NaN if not calculated .. rubric:: References Longden, N. S., et al. (2010) Estimating the location of the open-closed magnetic field line boundary from auroral images, 28 (9), p 1659-1678, doi:10.5194/angeo-28-1659-2010. .. only:: latex .. !! processed by numpydoc !! .. py:function:: locate_mult_peak_boundaries(fit_coeff, fit_covar, dominant_fit, min_mlat, max_mlat, max_peak_diff=5.0, strict_fit=False) Locate auroral luminosity boundaries assuming a single peak. :Parameters: **fit_coeff** : array-like Fit coefficients constant, quadratic multiplier for x, quadratic multiplier for x^2, and Gaussian amplitudes, x offsets, and exponential scalers for each Gaussian. The number of each Gaussian group must be the same; e.g., there must be two of each amplitude, x offset, and exponential scalers, but only one constant and quadratic multipliers. **fit_covar** : array-like Covarience matrix for the `fit_coeff` values **dominant_fit** : int Integer specifying the number of peaks used in the Gaussian fit. **min_mlat** : float Minimum latitude used to obtain fit in degrees **max_mlat** : float Maximum latitude used to obtain fit in degrees **max_peak_diff** : float For multi-peak fits, the maximum allowable difference between peak locations to be considered for boundary selection relative to the primary peak (default=5.0) **strict_fit** : bool Enforce positive values for the x-offsets in `fit_coeff` (default=False) :Returns: **eq_bound** : float or array-like Equatorial boundary of the auroral oval, NaN if not calculated **po_bound** : float or array-like Poleward boundary of the auroral oval, NaN if not calculated **un_bound_eq** : float or array-like Uncertainty of the auroral oval equatorward boundary, NaN if not calculated **un_bound_po** : float or array-like Uncertainty of the auroral oval poleward boundary, NaN if not calculated .. rubric:: References Longden, N. S., et al. (2010) Estimating the location of the open-closed magnetic field line boundary from auroral images, 28 (9), p 1659-1678, doi:10.5194/angeo-28-1659-2010. .. only:: latex .. !! processed by numpydoc !! .. py:function:: get_eval_boundaries(fit_coeff, fit_cov, rvalue, pvalue, num_peaks, mlat_min, mlat_max, method, un_threshold=1.25, dayglow_threshold=300.0, strict_fit=False) Find and evaluate the PALB and EALB for a provided fit. :Parameters: **fit_coeff** : array-like Fit coefficients constant, quadratic multiplier for x, quadratic multiplier for x^2, and Gaussian amplitudes, x offsets, and exponential scalers for each Gaussian. The number of each Gaussian group must be the same; e.g., there must be two of each amplitude, x offset, and exponential scalers, but only one constant and quadratic multipliers. **fit_covar** : array-like Covarience matrix for the `fit_coeff` values **rvalue** : float Pearson correlation coefficient **pvalue** : float Pearson p-value **num_peaks** : int Number of Gaussian peaks in the fit. **min_mlat** : float Minimum latitude used to obtain fit in degrees. **max_mlat** : float Maximum latitude used to obtain fit in degrees. **method** : str Specify which method to use, single Gaussian ('single'), multi-peak Gaussian ('mult'), or use `dominant_fit` to identify the most appropriate method ('best'). (default='best') **un_threshold** : float Maximum acceptable uncertainty value in degrees (default=1.25) **dayglow_threshold** : float Minimum allowable background intensity value in Rayleighs (default=300) **strict_fit** : bool Enforce positive values for the x-offsets in `fit_coeff` (default=False) :Returns: **bounds** : list List of floats containing the EALB, PALB, EALB uncertaintly, and PALB uncertainty in that order. NaN if no realistic boundaries were found. **good_bound** : bool True if the boundaries pass all tests, False otherwise. .. !! processed by numpydoc !!