OCB Gridding

OCB gridding is performed by matching observations and OCBs in Universal Time (UT) and then normalising the AACGM magnetic coordinates of the observation to OCB coordinates. This is done by determining the observation’s location relative to the current OCB and placing it in the same location relative to a typical OCB that has a magnetic latitude of 74 degrees. Data matching is performed by ocbpy.ocboundary.match_data_ocb. Coordinate normalisation, as well as OCB loading and data cycling is done within ocbpy.ocboundary.OCBoundary. These classes and functions make up the ocbpy.ocbounary module.

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 OCB coordinate normalisation are performed within the class VectorData. These classes and functions make up the ocbpy.ocb_scaling module.

OCBoundary

Hold, manipulate, and load the open-closed field line boundary data

Functions

match_data_ocb(ocb, dat_dtime, kwargs)
Match data with open-closed field line boundaries

Classes

OCBoundary Loads, holds, and cycles the open-closed field line boundary data.
Calculates magnetic coordinates relative to OCB (setting OCB at 74 degrees latitude) given an AACGM location.

Moduleauthor

Angeline G. Burrell (AGB), 15 April 2017, University of Texas, Dallas (UTDallas)

References

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.ocboundary.OCBoundary(filename='default', instrument='image', hemisphere=1, boundary_lat=None, stime=None, etime=None)[source]

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

Parameters:
filename : (str or NoneType)

File containing the required open-closed circle boundary data sorted by time. If NoneType, no file is loaded. If ‘default’, the default IMAGE FUV file is loaded (if available). (default=’default’)

instrument : (str)

Instrument providing the OCBoundaries (default=’image’)

hemisphere : (int)

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

boundary_lat : (float)

Typical AACGM latitude of the OCBoundary or None to use instrument defaults (default=None)

stime : (datetime or NoneType)

First time to load data or beginning of file (default=None)

etime : (datetime or NoneType)

Last time to load data or ending of file (default=None)

Returns:
self : OCBoundary class object containing OCB file data
Attributes:
filename : (str or NoneType)

OCBoundary filename or None, if problem loading default

boundary_lat : (float)

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

hemisphere : (int)

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

records : (int)

Number of OCB records (default=0)

rec_ind : (int)

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

dtime : (numpy.ndarray or NoneType)

Numpy array of OCB datetimes (default=None)

phi_cent : (numpy.ndarray or NoneType)

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

r_cent : (numpy.ndarray or NoneType)

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

r : (numpy.ndarray or NoneType)

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

(more) : (numpy.ndarray or NoneType)

Numpy array of floats that hold the remaining values in input file

Methods

inst_defaults() Get the information needed to load an OCB file using instrument specific formatting, and update the boundary latitude for a given instrument type.
load(hlines=0, ocb_cols=’year soy num_sectors phi_cent r_cent r a r_err’, datetime_fmt=’‘, stime=None, etime=None) Load the data from the OCB file specified by self.filename
get_next_good_ocb_ind(min_sectors=7, rcent_dev=8.0, max_r=23.0, min_r=10.0, min_j=0.15) Cycle to the next good OCB index
normal_coord(aacgm_lat, aacgm_mlt) Calculate the OCB coordinates of an AACGM location
revert_coord(ocb_lat, ocb_mlt) Calculate the AACGM location of OCB coordinates for this OCB
get_next_good_ocb_ind(self, min_sectors=7, rcent_dev=8.0, max_r=23.0, min_r=10.0, min_j=0.15)[source]

read in the next usuable OCB record from the data file. Only uses the available parameters.

Parameters:
min_sectors : (int)

Minimum number of MLT sectors required for good OCB. (default=7)

rcent_dev : (float)

Maximum number of degrees between the new centre and the AACGM pole (default=8.0)

max_r : (float)

Maximum radius for open-closed field line boundary in degrees. (default=23.0)

min_r : (float)

Minimum radius for open-closed field line boundary in degrees (default=10.0)

min_j : (float)

Minimum unitless current magnitude scale difference (default=0.15)

Returns:
self

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

inst_defaults(self)[source]

Get the information needed to load an OCB file using instrument specific formatting, also update the boundary latitude for a given instrument type.

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

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

Load the data from the specified Open-Closed 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’)

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 : (datetime or NoneType)

Time to start loading data or None to start at beginning of file. (default=None)

etime : (datetime or NoneType)

