pyIntensityFeatures.proc.boundaries

Functions for identifying auroral oval luminosity boundaries.

Functions

`locate_boundaries`(fit_coeff, fit_covar, dominant_fit, ...)	Locate auroral luminosity boundaries using the Longden method.
`calc_boundary_uncertainty`(peak_number, fit_covar)	Calculate the uncertainty of a boundary location.
`locate_single_peak_boundaries`(fit_mu, fit_sigma, ...)	Locate auroral luminosity boundaries assuming a single peak.
`locate_mult_peak_boundaries`(fit_coeff, fit_covar, ...)	Locate auroral luminosity boundaries assuming a single peak.
`get_eval_boundaries`(fit_coeff, fit_cov, rvalue, ...[, ...])	Find and evaluate the PALB and EALB for a provided fit.

Module Contents

pyIntensityFeatures.proc.boundaries.locate_boundaries(fit_coeff, fit_covar, dominant_fit, min_mlat, max_mlat, method='best', max_peak_diff=5.0, strict_fit=False)[source]

Locate auroral luminosity boundaries using the Longden method.

Parameters:

fit_coeffarray-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_covararray-like: Covarience matrix for the fit_coeff values
dominant_fitint: 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_mlatfloat: Minimum latitude used to obtain fit in degrees
max_mlatfloat: Maximum latitude used to obtain fit in degrees
methodstr: 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_difffloat: 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_fitbool: Enforce positive values for the x-offsets in fit_coeff (default=False)

Returns:

eq_boundfloat or array-like: Equatorial boundary of the auroral oval, NaN if not calculated
po_boundfloat or array-like: Poleward boundary of the auroral oval, NaN if not calculated
un_bound_eqfloat or array-like: Uncertainty of the auroral oval equatorward boundary, NaN if not calculated
un_bound_pofloat or array-like: Uncertainty of the auroral oval poleward boundary, NaN if not calculated

Raises:

ValueError: If an unknown method is provided

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.

pyIntensityFeatures.proc.boundaries.calc_boundary_uncertainty(peak_number, fit_covar)[source]

Calculate the uncertainty of a boundary location.

Parameters:

peak_numberint: 1-offset number of the primary peak (e.g., 1, 2, 3)
fit_covararray-like: Covarience matrix for the fit_coeff values

Returns:

un_boundfloat: Boundary uncertainty

pyIntensityFeatures.proc.boundaries.locate_single_peak_boundaries(fit_mu, fit_sigma, fit_covar, min_mlat, max_mlat, strict_fit=False)[source]

Locate auroral luminosity boundaries assuming a single peak.

Parameters:

fit_mufloat: Gaussian x offset from a single-peak fit, or dominant peak of a multi-peak fit.
fit_sigmafloat: Gaussian exponential scalar from a single-peak fit, or dominant peak of a multi-peak fit.
fit_covararray-like: Covarience matrix for the fit_coeff values
min_mlatfloat: Minimum latitude used to obtain fit in degrees
max_mlatfloat: Maximum latitude used to obtain fit in degrees
strict_fitbool: Enforce positive values for fit_sigma (default=False)

Returns:

eq_boundfloat or array-like: Equatorial boundary of the auroral oval, NaN if not calculated
po_boundfloat or array-like: Poleward boundary of the auroral oval, NaN if not calculated
un_bound_eqfloat or array-like: Uncertainty of the auroral oval equatorward boundary, NaN if not calculated
un_bound_pofloat or array-like: Uncertainty of the auroral oval poleward boundary, NaN if not calculated

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.

pyIntensityFeatures.proc.boundaries.locate_mult_peak_boundaries(fit_coeff, fit_covar, dominant_fit, min_mlat, max_mlat, max_peak_diff=5.0, strict_fit=False)[source]

Locate auroral luminosity boundaries assuming a single peak.

Parameters:

fit_coeffarray-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_covararray-like: Covarience matrix for the fit_coeff values
dominant_fitint: Integer specifying the number of peaks used in the Gaussian fit.
min_mlatfloat: Minimum latitude used to obtain fit in degrees
max_mlatfloat: Maximum latitude used to obtain fit in degrees
max_peak_difffloat: 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_fitbool: Enforce positive values for the x-offsets in fit_coeff (default=False)

Returns:

eq_boundfloat or array-like: Equatorial boundary of the auroral oval, NaN if not calculated
po_boundfloat or array-like: Poleward boundary of the auroral oval, NaN if not calculated
un_bound_eqfloat or array-like: Uncertainty of the auroral oval equatorward boundary, NaN if not calculated
un_bound_pofloat or array-like: Uncertainty of the auroral oval poleward boundary, NaN if not calculated

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.

pyIntensityFeatures.proc.boundaries.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)[source]

Find and evaluate the PALB and EALB for a provided fit.

Parameters:

fit_coeffarray-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_covararray-like: Covarience matrix for the fit_coeff values
rvaluefloat: Pearson correlation coefficient
pvaluefloat: Pearson p-value
num_peaksint: Number of Gaussian peaks in the fit.
min_mlatfloat: Minimum latitude used to obtain fit in degrees.
max_mlatfloat: Maximum latitude used to obtain fit in degrees.
methodstr: 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_thresholdfloat: Maximum acceptable uncertainty value in degrees (default=1.25)
dayglow_thresholdfloat: Minimum allowable background intensity value in Rayleighs (default=300)
strict_fitbool: Enforce positive values for the x-offsets in fit_coeff (default=False)

Returns:

boundslist: List of floats containing the EALB, PALB, EALB uncertaintly, and PALB uncertainty in that order. NaN if no realistic boundaries were found.
good_boundbool: True if the boundaries pass all tests, False otherwise.