smindex

A tiny module for downloading and reading SuperMAG indices and substorm lists.

For the SuperMAG data visit https://supermag.jhuapl.edu/indices

If using any of these data products, please remember to cite the relevant SuperMAG papers and acknowledge SuperMAG (see here: https://supermag.jhuapl.edu/info/?page=rulesoftheroad)

Installation

Install this module using pip3:

pip3 install smindex --user

Or by cloning and building this repository:

git clone https://github.com/mattkjames7/smindex
cd smindex
python3 setup.py bdist_wheel
pip3 install dist/smindex-2.0.0-py3-none-any.whl --user

Then set up an environment variable which point to where you want to store the data in your ~/.bashrc file:

export SMINDEX_PATH="/path/to/smindex/data"

If this is not set, then the default path will be ~/.smindex.

Downloading and Reading SuperMAG Indices

SuperMAG indices are downloaded automatically when requested by the indices() function. For example, to get the SME index for January 2005:

import smindex

# a single day of data
data = smindex.indices(20240101)

# a range of dates
data = smindex.indices(20240101, 20240131)

# a range of dates and times as tuples
data = smindex.indices((20240101, 12.0), (20240102, 23.75))

# or using datetime objects
from datetime import datetime

start = datetime(2024,1,1,0,0,0)
end = datetime(2024,1,31,23,59,59)
data = smindex.indices(start, end)

Downloading and Reading Substorm Lists

Substorm lists (by Frey et al., 2004 and 2006; Liou 2010; Newell and Gjerloev, 2011; Forsyth et al., 2015; Ohtani and Gjerloev, 2020) can be downloaded using the download_substorms() function:

smindex.download_substorms()

To read in the substorms, use the substorms() function:

# read the whole database
data = smindex.substorms()

# read substorms in a date range
data = smindex.substorms(start_date=20220101, end_date=20221231)

# read substorms from a specific list
data = smindex.substorms(list_type='frey2004')

References

Frey, H. U., Mende, S. B., Angelopoulos, V., and Donovan, E. F. (2004), Substorm onset observations by IMAGE‐FUV, J. Geophys. Res., 109, A10304, doi:10.1029/2004JA010607.

Frey, H.U. and Mende, S.B., 2006, March. Substorm onsets as observed by IMAGE-FUV. In Proceedings of the 8th International Conference on Substorms (pp. 71-76). Calgary, Alberta, Canada: Univ. of Calgary.

Forsyth, C., Rae, I. J., Coxon, J. C., Freeman, M. P., Jackman, C. M., Gjerloev, J., and Fazakerley, A. N. ( 2015), A new technique for determining Substorm Onsets and Phases from Indices of the Electrojet (SOPHIE), J. Geophys. Res. Space Physics, 120, 10,592– 10,606, doi:10.1002/2015JA021343.

Gjerloev, J. W. (2012), The SuperMAG data processing technique, J. Geophys. Res., 117, A09213, doi:10.1029/2012JA017683.

Gjerloev, J. W., R. A. Hoffman, S. Ohtani, J. Weygand, and R. Barnes, Response of the Auroral Electrojet Indices to Abrupt Southward IMF Turnings (2010), Annales Geophysicae, 28, 1167-1182.

Liou, K. (2010), Polar Ultraviolet Imager observation of auroral breakup, J. Geophys. Res., 115, A12219, doi:10.1029/2010JA015578.

Newell, P. T., and J. W. Gjerloev (2011), Evaluation of SuperMAG auroral electrojet indices as indicators of substorms and auroral power, J. Geophys. Res., 116, A12211, doi:10.1029/2011JA016779.

Newell, P. T., and J. W. Gjerloev (2011), Substorm and magnetosphere characteristic scales inferred from the SuperMAG auroral electrojet indices, J. Geophys. Res., 116, A12232, doi:10.1029/2011JA016936.

Newell, P. T. and J. W. Gjerloev (2012), SuperMAG-Based Partial Ring Current Indices, J. Geophys. Res., 117, doi:10.1029/2012JA017586.

Ohtani, S., and J. Gjerloev, Is the Substorm Current Wedge an Ensemble of Wedgelets?: Revisit to Midlatitude Positive Bays, accepted, J. Geophys. Res, 2020.