class spacepy.pybats.bats.MagFile(filename, ie_name=None, find_ie=False, *args, **kwargs)[source]

BATS-R-US magnetometer files are powerful tools for both research and operations. MagFile objects open, parse, and visualize such output.

The $delta B$ calculated by the SWMF requires two components: GM (BATSRUS) and IE (Ridley_serial). The data is spread across two files: GM_mag*.dat and IE_mag*.dat. The former contains $delta B$ caused by gap-region (i.e., inside the inner boundary) FACs and the changing global field. The latter contains the $delta B$ caused by Pederson and Hall currents in the ionosphere. MagFile objects can open one or both of these files at a time; when both are opened, the total $delta B$ is calculated and made available to the user.


>>> # Open up the GM magnetometer file only.
>>> obj = spacepy.pybats.bats.MagFile('GM_file.mag')
>>> # Open up both the GM and IE file [LEGACY SWMF ONLY]
>>> obj = spacepy.pybats.bats.MagFile('GM_file.mag', 'IE_file.mag')
>>> # Open up the GM magnetometer file; search for the IE file.
>>> obj = spacepy.pybats.bats.MagFile('GM_file.mag', find_ie=True)

Note that the find_ie kwarg uses a simple search assuming the data remain in a typical SWMF-output organizational tree (i.e., if the results of a simulation are in folder results, the GM magnetometer file can be found in results/GM/ or results/GM/IO2/ while the IE file can be found in results/IE/ or results/IE/ionosphere/). It will also search the present working directory. This method is not robust; the user must take care to ensure that the two files correspond to each other.