OCB Gridding

OCB and dual-boundary gridding is performed by matching observations and OCBs and/or EABs in Universal Time (UT) and then normalising the AACGM magnetic coordinates of the observation to boundary coordinates. This is done by determining the observation’s location relative to the current boundary and placing it in the same location relative to a typical OCB and/or EAB. For the OCB, this defaults to 74 degrees, while for the EAB, this defaults to 64 degrees. Data matching is performed by ocbpy.cycle_boundary.match_data_ocb(). Coordinate normalisation, as well as boundary loading and data cycling is done within the appropriate boundary classes: OCBoundary, EABoundary, and DualBoundary.

For observations that depend on the cross polar cap potential, it is also important to scale the magnitude. This ensures that the magnitudes from different sized polar caps compare to the typical polar cap the OCB gridding produces. For vector data, the local polar north and east components may also change. Magnitude scaling is performed by ocbpy.ocb_scaling.normal_evar() or ocbpy.ocb_scaling.normal_curl_evar(). Vector scaling, re-orientation, and boundary coordinate normalisation are performed within the class VectorData. These classes and functions make up the ocbpy.ocb_scaling module.

Boundary Classes

Hold, manipulate, and load the OCB and EAB data.

References

[2] (1,2,3,4)

Angeline Burrell, Christer van der Meeren, & Karl M. Laundal. (2020). aburrell/aacgmv2 (All Versions). Zenodo. doi:10.5281/zenodo.1212694.

[3] (1,2,3)

Shepherd, S. G. (2014), Altitude‐adjusted corrected geomagnetic coordinates: Definition and functional approximations, Journal of Geophysical Research: Space Physics, 119, 7501–7521, doi:10.1002/2014JA020264.

class ocbpy._boundary.DualBoundary(eab_filename='default', ocb_filename='default', eab_instrument='', ocb_instrument='', hemisphere=1, eab_lat=64.0, ocb_lat=74.0, stime=None, etime=None, eab_rfunc=None, eab_rfunc_kwargs=None, ocb_rfunc=None, ocb_rfunc_kwargs=None, eab=None, ocb=None, max_delta=60)

Object containing EAB and OCB data for dual-boundary coordinates.

Parameters:

• eab_filename (str or NoneType) – File containing the required equatorward auroral boundary data sorted by time. If NoneType, no file is loaded. If ‘default’, ocbpy.boundaries.files.get_default_file is called. (default=’default’)

• ocb_filename (str or NoneType) – File containing the required open-closed field line boundary data sorted by time. If NoneType, no file is loaded. If ‘default’, ocbpy.boundaries.files.get_default_file is called. (default=’default’)

• eab_instrument (str) – Instrument providing the EABoundaries. Requires ‘image’, ‘ampere’, or ‘dmsp-ssj’ if a file is provided. If using filename=’default’, also accepts ‘si12’, ‘si13’, ‘wic’, ‘model’, and ‘’. (default=’’)

• ocb_instrument (str) – Instrument providing the OCBoundaries. Requires ‘image’, ‘ampere’, or ‘dmsp-ssj’ if a file is provided. If using filename=’default’, also accepts ‘si12’, ‘si13’, ‘wic’, ‘model’, and ‘’. (default=’’)

• hemisphere (int) – Integer (+/- 1) denoting northern/southern hemisphere (default=1)

• eab_lat (float) – Typical EABoundary latitude in AACGM coordinates. Hemisphere will give this boundary the desired sign. (default=64.0)

• ocb_lat (float) – Typical OCBoundary latitude in AACGM coordinates. Hemisphere will give this boundary the desired sign. (default=74.0)