Time to stop loading data or None to end at the end of the file. (default=None)

Returns:
self
normal_coord(self, aacgm_lat, aacgm_mlt)[source]

converts the position of a measurement in AACGM co-ordinates to normalised co-ordinates relative to the OCB

Parameters:
aacgm_lat : (float)

Input magnetic latitude (degrees)

aacgm_mlt : (float)

Input magnetic local time (hours)

Returns:
ocb_lat : (float)

Magnetic latitude relative to OCB (degrees)

ocb_mlt : (float)

Magnetic local time relative to OCB (hours)

revert_coord(self, ocb_lat, ocb_mlt)[source]

Converts the position of a measurement in normalised co-ordinates relative to the OCB into AACGM co-ordinates

Parameters:
ocb_lat : (float)

Input OCB latitude (degrees)

ocb_mlt : (float)

Input OCB local time (hours)

Returns:
aacgm_lat : (float)

AACGM latitude (degrees)

aacgm_mlt : (float)

AACGM magnetic local time (hours)

ocbpy.ocboundary.match_data_ocb(ocb, dat_dtime, idat=0, max_tol=600, min_sectors=7, rcent_dev=8.0, max_r=23.0, min_r=10.0, min_j=0.15)[source]

Matches data records with OCB records, locating the closest values within a specified tolerance

Parameters:
ocb : (OCBoundary)

Class containing the open-close field line boundary data

dat_dtime : (list or numpy array of datetime objects)

Times where data exists

idat : (int)

Current data index (default=0)

max_tol : (int)

maximum seconds between OCB and data record in sec (default=600)

min_sectors : (int)

Minimum number of MLT sectors required for good OCB. (default=7)

rcent_dev : (float)

Maximum number of degrees between the new centre and the AACGM pole (default=8.0)

max_r : (float)

Maximum radius for open-closed field line boundary in degrees. (default=23.0)

min_r : (float)

Minimum radius for open-closed field line boundary in degrees (default=10.0)

min_j : (float)

Minimum unitless current magnitude scale difference (default=0.15)

Returns:
idat : (int or NoneType)

Data index for match value. None if all of the data have been searched.

Notes

Updates OCBoundary.rec_ind for matched value. None if all of the boundaries have been searched.

OCB Scaling

Scale data affected by magnetic field direction or electric field

Routines

normal_evar(evar, unscaled_r, scaled_r)
Normalise a variable proportaional to the electric field (such as velocity)
normal_curl_evar(curl_evar, unscaled_r, scaled_r)
Normalise a variable proportional to the curl of the electric field (such as vorticity)

Classes

VectorData(object)
Holds vector data in AACGM N-E-Z coordinates along with location information. Converts vector from AACGM to OCB coordinates.

Moduleauthor

Angeline G. Burrell (AGB), 12 May 2017, University of Texas, Dallas (UTDallas)

References

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, aacgm_lat, aacgm_mlt, ocb_lat=nan, ocb_mlt=nan, aacgm_n=0.0, aacgm_e=0.0, aacgm_z=0.0, aacgm_mag=nan, dat_name=None, dat_units=None, scale_func=None)[source]

Object containing a vector data point

Parameters:
dat_ind : (int)

Data index (zero offset)

ocb_ind : (int)

OCBoundary record index matched to this data index (zero offset)

aacgm_lat : (float)

Vector AACGM latitude (degrees)

aacgm_mlt : (float)

Vector AACGM MLT (hours)

ocb_lat : (float)

Vector OCB latitude (degrees) (default=np.nan)

ocb_mlt : (float)

Vector OCB MLT (hours) (default=np.nan)

aacgm_n : (float)

AACGM North pointing vector (positive towards North) (default=0.0)

aacgm_e : (float)

