API Reference¶

The class structure of this module is based on a parent-child approach. Each class in this list contains multiple children of the class below

absatday.absatday - top level class, one spacecraft-day of SSJ data
abpolarpass.abpolarpass - one half of a DMSP orbit, a crossing of N or S pole
absegment.absegent - a possible auroral zone, a single span of strong flux

Each successive class is a window to a subset of the parent class’s DMSP SSJ data. To keep accessing data simple and consistant across all of the classes, only the top-level class (absatday) stores and names data variables (time, spacecraft location, and fluxes) The child classes all slice their parent’s data as needed instead of storing it themselves.

This functionality is implemented with a custom __getitem__ method which can be used to fetch the data associated with a specific instance for any of the 3 classes.

Here is an example:

import os
from ssj_auroral_boundary import files
path,filename = files.test_cdf_path_and_filename()
cdffn = os.path.join(path,filename)

outdir = '/tmp'

from ssj_auroral_boundary.absatday import absatday

#Find boundaries
absd = absatday(cdffn,
                csvdir=outdir,
                imgdir=outdir,make_plot=False)

#Find a successful boundary identification
good_abpp = None
for abpp in absd.polarpasses:
    if abpp.failure_reason is None:
        good_abpp = abpp
        break

#Show how same interface accesses Magnetic Latitude
day_mlat = absd['mlat']
pass_mlat = good_abpp['mlat']
print(day_mlat.shape,pass_mlat.shape)

((86400,), (3050,))

Boundaries are represented as indicies into abpolarpass (see abpolarpass below). You can use this __getitem__ syntax combined with these index variables to get whatever data value (time,location,flux) you want from among the class properties in ssj_auroral_boundary.absatday.absatday.

For example following on the previous code snippet:

#Show how to get the boundaries from a successful abpolarpass
boundary_indicies = [good_abpp.idx_equator1,
                    good_abpp.idx_pole1,
                    good_abpp.idx_pole2,
                    good_abpp.idx_equator2]

for idx in boundary_indicies:
    btime = good_abpp['time'][idx] #datetime
    bmlat = good_abpp['mlat'][idx] #AACGM magnetic latitude
    bmlt = good_abpp['mlt'][idx] #AACGM magnetic local time
    print(btime.strftime('%c'),bmlat,bmlt)

('Sat May 29 02:58:07 2010', 65.541316005828321, 16.88996581629161)
('Sat May 29 03:00:16 2010', 70.908033561060606, 16.147218793047333)
('Sat May 29 03:08:38 2010', 72.781246453140852, 9.9421193209708267)
('Sat May 29 03:11:36 2010', 65.473878712612631, 8.7777971568744455)

class ssj_auroral_boundary.absatday.absatday(cdffile, imgdir=None, make_plot=True, plot_failed=False, csvdir=None, writecsv=True, csvvars=['mlat', 'mlt'])¶

Class for one satellite-day of SSJ data (one CDF file)

Implements __getitem__ interface to access any data marked with: (from CDF) below.

cdffn¶

Full file path to CDF file

Type:	str

satnum¶

DMSP number from CDF

Type:	int

log¶

Logger for this instance Expects a root logger with name ‘ssj_auroral_boundary’ in the calling function, otherwise won’t display anything

Type:	logging.logger

writecsv¶

Write out the CSV

Type:	bool

csv¶

Instance for adding lines to CSV

Type:	abcsv.abcsv

imgdir¶

Path to write image files to if make_plot is True or plot_failed is True (see constructor for defualt behavior and fallbacks)

Type:	str

make_plot¶

Plot successful passes

Type:	bool

plot_failed¶

Also plot unsuccessful passes

Type:	bool

cdf¶

Open CDF file

Type:	pycdf.CDF

time¶

Timestamp of SSJ data as datetimes (Universal Time)

Type:	np.ndarray, shape=(86400,1)

uts¶

Timestamp of SSJ data as Second of Day (Universal Time)

Type:	np.ndarray, shape=(86400,1)

hod¶

Timestamp of SSJ data as Hour of Day (Universal Time)

Type:	np.ndarray, shape=(86400,1)

mlat¶