• stime (dt.datetime, array-like, or NoneType) – First time to load data or beginning of file. If specifying time, be sure to start before the time of the data to allow the best match within the allowable time tolerance to be found. If running a model (e.g., instrument=’model’, provide an array of datetime values corresponding to the required driving index(es). (default=None)

• etime (dt.datetime or NoneType) – Last time to load data or ending of file. If specifying time, be sure to end after the last data point you wish to match to, to ensure the best match within the allowable time tolerance is made. (default=None)

• eab_rfunc (numpy.ndarray, function, or NoneType) – EAB radius correction or model function (if instrument is ‘model’). If None, will use the instrument default. Function must have AACGM MLT (in hours) as argument input. To allow the boundary shape to change with univeral time, each temporal instance may have a different function (array input). If a single function is provided, will recast as an array that specifies this function for all times. (default=None)

• eab_rfunc_kwargs (numpy.ndarray, dict, or NoneType) – Optional keyword arguments for eab_rfunc. If None is specified, uses function defaults. If dict is specified and instrument is ‘model’, any array-like values are expected to be the same length as dtime and will be recast as an array of dicts with single values. Otherwise, dict inputs are recasts as an array of this dict for all times. Array must be an array of dicts the same length as dtime. (default=None)

• ocb_rfunc (numpy.ndarray, function, or NoneType) – OCB radius correction or model function (if instrument is ‘model’). If None, will use the instrument default. Function must have AACGM MLT (in hours) as argument input. To allow the boundary shape to change with univeral time, each temporal instance may have a different function (array input). If a single function is provided, will recast as an array that specifies this function for all times. (default=None)

• ocb_rfunc_kwargs (numpy.ndarray, dict, or NoneType) – Optional keyword arguements for ocb_rfunc. If None is specified, uses function defaults. If dict is specified and instrument is ‘model’, any array-like values are expected to be the same length as dtime and will be recast as an array of dicts with single values. Otherwise, dict inputs are recasts as an array of this dict for all times. Array must be an array of dicts the same length as dtime. (default=None)

• eab (ocbpy.EABoundary or NoneType) – Equatorward auroral boundary data object or None to initialize here (default=None)

• ocb (ocbpy.OCBoundary) – Open-closed field line boundary data oject or Noneto initialize here (default=None)

• max_delta (int) – Maximum number of seconds allowed between paired EAB and OCB records (default=60)

eab

ocb

max_delta

hemisphere

dtime

Numpy array of paired boundary datetimes

Type:

numpy.ndarray

eab_ind

Numpy array of EAB indices for a good quality paired boundary

Type:

numpy.ndarray

ocb_ind

Numpy array of OCB indices for a good quality paired boundary

Type:

numpy.ndarray

rec_ind

Current OCB record index (default=0; initialised=-1)

Type:

int

records

Maximum number of paired boundary records

Type:

int

set_good_ind()

Pair the good indices for the quality EABs and OCBs.

get_next_good_ind()

Cycle to the the next quality paired boundary record.

normal_coord()

Convert data position(s) to normalised co-ordinates relative to the OCB.

revert_coord()

Convert the position of a measurement in OCB into AACGM co-ordinates.

get_aacgm_boundary_lats()

Calculate the EAB and OCB latitude in AACGM coordinates.

calc_r()

Calculate the scaled and unscaled radius at a normalised co-ordinates.

to_dict()

Provide the data in this class as a pair of dictionaries.

Raises:

ValueError – Incorrect or incompatible input, mismatched hemisphere assignment

calc_r(bound_lat, bound_mlt, aacgm_mlt, r_corr, overwrite=False)

Calculate the scaled and unscaled radius at a normalised co-ordinate.

Parameters:

• bound_lat (array-like or float) – Normalised dual-boundary latitude in degrees

• bound_mlt (array-like or float) – Normalised dual-boundary MLT in hours

• aacgm_mlt (array-like or float) – MLT in AACGM coordinates in hours

• r_corr (array-like or float) – OCB radial correction in degrees

• overwrite (bool) – Overwrite previous boundary locations if this time already has calculated boundary latitudes for a different set of input longitudes (default=False).

Returns:

• scaled_r (array-like) – Scaled radius for the region (OCB, EAB, Sub-auroral) in degrees

• unscaled_r (array-like) – Unscaled radius for the region (OCB, EAB, Sub-auroral) in degrees

get_aacgm_boundary_lats(aacgm_mlt, rec_ind=None, overwrite=False, set_lon=True)

Calculate the OCB latitude in AACGM coordinates at specified MLTs.

Parameters:

• aacgm_mlt (int, float, or array-like) – AACGM longitude location(s) (in degrees) for which the OCB latitude will be calculated.

• rec_ind (int, array-like, or NoneType) – Record index for which the OCB AACGM latitude will be calculated, or None to calculate all boundary locations (default=None).

• overwrite (bool) – Overwrite previous boundary locations if this time already has calculated boundary latitudes for a different set of input longitudes (default=False).

• set_lon (bool) – Calculate the AACGM longitude of the OCB alongside the MLT (default=True).

See also

ocbpy.OCBoundary.get_aacgm_boundary_lat

get_next_good_ind()

Cycle the boundary attributes to the next good paired index.

normal_coord(lat, lt, coords='magnetic', height=350.0, method='ALLOWTRACE', overwrite=False)

Convert coordinates to be normalised relative to the EAB and OCB.

Parameters:

• lat (float or array-like) – Input latitude (degrees), must be geographic, geodetic, or AACGMV2

• lt (float or array-like) – Input local time (hours), must be solar or AACGMV2 magnetic

• coords (str) – Input coordiate system. Accepts ‘magnetic’, ‘geocentric’, or ‘geodetic’ (default=’magnetic’)

• height (float or array-like) – Height (km) at which AACGMV2 coordinates will be calculated, if geographic coordinates are provided (default=350.0)

• method (str) – String denoting which type(s) of conversion to perform, if geographic coordinates are provided. Expects either ‘TRACE’ or ‘ALLOWTRACE’. See AACGMV2 for details [2]. (default=’ALLOWTRACE’)

• overwrite (bool) – Allow the OCB and EAB AACGM boundary locations to be overwritten (default=False)

Returns:

• bound_lat (float or array-like) – Magnetic latitude relative to EAB and OCB (degrees)

• bound_mlt (float or array-like) – Magnetic local time relative to EAB and OCB (hours)

• ocb_lat (float or array-like) – Magnetic latitude relative to only the OCB (degrees)

• r_corr (float or array-like) – Radius correction to OCB (degrees)

Notes

Approximation - Conversion assumes a planar surface

Defines bound_mlt relative to only the OCB.

See also

aacgmv2, ocbpy.OCBoundary.normal_coord

property rec_ind

Record index that identifies the current good EAB/OCB pair.

revert_coord(ocb_lat, ocb_mlt, r_corr=0.0, is_ocb=True, aacgm_mlt=None, coords='magnetic', height=350.0, method='ALLOWTRACE', overwrite=False)

Convert from OCB or dual-boundary into AACGM co-ordinates.

Parameters:

• ocb_lat (float or array-like) – Input OCB or dual-boundary latitude in degrees

• ocb_mlt (float or array-like) – Input OCB/dual-boundary local time in hours

• r_corr (float or array-like) – Input OCB radial correction in degrees, may be a function of AACGM MLT (default=0.0)

• is_ocb (bool) – Specifies that the input of ocb_lat is in OCB coordinates if True or in dual-boundary coordinates if False. If False, aacgm_mlt must be provided (default=True)

• aacgm_mlt (float, array-like, or NoneType) – Output AACGM MLT of the dual-boundary data, only used if is_ocb is False (default=None)

• coords (str) – Output coordiate system. Accepts ‘magnetic’, ‘geocentric’, or ‘geodetic’ (default=’magnetic’)

• height (float or array-like) – Geocentric height above sea level (km) at which AACGMV2 coordinates will be calculated, if geographic coordinates are desired (default=350.0)

• method (str) – String denoting which type(s) of conversion to perform, if geographic coordinates are provided. Expects either ‘TRACE’ or ‘ALLOWTRACE’. See AACGMV2 for details [2]. (default=’ALLOWTRACE’)

• overwrite (bool) – Allow the OCB and EAB AACGM boundary locations to be overwritten (default=False)

Returns:

• lat (float or array-like) – latitude (degrees)

• lt (float or array-like) – local time (hours)

Raises:

ValueError – When necessary inputs are not fully supplied

Notes

Approximation - Conversion assumes a planar surface

See also

aacgmv2, ocbpy.OCBoundary.revert_coord

set_good_ind(ocb_min_merit=None, ocb_max_merit=None, ocb_kwargs=None, eab_min_merit=None, eab_max_merit=None, eab_kwargs=None)

Pair the good indices for the quality EABs and OCBs.

Parameters:

• ocb_min_merit (float or NoneType) – Minimum value for the default figure of merit or None to not apply a custom minimum (default=None)

• ocb_max_merit (float or NoneTye) – Maximum value for the default figure of merit or None to not apply a custom maximum (default=None)

• ocb_kwargs (dict or NoneType) – Dict with optional selection criteria. The key should correspond to a data attribute and the value must be a tuple with the first value specifying ‘max’, ‘min’, ‘maxeq’, ‘mineq’, or ‘equal’ and the second value specifying the value to use in the comparison. None provides no optional selection criteria. (default=None)

• eab_min_merit (float or NoneType) – Minimum value for the default figure of merit or None to not apply a custom minimum (default=None)

• eab_max_merit (float or NoneTye) – Maximum value for the default figure of merit or None to not apply a custom maximum (default=None)

• eab_kwargs (dict or NoneType) – Dict with optional selection criteria. The key should correspond to a data attribute and the value must be a tuple with the first value specifying ‘max’, ‘min’, ‘maxeq’, ‘mineq’, or ‘equal’ and the second value specifying the value to use in the comparison. None provides no optional selection criteria. (default=None)

to_dict(xarray_style=False, sel_inds=None)

Convert the boundary data into a pair of dictionaries.

Parameters:

• xarray_style (bool) – If True, dict values will be a tuple with a tuple of dimensions as first item and data as the second item (default=False)

• sel_inds (list or NoneType) – Output a subset of the paired data to the dictionaries if not None (default=None)

Returns:

• data (dict) – Output with class data attributes as keys

• info (dict) – Output with class informational attributes as keys

Raises:

ValueError – If output type is inconsistent with class data

class ocbpy._boundary.EABoundary(filename='default', instrument='', hemisphere=1, boundary_lat=64.0, stime=None, etime=None, rfunc=None, rfunc_kwargs=None)

Object containing equatorward auroral boundary (EAB) data.

Parameters:

• filename (str or NoneType) – File containing the required equatorward auroral boundary data sorted by time. If NoneType, no file is loaded. If ‘default’, ocbpy.boundaries.files.get_default_file is called. (default=’default’)

• instrument (str) – Instrument providing the EABoundaries. Requires ‘image’ or ‘dmsp-ssj’ if a file is provided. If using filename=’default’, also accepts ‘si12’, ‘si13’, ‘wic’, ‘model’, and ‘’. (default=’’)

• hemisphere (int) – Integer (+/- 1) denoting northern/southern hemisphere (default=1)

• boundary_lat (float) – Typical EABoundary latitude in AACGM coordinates. Hemisphere will give this boundary the desired sign. (default=64.0)

• stime (dt.datetime, array-like, or NoneType) – First time to load data or beginning of file. If specifying time, be sure to start before the time of the data to allow the best match within the allowable time tolerance to be found. If running a model (e.g., instrument=’model’, provide an array of datetime values corresponding to the required driving index(es). (default=None)

• etime (dt.datetime or NoneType) – Last time to load data or ending of file. If specifying time, be sure to end after the last data point you wish to match to, to ensure the best match within the allowable time tolerance is made. (default=None)

• rfunc (numpy.ndarray, function, or NoneType) – EAB radius correction or model function (if instrument is ‘model’). If None, will use the instrument default. Function must have AACGM MLT (in hours) as argument input. To allow the boundary shape to change with univeral time, each temporal instance may have a different function (array input). If a single function is provided, will recast as an array that specifies this function for all times. (default=None)

• rfunc_kwargs (numpy.ndarray, dict, or NoneType) – Optional keyword arguments for rfunc. If None is specified, uses function defaults. If dict is specified and instrument is ‘model’, any array-like values are expected to be the same length as dtime and will be recast as an array of dicts with single values. Otherwise, dict inputs are recasts as an array of this dict for all times. Array must be an array of dicts the same length as dtime. (default=None)

See also

ocbpy.OCBoundary

Raises:

ValueError – Incorrect or incompatible input

class ocbpy._boundary.OCBoundary(filename='default', instrument='', hemisphere=1, boundary_lat=74.0, stime=None, etime=None, rfunc=None, rfunc_kwargs=None)

Object containing open-closed field-line boundary (OCB) data.

Parameters:

• filename (str or NoneType) – File containing the required open-closed boundary data sorted by time. If NoneType, no file is loaded. If ‘default’, ocbpy.boundaries.files.get_default_file is called. (default=’default’)

• instrument (str) – Instrument providing the OCBoundaries. Requires ‘image’, ‘ampere’, or ‘dmsp-ssj’ if a file is provided through filename. If using filename=’default’, also accepts ‘amp’, ‘si12’, ‘si13’, ‘wic’, ‘model’, and ‘’. (default=’’)

• hemisphere (int) – Integer (+/- 1) denoting northern/southern hemisphere (default=1)

• boundary_lat (float) – Typical OCBoundary latitude in AACGM coordinates. Hemisphere will give this boundary the desired sign. (default=74.0)

• stime (dt.datetime, array-like, or NoneType) – First time to load data or beginning of file. If specifying time, be sure to start before the time of the data to allow the best match within the allowable time tolerance to be found. If running a model (e.g., instrument=’model’, provide an array of datetime values corresponding to the required driving index(es). (default=None)

• etime (dt.datetime or NoneType) – Last time to load data or ending of file. If specifying time, be sure to end after the last data point you wish to match to, to ensure the best match within the allowable time tolerance is made. (default=None)

• rfunc (numpy.ndarray, function, or NoneType) – OCB radius correction or model function (if instrument is ‘model’). If None, will use the instrument default. Function must have AACGM MLT (in hours) as argument input. To allow the boundary shape to change with univeral time, each temporal instance may have a different function (array input). If a single function is provided, will recast as an array that specifies this function for all times. (default=None)

• rfunc_kwargs (numpy.ndarray, dict, or NoneType) – Optional keyword arguments for rfunc. If None is specified, uses function defaults. If dict is specified and instrument is ‘model’, any array-like values are expected to be the same length as dtime and will be recast as an array of dicts with single values. Otherwise, dict inputs are recasts as an array of this dict for all times. Array must be an array of dicts the same length as dtime. (default=None)

records

Number of boundary records (default=0)

Type:

int

rec_ind

Current boundary record index (default=0; initialised=-1)

Type:

int

dtime

Numpy array of boundary datetimes (default=None)

Type:

numpy.ndarray or NoneType

phi_cent

Numpy array of floats that give the angle from AACGM midnight of the boundary pole in degrees (default=None)

Type:

numpy.ndarray or NoneType

r_cent

Numpy array of floats that give the AACGM co-latitude of the boundary pole in degrees (default=None)

Type:

numpy.ndarray or NoneType

r

Numpy array of floats that give the radius of the boundary in degrees (default=None)

Type:

numpy.ndarray or NoneType

fom

Numpy array of floats that provides a figure of merit that can be used to evaluate the quality of the boundary (default=None)

Type:

numpy.ndarray or NoneType

min_fom

Minimum acceptable figure of merit for data (default=-np.inf)

Type:

float

max_fom

Maximum acceptable figure of merit for data (default=np.inf)

Type:

float

x, y, etc.

Numpy array of floats that hold the remaining values held in filename

Type:

numpy.ndarray or NoneType

inst_defaults()

Get the instrument-specific boundary file loading information.

load()

Load the data from the specified boundary file or model.

get_next_good_ocb_ind()

Cycle to the the next quality boundary record.

normal_coord()

Convert data position(s) to normalised co-ordinates relative to the OCB.

revert_coord()

Convert the position of a measurement in OCB into AACGM co-ordinates.

get_aacgm_boundary_lat()

Calculate the OCB latitude in AACGM coordinates at specified MLTs.

to_dict()

Provide the data in this class as a pair of dictionaries.

Raises:

ValueError – Incorrect or incompatible input

get_aacgm_boundary_lat(aacgm_mlt, rec_ind=None, overwrite=False, set_lon=True)

Calculate the OCB latitude in AACGM coordinates at specified MLTs.

Parameters:

• aacgm_mlt (int, float, or array-like) – AACGM longitude location(s) (in degrees) for which the OCB latitude will be calculated.

• rec_ind (int, array-like, or NoneType) – Record index for which the OCB AACGM latitude will be calculated, or None to calculate all boundary locations (default=None).

• overwrite (bool) – Overwrite previous boundary locations if this time already has calculated boundary latitudes for a different set of input longitudes (default=False).

• set_lon (bool) – Calculate the AACGM longitude of the OCB alongside the MLT (default=True).

Notes

Updates OCBoundary object with list attributes. If no boundary value is calculated at a certain time, the list is padded with None. If a boundary latitude cannot be calculated at that time and longitude, that time and longitude is filled with NaN.

aacgm_boundary_lat contains the AACGM latitude location(s) of the OCB (in degrees) for each requested time [3].

aacgm_boundary_mlt holds the aacgm_mlt input for each requested time. The requested MLT may differ from time to time, to allow easy comparison with satellite passes [3].

aacgm_boundary_lon holds the aacgm_lon input for each requested time. This is calculated from aacgm_boundary_mlt by default [3].

If the boundary radius is not defined at all MLT (possible for poorly constrained boundaries), then MLT with multiple boundary values will only return one possible solution.

get_next_good_ocb_ind(min_merit=None, max_merit=None, **kwargs)

Cycle to the the next quality OCB record.

Parameters:

• min_merit (float or NoneType) – Minimum value for the default figure of merit or None to not apply a custom minimum (default=None)

• max_merit (float or NoneTye) – Maximum value for the default figure of merit or None to not apply a custom maximum (default=None)

• kwargs (dict) – Dict with optional selection criteria. The key should correspond to a data attribute and the value must be a tuple with the first value specifying ‘max’, ‘min’, ‘maxeq’, ‘mineq’, or ‘equal’ and the second value specifying the value to use in the comparison.

Notes

Updates self.rec_ind to the index of next good OCB record or a value greater than self.records if there aren’t any more good records available after the starting point

AMPERE/DMSP-SSJ and new IMAGE FUV checks that: - the Figure of Merit is greater than or equal to the specified minimum (min_fom) or less than or equal to the specified maximum (max_fom)

inst_defaults()

Get the instrument-specific OCB file loading information.

Returns:

• hlines (int) – Number of header lines

• ocb_cols (str) – String containing the names for each data column

• datetime_fmt (str) – String containing the datetime format

Notes

Updates the min_fom attribute for AMPERE and DMSP-SSJ

load(hlines=0, ocb_cols='year soy num_sectors phi_cent r_cent r a r_err fom', datetime_fmt='', stime=None, etime=None)

Load the data from the specified boundary file.

Parameters:

• ocb_cols (str) – String specifying format of OCB file. All but the first two columns must be included in the string, additional data values will be ignored. If ‘year soy’ aren’t used, expects ‘date time’ in ‘YYYY-MM-DD HH:MM:SS’ format. (default=’year soy num_sectors phi_cent r_cent r a r_err r_merit’)

• hlines (int) – Number of header lines preceeding data in the OCB file (default=0)

• datetime_fmt (str) – A string used to read in ‘date time’ data. Not used if ‘year soy’ is specified. (default=’’)

• stime (dt.datetime, array-like, or NoneType) – Time to start loading data, array of times for model calculation, or None to start at beginning of an instrument file. (default=None)

• etime (datetime or NoneType) – Time to stop loading data or None to end at the end of the file. (default=None)

normal_coord(lat, lt, coords='magnetic', height=350.0, method='ALLOWTRACE')

Convert position(s) to normalised co-ordinates relative to the OCB.

Parameters:

• lat (float or array-like) – Input latitude (degrees), must be geographic, geodetic, or AACGMV2

• lt (float or array-like) – Input local time (hours), must be solar or AACGMV2 magnetic

• coords (str) – Input coordiate system. Accepts ‘magnetic’, ‘geocentric’, or ‘geodetic’ (default=’magnetic’)

• height (float or array-like) – Height (km) at which AACGMV2 coordinates will be calculated, if geographic coordinates are provided (default=350.0)

• method (str) – String denoting which type(s) of conversion to perform, if geographic coordinates are provided. Expects either ‘TRACE’ or ‘ALLOWTRACE’. See AACGMV2 for details [2]. (default=’ALLOWTRACE’)

Returns:

• ocb_lat (float or array-like) – Magnetic latitude relative to OCB (degrees)

• ocb_mlt (float or array-like) – Magnetic local time relative to OCB (hours)

• r_corr (float or array-like) – Radius correction to OCB (degrees)

Notes

Approximation - Conversion assumes a planar surface

See also

aacgmv2

revert_coord(ocb_lat, ocb_mlt, r_corr=0.0, coords='magnetic', height=350.0, method='ALLOWTRACE')

Convert the position of a measurement in OCB into AACGM co-ordinates.

Parameters:

• ocb_lat (float or array-like) – Input OCB latitude in degrees

• ocb_mlt (float or array-like) – Input OCB local time in hours

• r_corr (float or array-like) – Input OCB radial correction in degrees, may be a function of AACGM MLT (default=0.0)

• coords (str) – Output coordiate system. Accepts ‘magnetic’, ‘geocentric’, or ‘geodetic’ (default=’magnetic’)

• height (float or array-like) – Geocentric height above sea level (km) at which AACGMV2 coordinates will be calculated, if geographic coordinates are desired (default=350.0)

• method (str) – String denoting which type(s) of conversion to perform, if geographic coordinates are provided. Expects either ‘TRACE’ or ‘ALLOWTRACE’. See AACGMV2 for details [2]. (default=’ALLOWTRACE’)

Returns:

• lat (float or array-like) – latitude (degrees)

• lt (float or array-like) – local time (hours)

Notes

Approximation - Conversion assumes a planar surface

See also

aacgmv2

to_dict(xarray_style=False, sel_inds=None)

Convert the boundary data into a pair of dictionaries.

Parameters:

• xarray_style (bool) – If True, dict values will be a tuple with a tuple of dimensions as first item and data as the second item (default=False)

• sel_inds (list or NoneType) – Output a subset of the data to the dictionaries if not None (default=None)

Returns:

• data (dict) – Output with class data attributes as keys

• info (dict) – Output with class informational attributes as keys

Raises:

ValueError – If output type is inconsistent with class data

Cycle Boundary Module

Routines to match and cycle through the OCboundary class records.

ocbpy.cycle_boundary.match_data_ocb(ocb, dat_dtime, idat=0, max_tol=60, min_merit=None, max_merit=None, **kwargs)

Match data records with OCB records.

Parameters:

• ocb (ocbpy.OCBoundary, ocbpy.EABoundary, or ocbpy.DualBoundary) – Class containing the open-close field line, equatorial auroral boundary, or dual-boundary data

• dat_dtime (list-like) – List or array of datetime objects where data exists

• idat (int) – Current data index (default=0)

• max_tol (int) – maximum seconds between OCB and data record in sec (default=60)

• min_merit (float or NoneType) – Minimum value for the default figure of merit or None to not apply a custom minimum (default=None)

• max_merit (float or NoneTye) – Maximum value for the default figure of merit or None to not apply a custom maximum (default=None)

• kwargs (dict) – Dict with optional selection criteria. The key should correspond to a data attribute and the value must be a tuple with the first value specifying ‘max’, ‘min’, ‘maxeq’, ‘mineq’, or ‘equal’ and the second value specifying the value to use in the comparison.

Returns:

idat – Data index for match value, None if all of the data have been searched

Return type:

int or NoneType

Raises:

ValueError – If the input boundary class has an unknown cycling method name

Notes

Updates ocb.rec_ind for matched value. This attribute is set to None if all of the boundaries have been searched.

ocbpy.cycle_boundary.retrieve_all_good_indices(ocb, min_merit=None, max_merit=None, **kwargs)

Retrieve all good indices from the OCBoundary class.

Parameters:

• ocb (ocbpy.OCBoundary or ocbpy.EABoundary) – Class containing the open-close field line or equatorward auroral boundary data

• min_merit (float or NoneType) – Minimum value for the default figure of merit or None to not apply a custom minimum (default=None)

• max_merit (float or NoneTye) – Maximum value for the default figure of merit or None to not apply a custom maximum (default=None)

• kwargs (dict) – Dict with optional selection criteria. The key should correspond to a data attribute and the value must be a tuple with the first value specifying ‘max’, ‘min’, ‘maxeq’, ‘mineq’, or ‘equal’ and the second value specifying the value to use in the comparison.

Returns:

good_ind – List of indices containing good OCBs

Return type:

list

ocbpy.cycle_boundary.satellite_track(lat, mlt, x1, y1, x2, y2, hemisphere, del_x=1.0, del_y=1.0, past_bound=5.0)

Determine whether or not a point lies along the satellite track.

Parameters:

• lat (array-like) – AACGM latitude in degrees

• mlt (array-like) – AACGM local time in hours

• x1 (float) – Cartesian x-coordinate of the first boundary location in AACGM degrees along the Dawn-Dusk axis

• y1 (float) – Cartesian y-coordinate of the first boundary location in AACGM degrees along the Noon-Midnight axis

• x2 (float) – Cartesian x-coordinate of the second boundary location in AACGM degrees along the Dawn-Dusk axis

• y2 (float) – Cartesian y-coordinate of the second boundary location in AACGM degrees along the Noon-Midnight axis

• hemisphere (int) – Integer (+/- 1) denoting northern/southern hemisphere

• del_x (float) – Allowable distance from the track in AACGM degrees along the x-axis (default=1.0)

• del_y (float) – Allowable distance from the track in AACGM degrees along the y-axis (default=1.0)

• past_bound (float) – Allowable distance equatorward from the boundary in AACGM degrees (default=5.0)

Returns:

good – Array of booleans that are True if location is along the track and False if the location falls outside of the track

Return type:

array-like

Raises:

ValueError – If the boundary values are negative or if an unknown hemisphere is specified

OCB Scaling Module

Scale data affected by magnetic field direction or electric field.

References

[1] (1,2)

Chisham, G. (2017), A new methodology for the development of high-latitude ionospheric climatologies and empirical models, Journal of Geophysical Research: Space Physics, 122, doi:10.1002/2016JA023235.

class ocbpy.ocb_scaling.VectorData(dat_ind, ocb_ind, lat, lt, height=350.0, loc_coord='magnetic', ocb_lat=nan, ocb_mlt=nan, r_corr=nan, vect_n=0.0, vect_e=0.0, vect_z=0.0, vect_mag=nan, vect_coord='magnetic', dat_name=None, dat_units=None, scale_func=None)

Object containing a vector data.

Parameters:

• dat_ind (int or array-like) – Data index (zero offset) for the input

• ocb_ind (int or array-like) – OCBoundary or DualBoundary record index matched to this data index (zero offset)

• lat (float or array-like) – Vector latitude (degrees)

• lt (float or array-like) – Vector LT (hours)

• height (float or array-like) – Geocentric height above sea level (km) at which magnetic coordinates will be calculated if conversion is needed (default=350.0)

• loc_coord (str) – Name of the coordinate system for lat and lt; one of ‘magnetic’, ‘geocentric’, or ‘geodetic’ (default=’magnetic’)

• ocb_lat (float or array-like) – Vector OCB latitude (degrees) (default=np.nan)

• ocb_mlt (float or array-like) – Vector OCB MLT (hours) (default=np.nan)

• vect_n (float or array-like) – Vector North-pointing component (positive towards North) (default=0.0)

• vect_e (float or array-like) – Vector East-pointing component (completes right-handed coordinate system (default = 0.0)

• vect_z (float or array-like) – Vector vertical-pointing component (positive down) (default=0.0)

• vect_mag (float or array-like) – Vector magnitude (default=np.nan)

• vect_coord (str) – Name of the coordinate system for vect_n and vect_e; one of ‘magnetic’, ‘geocentric’, or ‘geodetic’ (default=’magnetic’)

• dat_name (str) – Data name (default=None)

• dat_units (str) – Data units (default=None)

• scale_func (function) – Function for scaling AACGM magnitude with arguements: [measurement value, mesurement AACGM latitude (degrees), mesurement OCB latitude (degrees)] (default=None)

vshape

Shape of output data

Type:

array-like

unscaled_r

Radius of polar cap in degrees

Type:

float or array-like

scaled_r

Radius of normalised OCB polar cap in degrees

Type:

float or array-like

ocb_n

OCB north component of data vector (default=np.nan)

Type:

float or array-like

ocb_e

OCB east component of data vector (default=np.nan)

Type:

float or array-like

ocb_z

OCB vertical component of data vector (default=np.nan)

Type:

float or array-like

ocb_mag

OCB magnitude of data vector (default=np.nan)

Type:

float or array-like

ocb_quad

AACGM quadrant of OCB pole (default=0)

Type:

int or array-like

vec_quad

AACGM quadrant of Vector (default=0)

Type:

int or array-like

pole_angle

Angle at vector location appended by AACGM and OCB poles in degrees (default=np.nan)

Type:

float or array-like

ocb_aacgm_lat

AACGM latitude of OCB pole in degrees (default=np.nan)

Type:

float or array-like

ocb_aacgm_mlt

AACGM MLT of OCB pole in hours (default=np.nan)

Type:

float or array-like

Notes

May only handle one data type, so scale_func cannot be an array

calc_vec_pole_angle()

Calc the angle between the AACGM pole, data, and the OCB pole.

Raises:

ValueError – If the input is undefined or inappropriate

Notes

Requires lt and lat in magnetic coordinates, as well as defined ocb_aacgm_mlt and ocb_aacgm_lat attributes. Updates pole_angle using spherical trigonometry.

clear_data()

Clear or initialize the output data attributes.

property dat_ind

Data index(es).

define_quadrants()

Define AACGM MLT quadrants for the OCB pole and data vector.

Notes

North (N) and East (E) are defined by the AACGM directions centred on the data vector location, assuming vertical is positive downwards Quadrants: 1 [N, E]; 2 [N, W]; 3 [S, W]; 4 [S, E]

Requires ocb_aacgm_mlt, lt, pole_angle, vect_n, and vect_e. Both loc_coord and vect_coord must be ‘magnetic’. Updates ocb_quad and vec_quad

Raises:

ValueError – If the required input is undefined or incorrect

property height

Vector in km.

property lat

Vector latitude in degrees.

property lt

Vector local time in hours.

property ocb_ind

Boundary index(es).

property ocb_lat

Boundary latitude in degrees.

property ocb_mlt

Boundary magnetic local time in hours.

property r_corr

Boundary radius correction in degrees.

scale_vector()

Normalise a variable proportional to the curl of the electric field.

Raises:

ValueError – If the required input is not defined

Notes

Requires lat, lt, ocb_aacgm_mlt, ocb_aacgm_lat, and pole_angle. Updates ocb_n, ocb_e, ocb_z, and ocb_mag.

set_ocb(ocb, scale_func=None, trace_method='ALLOWTRACE')

Set the OCBoundary values for provided data (updates all attributes).

Parameters:

• ocb (ocbpy.OCBoundary or ocbpy.DualBoundary) – OCB, EAB, or Dual boundary object

• scale_func (function) – Function for scaling the vector magnitude with arguments: measurement value, measurement latitude (degrees), and measurement boundary-adjusted latitude (degrees). Not necessary if defined earlier or no scaling is needed. (default=None)

• trace_method (str) – Desired AAGCM tracing method (default=’ALLOWTRACE’)

update_loc_coords(dtimes, coord='magnetic', trace_method='ALLOWTRACE')

Update location coordiantes to the desired system.

Parameters:

• dtimes (dt.datetime or list-like) – Datetime or list of datetimes for conversion

• coord (str) – Desired coordinate system, accepts ‘magnetic’, ‘geodetic’, and ‘geocentric’ (default=’magnetic’)

• trace_method (str) – Desired AAGCM tracing method (default=’ALLOWTRACE’)

Raises:

ValueError – If the time and location inputs are mismatched.

Notes

Updates lat, lt, and loc_coord attributes.

update_vect_coords_to_mag(dtimes, hemisphere, trace_method='ALLOWTRACE')

Convert geographic vector components into AAGGMV2 coordinates.

Parameters:

• dtimes (dt.datetime or list-like) – Datetime or list of datetimes for conversion

• hemisphere (int) – -1 for Southern, 1 for Northern

• trace_method (str) – Desired AAGCM tracing method (default=’ALLOWTRACE’)

Notes

This follows the procedure in set_ocb, and is complicated to reverse.

property vect_mag

Magntiude of the vector(s).

ocbpy.ocb_scaling.archav(hav)

Calculate the inverse haversine.

Parameters:

hav (float or array-like) – Haversine of an angle

Returns:

alpha – Angle in radians

Return type:

float or array-like

Notes

The input must be positive. However, any number with a magnitude below 10-16 will be rounded to zero. More negative numbers will return NaN.

ocbpy.ocb_scaling.hav(alpha)

Calculate the haversine.

Parameters:

alpha (float or array-like) – Angle in radians

Returns:

hav_alpha – Haversine of alpha, equal to the square of the sine of half-alpha

Return type:

float or array-like

ocbpy.ocb_scaling.normal_curl_evar(curl_evar, unscaled_r, scaled_r)

Normalise a variable proportional to the curl of the electric field.

Parameters:

• curl_evar (float or array) – Variable related to electric field (e.g. vorticity)

• unscaled_r (float or array) – Radius of polar cap in degrees

• scaled_r (float or array) – Radius of normalised OCB polar cap in degrees

Returns:

nvar – Normalised variable

Return type:

float or array

Notes

Assumes that the cross polar cap potential is fixed across the polar cap regardless of the radius of the Open Closed field line Boundary. This is commonly assumed when looking at statistical patterns that control the IMF (which accounts for dayside reconnection) and assume that the nightside reconnection influence is averaged out over the averaged period [1].

ocbpy.ocb_scaling.normal_evar(evar, unscaled_r, scaled_r)

Normalise a variable proportional to the electric field.

Parameters:

• evar (float or array) – Variable related to electric field (e.g. velocity)

• unscaled_r (float or array) – Radius of polar cap in degrees

• scaled_r (float or array) – Radius of normalised OCB polar cap in degrees

Returns:

nvar – Normalised variable

Return type:

float or array

Notes

Assumes that the cross polar cap potential is fixed across the polar cap regardless of the radius of the Open Closed field line Boundary. This is commonly assumed when looking at statistical patterns that control the IMF (which accounts for dayside reconnection) and assume that the nightside reconnection influence is averaged out over the averaged period [1].

Vector Functions

Functions for performing vector transformations.

ocbpy.vectors.adjust_vector(vect_lt, vect_lat, vect_n, vect_e, vect_z, vect_quad, pole_lt, pole_lat, pole_angle, pole_quad)

Adjust a vector from one coordinate system to another.

Parameters:

• vect_lt (float or array-like) – Vector local time in base coordinate system in hours

• vect_lat (float or array-like) – Vector latitude in base coordinate system in degrees

• vect_n (float or array-like) – Vector North component in base coordinate system in degrees latitude

• vect_e (float or array-like) – Vector East component in base coordinate system in degrees latitude

• vect_z (float or array-like) – Vector vertical component in base coordinate system in degrees latitude

• vect_quad (float or array-like) – Specifies the base coordinate system LT quadrant for each data vector

• pole_lt (float or array-like) – Local time of destination pole location in the base coordinate system in hours

• pole_lat (float or array-like) – Latitude of destination pole location in the base coordinate system in degrees

• pole_angle (float or array-like) – Angle between the base coordinate system pole, data location, and the destination coordinate sytem pole (as located in the base coordinate system) in degrees

• pole_quad (float or array-like) – Specifies the base coordinate system LT quadrant for each pole/data pair

Returns:

• dest_n (float or array-like) – Vector North component in destination coordinate system in degrees latitude

• dest_e (float or array-like) – Vector East component in destination coordinate system in degrees latitude

• dest_z (float or array-like) – Vector vertical component in destination coordinate system in degrees latitude

ocbpy.vectors.calc_dest_polar_angle(pole_quad, vect_quad, base_naz_angle, pole_angle)

Calcuate the North azimuth angle for the destination pole.

Parameters:

• pole_quad (float or array-like) – Specifies the base coordinate system LT quadrant for each pole/data pair

• vect_quad (float or array-like) – Specifies the base coordinate system LT quadrant for each data vector

• base_naz_angle (float or array-like) – North azimuth angle for the base coordinate system pole in degrees

• pole_angle (float or array-like) – Angle between the base coordinate system pole, data location, and the destination coordinate sytem pole (as located in the base coordinate system) in degrees

Returns:

dest_naz_angle – North azimuth angle for the destination coordinate system pole in degrees

Return type:

float or array-like

Raises:

ValueError – If the input quadrant data is undefined

ocbpy.vectors.calc_dest_vec_sign(pole_quad, vect_quad, base_naz_angle, pole_angle, north=False, east=False, quads=None)

Calculate the sign of the North and East components.

Parameters:

• pole_quad (float or array-like) – Specifies the base coordinate system LT quadrant for each pole/data pair

• vect_quad (float or array-like) – Specifies the base coordinate system LT quadrant for each data vector

• base_naz_angle (float or array-like) – North azimuth angle for the base coordinate system pole in degrees

• pole_angle (float or array-like) – Angle between the base coordinate system pole, data location, and the destination coordinate sytem pole (as located in the base coordinate system) in degrees

• north (bool) – Get the sign of the north component(s) (default=False)

• east (bool) – Get the sign of the east component(s) (default=False)

• quads (dict or NoneType) – Dictionary of boolean values or arrays of boolean values for the destination coordinate system pole and data vector quadrants (default=None)

Returns:

vsigns – Dictionary with keys ‘north’ and ‘east’ containing the desired signs

Return type:

dict

Raises:

ValueError – If the input quadrant data is undefined

ocbpy.vectors.calc_vec_pole_angle(data_lt, data_lat, pole_lt, pole_lat)

Find the angle between the base pole, data, and the other pole.

Parameters:

• data_lt (float or array-like) – Local time of data in the base coordinate system in hours

• data_lat (float or array-like) – Latitude of data in the base coordinate system in degrees

• pole_lt (float or array-like) – Local time of destination pole location in the base coordinate system in hours

• pole_lat (float or array-like) – Latitude of destination pole location in the base coordinate system in degrees

Returns:

pole_angle – Angle between the base coordinate system pole, data location, and the destination coordinate sytem pole (as located in the base coordinate system) in degrees

Return type:

float or array-like

Notes

The data coordinates must be in the base coordinate system. Finds the pole_angle using spherical trigonometry.

ocbpy.vectors.define_pole_quadrants(data_lt, pole_lt, pole_angle)

Define LT quadrants for the pole of the another coordinate system.

Parameters:

• data_lt (float or array-like) – Local time of data in the base coordinate system in hours

• pole_lt (float or array-like) – Local time of destination pole location in the base coordinate system in hours

• pole_angle (float or array-like) – Angle between the base coordinate system pole, data location, and the destination coordinate sytem pole (as located in the base coordinate system) in degrees

Returns:

pole_quad – Specifies the base coordinate system LT quadrant for each pole/data pair

Return type:

float or array-like

Notes

North (N) and East (E) are defined by the base coordinate system directions centred on the the data vector location, assuming vertical is positive downwards. Quadrants: 1 [N, E]; 2 [N, W]; 3 [S, W]; 4 [S, E]; 0 [undefined]

ocbpy.vectors.define_vect_quadrants(vect_n, vect_e)

Define LT quadrants for the data vectors.

Parameters:

• vect_n (float or array-like) – North component of data vector in the base coordinate system in units of degrees latitude

• vect_e (float or array-like) – East component of data vector in the base coordinate system in units of degrees latitude

Returns:

vect_quad – Specifies the base coordinate system LT quadrant for each data vector

Return type:

float or array-like

Notes

North (N) and East (E) are defined by the base coordinate system directions centred on the data vector location, assuming vertical is positive downwards Quadrants: 1 [N, E]; 2 [N, W]; 3 [S, W]; 4 [S, E]; 0 [undefined]

ocbpy.vectors.get_pole_loc(phi_cent, r_cent)

Convert a second coordinate system’s pole location to lt/lat.

Parameters:

• phi_cent (float or array-like) – The angle from midnight in the base coordinate system of the destination coordinate system pole in degrees

• r_cent (float or array-like) – The co-latitude in the base coordinate system of the destination coordinate system pole in degrees

Returns:

• pole_lt (float or array-like) – The base coordinate system LT of the destination coordinate system pole location in hours; float if both inputs are float-like

• pole_lat (float or array-like) – The base coordinate system latitude of the destination coordinate system pole location in degrees; float if both inputs are float-like