AACGM East pointing vector (completes right-handed coordinate system (default = 0.0)

aacgm_z : (float)

AACGM Vertical pointing vector (positive down) (default=0.0)

aacgm_mag : (float)

Vector magnitude (default=np.nan)

scale_func : (function)

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

dat_name : (str)

Data name (default=None)

dat_units : (str)

Data units (default=None)

Attributes:
dat_name : (str or NoneType)

Name of data

dat_units : (str or NoneType)

Units of data

dat_ind : (int)

Vector data index in external data array

ocb_ind : (int)

OCBoundary rec_ind value that matches dat_ind

unscaled_r : (float)

Radius of polar cap in degrees

scaled_r : (float)

Radius of normalised OCB polar cap in degrees

aacgm_n : (float)

AACGM north component of data vector (default=0.0)

aacgm_e : (float)

AACGM east component of data vector (default=0.0)

aacgm_z : (float)

AACGM vertical component of data vector (default=0.0)

aacgm_mag : (float)

Magnitude of data vector in AACGM coordinates (default=np.nan)

aacgm_lat : (float)

AACGM latitude of data vector in degrees

aacgm_mlt : (float)

AACGM MLT of data vector in hours

ocb_n : (float)

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

ocb_e : (float)

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

ocb_z : (float)

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

ocb_mag : (float)

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

ocb_lat : (float)

OCB latitude of data vector in degrees (default=np.nan)

ocb_mlt : (float)

OCB MLT of data vector in hours (default=np.nan)

ocb_quad : (int)

AACGM quadrant of OCB pole (default=0)

vec_quad : (int)

AACGM quadrant of Vector (default=0)

pole_angle : (float)

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

aacgm_naz : (float)

AACGM north azimuth of data vector in degrees (default=np.nan)

ocb_aacgm_lat : (float)

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

ocb_aacgm_mlt : (float)

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

scale_func : (function or NoneType)

Funciton that scales the magnitude of the data vector from AACGM polar cap coverage to OCB polar cap coverage

Methods

set_ocb(ocb, scale_func=None) Set the ocb coordinates and vector values
define_quadrants() Define the OCB pole and vector AACGM quadrant
scale_vector() Scale the data vector into OCB coordinates
calc_ocb_polar_angle() calculate the OCB north azimuth angle
calc_ocb_vec_sign(north=False, east=False, quads=dict()) calculate the signs of the OCB scaled vector components
calc_vec_pole_angle(angular_res=1.0e-3) calculate the vector angle of the vector-poles triangle
calc_ocb_polar_angle(self)[source]

Calculate the OCB north azimuth angle

Returns:
ocb_naz : (float)

Angle between measurement vector and OCB pole in degrees

calc_ocb_vec_sign(self, north=False, east=False, quads={})[source]

Get the sign of the North and East components

Parameters:
north : (boolian)

Get the sign of the north component (default=False)

east : (boolian)

Get the sign of the east component (default=False)

quads : (dictionary)

Dictionary of boolian values for OCB and Vector quadrants (default=dict())

Returns:
vsigns : (dict)

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

calc_vec_pole_angle(self)[source]

calculates the angle between the AACGM pole, a measurement, and the OCB pole using spherical triginometry

define_quadrants(self)[source]

Determine which quadrants (in AACGM coordinates) the OCB pole and data vector lie in

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]

scale_vector(self)[source]

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

set_ocb(self, ocb, scale_func=None)[source]

Set the OCBoundary values for this data point

Parameters:
ocb : (OCBoundary)

Open Closed Boundary class object

scale_func : (function)

Function for scaling AACGM magnitude with arguements: [measurement value, mesurement AACGM latitude (degrees), mesurement OCB latitude (degrees)] Not necessary if defined earlier or no scaling is needed. (default=None)

ocbpy.ocb_scaling.archav(hav)[source]

Formula for the inverse haversine

Parameters:
hav : (float)

Haversine of an angle

Returns:
alpha : (float)

Angle in radians

ocbpy.ocb_scaling.hav(alpha)[source]

Formula for haversine

Parameters:
alpha : (float)

Angle in radians

Returns:
hav_alpha : (float)

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

ocbpy.ocb_scaling.normal_curl_evar(curl_evar, unscaled_r, scaled_r)[source]

Normalise a variable proportional to the curl of the electric field

Parameters:
curl_evar : (float)

Variable related to electric field (e.g. vorticity)

unscaled_r : (float)

Radius of polar cap in degrees

scaled_r : (float)

Radius of normalised OCB polar cap in degrees

Returns:
nvar : (float)

Normalised variable

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.

References

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

ocbpy.ocb_scaling.normal_evar(evar, unscaled_r, scaled_r)[source]

Normalise a variable proportional to the electric field

Parameters:
evar : (float)

Variable related to electric field (e.g. velocity)

unscaled_r : (float)

Radius of polar cap in degrees

scaled_r : (float)

Radius of normalised OCB polar cap in degrees

Returns:
nvar : (float)

Normalised variable

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.

References

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