Magnetic latitude AACGM (NOAA CDF v1.1.2) / Apex (CU internal SSJ CDF)

Type:	np.ndarray, shape=(86400,1)

mlt¶

Magnetic local time AACGM (NOAA CDF v1.1.2) / Apex (CU internal SSJ CDF)

Type:	np.ndarray, shape=(86400,1)

counts¶

Detector counts for all SSJ channels (from CDF)

Type:	np.ndarray, shape=(86400,19)

diff_flux¶

Differential electron energy energy flux (from CDF)

Type:	np.ndarray, shape=(86400,19)

diff_flux_std¶

Relative error in differential electron energy flux (from CDF)

Type:	np.ndarray, shape=(86400,19)

total_flux¶

Total energy flux intergrated across all 19 channels (from CDF)

Type:	np.ndarray, shape=(86400,1)

total_flux_std¶

Relative error in total electron energy flux (from CDF)

Type:	np.ndarray, shape=(86400,1)

channel_energies¶

Energy in electron volts (from CDF)

Type:	np.ndarray, shape=(19,)

xings¶

Indices into data arrays of equator crossings

Type:	list

polarpasses¶

List of abpolarpass.abpolarpass obj for each polar crossing (half orbit)

Type:	list

Constructor for absatday

Parameters:

cdffile (str) – DMSP SSJ CDF file (probably from NASA CDAWeb)
imgdir (str, optional) – Path to dump boundary identification images to (must exist) If None looks for environment variable DMSP_DIR_ABIMG
make_plot (bool, optional) – Plot of each successful identification (the default is True)
plot_failed (bool, optional) – Also plot unsuccesful passes (the default is False)
csvdir (str, optional) – Directory to dump CSV files to (must exist) If None looks for environment variable DMSP_DIR_ABCSV If still fails raises RuntimeError
writecsv (bool, optional) – Write a CSV file of boundary identifications (the default is True)
csvvars (list, optional) – List of optional variables to include in each line of the CSV file. See abcsv for more details. (default=[‘mlat’, ‘mlt’])

class ssj_auroral_boundary.abpolarpass.abpolarpass(satday, ind_pass_start, ind_pass_end)¶

A class for encapulating each spacecraft pass over the pole.

satday¶

Parent absatday object

Type:	absatday.absatday

failure_reason¶

Set to descriptive string of why boundary finding failed if it did fail, otherwise, it is None if boundary finding succeeded

Type:	str

FLUX_MIN¶

Threshold that integrated flux must exceed continously for a span of time to be defined as a auroral region candidate. For each such continous above-threshold region, an absegment.absegment instance is created.

Type:	float

hemi¶

Single letter (N or S) hemisphere code

Type:	str,

idx_pole_approach¶

Index (relative to the start of the pass data) at which the spacecraft was closest to the pole

Type:	int

idx_equator1¶

Index (relative to the start of the pass data) at which the spacecraft first encounted the equatorward edge of the aurora. Set to None if boundary idenficiation failed.

Type:	int

idx_pole1¶

Index (as above) at which the spacecraft first exited the auroral oval into the polar cap. None if boundary finding failed.

Type:	int

idx_pole2¶

Index (as above) at which the spacecraft exited the polar cap and entered the aurora again. None if boundary finding failed.

Type:	int

idx_equator2¶

Index (as above) where the spacecraft left the aurora, continuing on to subauroral latitudes. None if boundary finding failed.

Type:	int

max_fom¶

Figure of Merit for the boundary identification. None if boundary identification failed.

Type:	float

Notes

Handles finding the boundaries for a single pass.

Some attributes are not documented, this abbreviated list shows those most likely to be useful to a user not interested in modifying the code, i.e. someone who wants to integrated the code into thier own application and read boundaries directly from these objects instead of using output CSVs.

Implements __getitem__ interface to access any data marked with (from CDF) in absatday.absatday docstring. Slices data from parent absatday as idx_pass_start:idx_pass_end (see constructor docstring).

Constructor for abpolarpass

Parameters:	satday (ssj_auroral_boundary.absatday.absatday) – Parent absatday object ind_pass_start (int) – Index of polar pass start in SSJ CDF ind_pass_end (int) – Index of polar pass end in SSJ CDF