Boundary Data Sets

Poleward (OCB) and Equatorward Auroral Boundaries (EABs) must be obtained from observations or a model for this coordinate transformation. The standard OCB and EAB data sets can be found in ocbpy/boundaries, though this location may also found using ocbpy.boundaries.files.get_boundary_directory(). Currently, three different boundary data set types are available. Not all data sets include the locations of the EAB. Routines to retrieve boundary filenames from specific instruments, time periods, hemispheres, and boundary types are provided in the ocbpy.boundaries.files sub-module.

IMAGE

Data from three auroral instruments provide northern hemisphere poleward auroral boundary (PAB) and EAB locations for 3 May 2000 02:41:43 UT - 31 Oct 2002 20:05:16, though not all of the times included in these files contain high-quality estimations of the boundary locations. Recommended selection criteria are included as defaults in the OCBoundary class. There are also boundary files that combine the information from all instruments to obtain the OCB and EAB. These combined files are the default boundaries for the IMAGE time period. You can read more about the OCB determination, EAB determination, this selection criteria, and the three auroral instruments (IMAGE Wideband Imaging Camera (WIC) and FUV Spectrographic Imagers SI12 and SI13) in the articles listed in IMAGE FUV Boundaries.

The most recent corrects for each instrument that add the DMSP particle precipitation corrections to the PAB and EAB locations are included in ocbpy.ocb_correction. These corrections should be applied to the data used to obtain the circle fits included in the instrument files, not the circle fits themselves. These data sets may be obtained from the British Antarctic Survey.

AMPERE

OCB data sets can also be obtained from AMPERE (Active Magnetosphere and Planetary Electrodynamics Response Experiment) R1/R2 Field-Aligned Current (FAC) boundary data. This data is provided for both hemispheres between 2010-2021, inclusive. Because there is an offset between the R1/R2 FAC boundary and the OCB, a correction is required. This correction can be implemented using the routines in ocbpy.ocb_correction.

In the most recent version (V2) of these AMPERE boundary fits, which uses the newly-processed AMPERE data, a fit for the Heppner-Maynard Boundary (HMB) were also made available. The HMB has been shown to be related to the equatorward boundary of the auroral oval near magnetic midnight, and so is provided as an EAB. This may or may not be an appropriate boundary for your auroral gridding purposes. As the HMB has not been related to the equatorward particle precipitation boundary, there is no correction function needed.

More information about the method behind the identification of these boundaries and their offset can be found in the articles listed in AMPERE Boundaries. Recommended selection criteria are included as defaults in the OCBoundary and EABoundary classes. We gratefully acknowledge the use of AMPERE data provided by JHU/APL, PIs Brian Anderson / Sarah Vines. This analysis uses the newly-processed AMPERE data.

DMSP SSJ

DMSP particle precipitation instruments make it possible to identify the poleward and equatorward boundaries of the auroral oval along the satellite orbit. Details about this identification process can be found in the references listed in DMSP SSJ Boundaries. Routines to download and proceess the DMSP boundary files are provided in the ocbpy.boundaries.dmsp_ssj_files sub-module.

Boundaries Module

Boundary file utilities.

Boundary Files

Functions that support boundary file selection.

ocbpy.boundaries.files.get_boundary_directory()

Get the OCBpy boundary directory.

Returns:

boundary_dir – Directory holding the boundary files included in OCBpy

Return type:

str

ocbpy.boundaries.files.get_boundary_files(bound='ocb')

Get boundary filenames and their spatiotemporal ranges.

Parameters:

bound (str) – String specifying which boundary is desired (OCB or EAB) (default=’ocb’)

Returns:

boundary_files – Dict with keys of boundary files containing dicts specifying the hemisphere, instrument, file start time, and file end time

Return type:

dict

Notes

IMAGE instruments may be separated into WIC, SI12, and SI13. If IMAGE is desired, the combined file will be used.

Unknown instruments should have filenames of the format, instrument_hemisphere_%Y%m%d_%Y%m%d.boundary

ocbpy.boundaries.files.get_default_file(stime, etime, hemisphere, instrument='', bound='ocb')

Get the default file for a specified time and hemisphere.

Parameters:

• stime (dt.datetime or NoneType) – Starting time for which the file is desired; if None, will prioritize IMAGE data for the northern and AMERE data for the southern hemisphere

• etime (dt.datetime or NoneType) – Ending time for which the file is desired; if None, will prioritize IMAGE data for the northern and AMPERE data for the southern hemisphere

• hemisphere (int) – Hemisphere for which the file is desired (1=north, -1=south)

• instrument (str) – Instrument that provides the data. This will override the starting and ending times. Accepts ‘ampere’, ‘amp’, ‘image’, ‘si12’, ‘si13’, ‘wic’, ‘dmsp-ssj’, and ‘’ (to accept instrument defaults based on time range). Will also accept the instrument name for any instrument whose boundary file follows the naming convention INST_HEMI_YYYYMMDD_YYYYMMDD_*.BBB, where: INST = instrument name HEMI = north or south YYYYMMDD = starting and ending year, month, day BBB = ocb or eab (default=’’)

• bound (str) – String specifying which boundary is desired (OCB or EAB) (default=’ocb’)

Returns:

• default_file (str or NoneType) – Default filename with full path defined or None if no file was available for the specified input constraints

• instrument (str) – Instrument for the default file (either ‘ampere’, ‘image’, or ‘dmsp-ssj’)

DMSP SSJ Files

Download and format DMSP SSJ boundary files.

References

[2] (1,2)

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

