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.ocboundary
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 Module¶
Hold, manipulate, and load the open-closed field line boundary data
References
[2] | (1, 2) 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.ocboundary.
OCBoundary
(filename='default', instrument='', hemisphere=1, boundary_lat=74.0, stime=None, etime=None, rfunc=None, rfunc_kwargs=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’, 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. If using filename=’default’, also accepts ‘amp’, ‘si12’, ‘si13’, ‘wic’, 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 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. (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 function, if None will use 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 arguements for rfunc. If None is specified, uses function defaults. If dict is specified, recasts as an array of this dict for all times. Array must be an array of dicts. (default=None)
-
dtime
¶ Numpy array of OCB datetimes (default=None)
Type: numpy.ndarray or NoneType
-
phi_cent
¶ Numpy array of floats that give the angle from AACGM midnight of the OCB pole in degrees (default=None)
Type: numpy.ndarray or NoneType
-
r_cent
¶ Numpy array of floats that give the AACGM co-latitude of the OCB pole in degrees (default=None)
Type: numpy.ndarray or NoneType
-
r
¶ Numpy array of floats that give the radius of the OCBoundary in degrees (default=None)
Type: numpy.ndarray or NoneType
-
x, y, j_mag, etc.
Numpy array of floats that hold the remaining values held in filename
Type: numpy.ndarray or NoneType
Raises: ValueError
– Incorrect or incompatible input-
get_aacgm_boundary_lat
(aacgm_mlt, rec_ind=None, overwrite=False, set_lon=True)[source]¶ Get the OCB latitude in AACGM coordinates at specified longitudes
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].
-
get_next_good_ocb_ind
(min_sectors=7, rcent_dev=8.0, max_r=23.0, min_r=10.0)[source]¶ Read in the next usuable OCB record from the data file.
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)
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
IMAGE FUV checks that: - more than 6 MLT boundary values have contributed to OCB circle - the OCB ‘pole’ is with 8 degrees of the AACGM pole - the OCB ‘radius’ is greater than 10 and less than 23 degrees AMPERE/DMSP-SSJ checks that: - the Figure of Merit is greater than or equal to the specified minimum
-
inst_defaults
()[source]¶ Get the information needed to load an OCB file using instrument specific formatting
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', 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 (dt.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)
-
normal_coord
(lat, lt, coords='magnetic', height=350.0, method='ALLOWTRACE')[source]¶ Converts 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')[source]¶ Converts 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()
-
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)[source]¶ Matches data records with OCB records, locating the closest values within a specified tolerance
Parameters: - ocb (ocbpy.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)
Returns: idat – Data index for match value, None if all of the data have been searched
Return type: int or NoneType
Notes
Updates OCBoundary.rec_ind for matched value. None if all of the boundaries have been searched.
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, aacgm_lat, aacgm_mlt, ocb_lat=nan, ocb_mlt=nan, r_corr=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 or array-like) – Data index (zero offset)
- ocb_ind (int or array-like) – OCBoundary record index matched to this data index (zero offset)
- aacgm_lat (float or array-like) – Vector AACGM latitude (degrees)
- aacgm_mlt (float or array-like) – Vector AACGM MLT (hours)
- 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)
- aacgm_n (float or array-like) – AACGM North pointing vector (positive towards North) (default=0.0)
- aacgm_e (float or array-like) – AACGM East pointing vector (completes right-handed coordinate system (default = 0.0)
- aacgm_z (float or array-like) – AACGM Vertical pointing vector (positive down) (default=0.0)
- aacgm_mag (float or array-like) – Vector magnitude (default=np.nan)
- 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)
-
pole_angle
¶ Angle at vector location appended by AACGM and OCB poles in degrees (default=np.nan)
Type: float or array-like
Notes
May only handle one data type, so scale_func cannot be an array
-
calc_ocb_polar_angle
()[source]¶ Calculate the OCB north azimuth angle
Returns: ocb_naz – Angle between measurement vector and OCB pole in degrees Return type: float or array-like Raises: ValueError
– If the required input is undefinedNotes
Requires ocb_quad, vec_quad, aacgm_naz, and pole_angle
-
calc_ocb_vec_sign
(north=False, east=False, quads={})[source]¶ Get the sign of the North and East components
Parameters: Returns: vsigns – Dictionary with keys ‘north’ and ‘east’ containing the desired signs
Return type: Raises: ValueError
– If the required input is undefinedNotes
Requires ocb_quad, vec_quad, aacgm_naz, and pole_angle
-
calc_vec_pole_angle
()[source]¶ Calculate the angle between the AACGM pole, a measurement, and the OCB pole using spherical triginometry
Raises: ValueError
– If the input is undefined or inappropriately sized arraysNotes
Requires aacgm_mlt, aacgm_lat, ocb_aacgm_mlt, and ocb_aacgm_lat. Updates pole_angle.
-
define_quadrants
()[source]¶ Find the MLT quadrants (in AACGM coordinates) 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, aacgm_mlt, and pole_angle. Updates ocb_quad and vec_quad
Raises: ValueError
– If the required input is undefined
-
scale_vector
()[source]¶ Normalise a variable proportional to the curl of the electric field.
Raises: ValueError
– If the required input is not definedNotes
Requires ocb_lat, ocb_mlt, ocb_aacgm_mlt, and pole_angle. Updates ocb_n, ocb_e, ocb_z, and ocb_mag
-
set_ocb
(ocb, scale_func=None)[source]¶ Set the OCBoundary values for provided data (updates all attributes)
Parameters: - ocb (ocbpy.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 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)[source]¶ Formula for 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)[source]¶ Normalise a variable proportional to the curl of the electric field
Parameters: 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)[source]¶ Normalise a variable proportional to the electric field
Parameters: 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].