Updates

Version 2.0.0 has just been released. Major update is compatibility with Pandas >=2.0.2 and cdflib >=1.0.4!

Overview

This code provides the utility to download and load data from various ground-based magnetometer arrays into a Pandas DataFrame. The code also return metadata for the loaded stations. The code is divided into a seperate module for each array. These are the carisma, canopus, image, and themis modules.

The carisma module loads data from the CARISMA magnetometer array.

The canopus module loads data from the legacy CANOPUS magnetometer array pre 1 April 2005. The data must be downloaded from the CARISMA website and cannot be downloaded using the module.

The image modules loads data from the IMAGE magnetometer array.

The themis modules loads data from the THEMIS EPO and GBO, CARISMA, CANMOS, AUTUMN and AUTUMN X, DTU, IMAGE, GIMA, MACCS, McMAC, USGS, and PENGUIN arrays. When loading data from the themis module be sure to properly acknowledge each individual array used.

Arrays

Additonal information on the arrays supported by gmag.

Stations

Table and map of stations for each array.

Installation

Download or fork the repository. Replace the example configuration file gmagrc_example with gmagrc and fill in the variable data_dir with the directory you would like all files downloaded then CD to the local GMAG directory and install via:

pip install -e .

gmagrc

The gmagrc file defines the local directory where magnetoemter data is downloaded and the web address where data is stored for each array. If the addreses change they can be updated here.

• CARISMA files
  • local_dir\CARISMA\YYYY\MM\DD\station.file
• CANOPUS files
  • local_dir\CANOPUS\YYYY\MM\DD\station.file
• IMAGE files
  • local_dir\IMAGE\YYYY\MM\array_day.file
• THEMIS files
  • local_dir\THEMIS\site\YYYY\station.file

The carisma and themis modules download a daily file for each station. The image module downloads a single file including data from multiple stations each day.

Station Parameters

The names of stations, 4 letter codes, home array, geographic and geomagnetic coordinates, L-shell, and declinations are stored in yearly coordinate files and can be loaded with the utlis module. These files and the declinations are used to rotate CARISMA and IMAGE date from geographic (XYZ) to geomagnetic coordinates (HDZ, or heZ). This is done using:

H = X cos(dec) + Y sin(dec)

D = Y cos(dec) - H sin(dec)

Data loaded using the themis module is not rotated as the data is generally already in geomagnetic coordinates. Details on the processing of the ground-based magnetometer data from THEMIS can be found here.

The util module will load station coordinates from text files in ./gmag/Stations/

from gmag import utils
#load geomagnetic data
#load all CARISMA station data for 2002
car_stn = utils.load_station_coor(
  param='CARISMA',col='array',year=2002)

#load GILL data from 2012
gill_stn = utils.load_station_coor(
  param='GILL',col='code',year=2012)

#load all data from 2012
all_stn = utils.load_station_coor(param='ALL',year=2012)

#load station geographic data
#load all CARISMA data
geo_stn = utils.load_station_geo(param='CARISMA',col='array')

#load all stations
all_stn = utils.load_station_geo(param='ALL')

The yearly coordinate files are generated using Convert_coords.ipynb which requires the IGRF and aacgmv2 modules which can be difficult to install. For simplicity, the coordinate files are pre-generated and will updated when possible.

Loading Data

The load routines in each of the modules will load (rotate if necessary) and download files. Some examples can be found in notebooks folder. Simple examples are below. The load routines are similar for each array and load data into Pandas DataFrames.

#load CARISMA
import gmag.arrays.carisma as carisma
df, meta = carisma.load(['ISLL','PINA'],'2012-01-01',ndays=2)
df, meta = carisma.load(['ISLL','PINA'],
                  '2012-01-01',edate='2012-01-03')

#load IMAGE
import gmag.arrays.image as image
df, meta = image.load('AND','2012-01-01',ndays=21)

#load THEMIS, force download even if file exists
import gmag.arrays.themis as themis
df, meta = themis.load('KUUJ',sdate='2012-01-01',
                  ndays=22, dl=True,force=True)

#load CANOPUS
import gmag.arrays.canopus as canopus
df, meta = canopus.load('ISLL',sdate='2001-01-01',ndays=1)