[5]

Kilcommons, L.M., et al. (2017), A new DMSP magnetometer and auroral boundary data set and estimates of field-aligned currents in dynamic auroral boundary coordinates, J. Geophys. Res.: Space Phys., 122, pp 9068-9079, doi:10.1002/2016ja023342.

[7] (1,2)

Kilcommons, L., Redmon, R., & Knipp, D. (2019). Defense Meteorology Satellite Program (DMSP) Electron Precipitation (SSJ) Auroral Boundaries, 2010-2014 (1.0.0) [Data set]. Zenodo. https://doi.org/10.5281/zenodo.3373812

ocbpy.boundaries.dmsp_ssj_files.evaluate_dmsp_boundary_file(fname, stime, etime, sat_nums)

Evaluate a boundary file name for time range and satellite ID.

Parameters:

• fname (str) – Filename with the format: dmsp-fII_ssj_precipitating-electrons-ions_YYYYMMDD_vXXX_boundaries.csv where II is the satellite ID, YYYY is the year, MM is the month, DD is the day of month, and XXX is the version number.

• stime (dt.datetime or NoneType) – Start time or None to get all boundaries

• etime (dt.datetime or NoneType) – End time or None to get all boundaries

• sat_nums (list) – Desired satellite ID numbers

Returns:

good_file – True if the satellite has the desired ID and time, False otherwise

Return type:

bool

ocbpy.boundaries.dmsp_ssj_files.fetch_format_ssj_boundary_files(stime, etime, out_dir=None, rm_temp=True, ref_alt=830.0, method='GEOCENTRIC|ALLOWTRACE')

Download DMSP SSJ data and create boundary files for each hemisphere.

Parameters:

• stime (dt.datetime or NoneType) – Start time or NoneType to fetch all

• etime (dt.datetime) – End time or NoneType to fetch all

• out_dir (str or NoneType) – Output directory or None to download to ocbpy boundary directory (default=None)

• rm_temp (bool) – Remove all files that are not the final boundary files (default=True)

• ref_alt (float) – Reference altitude for boundary locations in km (default=830.0)

• method (str) – AACGMV2 method, may use ‘TRACE’, ‘ALLOWTRACE’, ‘BADIDEA’, ‘GEOCENTRIC’ [2] (default=’GEOCENTRIC|ALLOWTRACE’)

Returns:

bound_files – List of the boundary file names

Return type:

list

Raises:

ValueError – If the DMSP SSJ files could not be downloaded

See also

aacgmv2, requests.exceptions.ProxyError

ocbpy.boundaries.dmsp_ssj_files.fetch_ssj_boundary_files(stime=None, etime=None, out_dir=None, sat_nums=None, doi='10.5281/zenodo.3373811', rm_temp=True)

Download DMSP SSJ files and place them in a specified directory.

Parameters:

• stime (dt.datetime or NoneType) – Start time or None to get all boundaries (default=None)

• etime (dt.datetime or NoneType) – End time or None to get all boundaries (default=None)

• out_dir (str or NoneType) – Output directory or None to download to ocbpy boundary directory (default=None)

• sat_nums (list or NoneType) – Satellite numbers or None for all satellites (default=None)

• doi (str) – DOI for the DMSP SSJ boundary file Zenodo archive [7] (default=’10.5281/zenodo.3373811’)

• rm_temp (bool) – Remove all files that are not the final boundary files (default=True)

Returns:

out_files – List of filenames corresponding to downloaded boundary files

Return type:

list

Raises:

• ValueError – If an unknown satellite ID, DOI, or output directory is provided.

• IOError – If unable to donwload the target archive and identify the zip file

• ImportError – If called and zenodo_get is not available

Notes

If a file already exists, the routine will add the file to the output list without downloading it again.

ocbpy.boundaries.dmsp_ssj_files.format_ssj_boundary_files(csv_files, ref_alt=830.0, method='GEOCENTRIC|ALLOWTRACE')

Create SSJ boundary files for a list of DMSP SSJ daily satellite files.

Parameters:

• csv_files (list) – List of SSJ CSV boundary files with directory structure

• ref_alt (float) – Reference altitude for boundary locations in km (default=830.0)

• method (str) – AACGMV2 method, may use ‘TRACE’, ‘ALLOWTRACE’, ‘BADIDEA’, ‘GEOCENTRIC’ [2] (default=’GEOCENTRIC|ALLOWTRACE’)

Returns:

bound_files – List of successfully updated .csv boundary files

Return type:

list

Notes

Output format is ‘sc date time r x y fom x_1 y_1 x_2 y_2’ where:

sc	Spacecraft number
date	YYYY-MM-DD
time	HH:MM:SS of midpoint between the two measurements for this pass
r	Half the distance between the two pass boundaries
x	Distance between the midpoint of the two pass boundaries and the AACGMV2 pole in degrees along the dusk-dawn meridian
y	distance between the midpoint of the two pass boundaries and the AACGMV2 pole in degrees along the midnight-noon meridian
fom	FOM for the boundaries found along this pass
x_1	x coordinate of the first boundary
y_1	y coordinate of the first boundary
x_2	x coordinate of the second boundary
y_2	y coordinate of the second boundary

Because two points are not enough to define the OCB or EAB across all local times, a circle that intersects the two boundary pass points is defined and the boundary location saved. The DMSP SSJ boundary correction function will use this information to only return values within a small distance of the boundary locations [5], [7].

Separate files are created for each boundary and hemisphere, dates and spacecraft are combined.

See also

aacgmv2