Visualization tool for three-dimensional plasma velocity distributions (ISEE_3D) as a plug-in for SPEDAS

This paper introduces ISEE_3D, an interactive visualization tool for three-dimensional plasma velocity distribution functions, developed by the Institute for Space-Earth Environmental Research, Nagoya University, Japan. The tool provides a variety of methods to visualize the distribution function of space plasma: scatter, volume, and isosurface modes. The tool also has a wide range of functions, such as displaying magnetic field vectors and two-dimensional slices of distributions to facilitate extensive analysis. The coordinate transformation to the magnetic field coordinates is also implemented in the tool. The source codes of the tool are written as scripts of a widely used data analysis software language, Interactive Data Language, which has been widespread in the field of space physics and solar physics. The current version of the tool can be used for data files of the plasma distribution function from the Geotail satellite mission, which are publicly accessible through the Data Archives and Transmission System of the Institute of Space and Astronautical Science (ISAS)/Japan Aerospace Exploration Agency (JAXA). The tool is also available in the Space Physics Environment Data Analysis Software to visualize plasma data from the Magnetospheric Multiscale and the Time History of Events and Macroscale Interactions during Substorms missions. The tool is planned to be applied to data from other missions, such as Arase (ERG) and Van Allen Probes after replacing or adding data loading plug-ins. This visualization tool helps scientists understand the dynamics of space plasma better, particularly in the regions where the magnetohydrodynamic approximation is not valid, for example, the Earth’s inner magnetosphere, magnetopause, bow shock, and plasma sheet.

Interplanetary space is filled with the solar wind, which is plasma originating from the Sun. Planetary magnetospheres are filled with plasma originating not only from the Sun but also from the planet itself and/or from its moon(s), which are primarily produced by ionization of the atmosphere of the planet or moon by ultraviolet and X-ray emissions. The plasma in near-Earth space is the most accessible and thus has been measured in situ by sounding rockets and spacecraft since the mid-twentieth century. The basic characteristics of space plasma, such as density and temperature, are derived as the velocity moments of the distribution in three-dimensional (3D) velocity space (e.g., Baumjohann and Treumann 1997).

Plasma velocity distributions provide more detailed information on space plasma than plasma moments. It is well known that sometimes space plasma deviates from the thermal equilibrium distribution such as the isotropic Maxwellian distribution. Examples are beam plasma population moving through another population (e.g., Mukai et al. 1994a; Oka et al. 2005); power law distribution (e.g., Gosling et al. 1989); bi-Maxwellian distribution with a stable plasma population, perpendicular to the ambient magnetic field, with another population parallel with the field (e.g., Anderson et al. 1992); ring distribution, with plasma dominant in the direction quasi-perpendicular to the ambient magnetic field, with a narrow energy range (e.g., Ejiri et al. 1980; Saito et al. 1994; Chen et al. 2011); and nongyrotropic distribution (e.g., Nagai et al. 2011; Ng et al. 2012; Burch et al. 2016). Three-dimensional visualization is useful for these distributions, because it helps scientists decide which two-dimensional slice displays properly the important characteristics of a plasma distribution with a structure that is too complicated to be visualized entirely. Another advantage is the ability to visualize the entire structure both in the rest frame [e.g., geocentric solar magnetic (GSM) coordinates] and in the magnetic field coordinates, instantaneously. In the Earth’s inner magnetosphere, where the gradient and curvature drifts are not negligible compared to the E × B drift, where E and B are the electric and magnetic fields, respectively, the motion of particles depends on the kinetic energy of the particles and sometimes on gyrophases (Roederer 1970; Ebihara and Miyoshi 2011). Thus, the plasma dynamics cannot be fully described by magnetohydrodynamic (MHD) components (plasma velocity moments). Therefore, visualization of 3D velocity distributions is helpful and in most cases essential to obtain information on space plasma dynamics from observational data. Particularly, the detailed evolution of the entire velocity distribution has to be seen in order to capture, study, and better understand non-MHD dynamics in detail.

We have developed a visualization tool for plasma 3D distributions, which is intended to be user-friendly, independent of computer operating systems, and easily extendable by researchers or engineers to process plasma data obtained from a variety of completed, ongoing, or future missions. The source codes are written in Interactive Data Language (IDL) (offered by Harris Geospatial Solutions; http://www.harrisgeospatial.com/SoftwareTechnology/IDL.aspx), which is a data analysis programming language widely used in the field of space physics and solar physics. IDL has been used to develop the data analysis framework, Space Physics Environment Data Analysis Software (SPEDAS) (http://spedas.org/), developed by the team of the Time History of Events and Macroscale Interactions during Substorms (THEMIS) mission (Angelopoulos 2009). SPEDAS has been extended to other projects for the application in the whole scientific community by the implementation of mission-specific program codes as plug-in tools. The Exploration of energization and Radiation in Geospace (ERG) project, including the Arase (ERG) spacecraft (Miyoshi et al. 2012; Miyoshi et al. this issue), which was successfully launched on December 20, 2016, also uses SPEDAS as the main analysis software to facilitate its own data analysis, as well as collaborative studies by other projects. In the following sections, we present the details of the visualization tool that we have developed.

The source codes of the tool are object-oriented, written as IDL scripts. They can be accessible by the public in the “bleeding edge” build of SPEDAS, specifically in the “spedas_gui” subdirectory, in the SPEDAS main “idl” directory. The tool accepts ASCII files as input data in the format of Geotail low-energy particle (LEP) experiment data, available from the Data Archives and Transmission System (DARTS) of the Institute of Space and Astronautical Science (ISAS)/Japan Aerospace Exploration Agency (JAXA) (https://www.darts.isas.jaxa.jp/stp/geotail/ascii_format_lep_psd.html). It is also capable of loading data stored in an IDL hash, where the THEMIS and Magnetospheric Multiscale (MMS) data stored in Common Data Format (CDF) files are reformatted by SPEDAS (see “Application to other mission data” section for details).

The tool provides three view modes to visualize 3D velocity distributions: scatter mode, volume mode, and isosurface mode, which are presented in the next section. This section briefly explains the functions of the 3D velocity distribution data for the volume and isosurface modes and coordinate transformation.

In the volume mode, the tool first constructs convex hulls using the Quickhull method (Barber et al. 1996), executed by the IDL standard function, qhull.pro. Then, the tool uses the IDL standard function, qgrid3.pro, to create the volume data. The function linearly interpolates data over the velocity space to generate the volume data of a regular grid.

In the isosurface mode, the tool uses the interval_volume procedure to generate an isosurface mesh from the 3D distribution data. Then, it uses the tetra_surface procedure to extract the exterior surface of the mesh.

The tool can display velocity distributions in two different coordinate systems: spacecraft (S/C) and ambient magnetic field (MAG) coordinates. A set of original codes is implemented for the transformation between the coordinates. The MAG coordinates are defined such that the Z-axis is parallel with the magnetic field (B). The Y-axis is defined to be perpendicular to both B and the bulk velocity vector (V), in the direction of B × V. The X-axis completes the right-handed orthogonal set (= (B × V) × B).

The tool also can visualize the X–Y, Y–Z, and Z–X slices of 3D velocity distributions, on which the contours of the raw data count or the phase space density can be drawn. The tool uses the standard IDL command, contour.pro.

This section gives details of the visualization and function of the interactive tool by demonstrating a previously published event of nongyrotropic velocity distribution (Ieda et al. 2003).

Figure 1 shows magnetic field and plasma data from the magnetic field (MGF) experiment (Kokubun et al. 1994) and the LEP experiment (Mukai et al. 1994b) on board the Geotail spacecraft (Nishida 1994) for a period of 1330–1400 UT on December 12, 1997. Geotail observed a fast, earthward plasma flow at 1345–1353 UT, when it approached the current sheet, as shown by a decrease in the total magnetic field (top panel) close to zero. The energy–time spectrograms of electrons and ions (bottom two panels) show significant changes in energy spectra, compared to the intervals when Geotail was away from the current sheet (before 1345 UT and after 1353 UT). The ion velocity distributions were not gyrotropic during the 1345–1353 UT interval. In the following, we show the capabilities of our visualization tool, using the ion data for the interval, specifically at 1348:00 UT.

Example of magnetic field and particle data taken from the Geotail mission

Full size image

When the tool is run by users, it automatically loads data or a pop-up window requests them to choose a data file. Next, the main window opens, as shown in Fig. 2. It allows users to choose a time interval of interest and a variety of visualization modes, initial settings, and options in the setting part (i.e., left part of the main window). The visualization part (i.e., the right part) displays a velocity distribution in velocity space for the designated time interval. Users can rotate the distribution toward any viewing direction by using the mouse. Three independent arrows can be drawn: the magnetic field direction, the bulk velocity vector, and a user-defined vector. All the vectors are centered at [X, Y, Z] = [0, 0, 0]. Using the slider below the box for determining the time interval, users can forward or backward the plot interval by a step defined in the “Step” box. The window displays data averaged over the number of spins of a spacecraft defined in the “Spin sum” box.

Main window of the tool. The selected 3D distribution data are shown in the scatter mode

Full size image

The scatter mode displays color-coded physical quantities (particle count or phase space density) at each data point of observations, as shown in Fig. 2. The 3D distribution data are provided in a spherical coordinate system in most of the plasma observations. The scatter mode shows small cubes at the data points in the spherical coordinates with colors representing the data values (i.e., physical quantities). The range of the physical quantity to be displayed can be changed on the “Scatter” tab, as shown in Fig. 3. This mode with the feature of limiting the range helps scientists to see how the original data are distributed in the velocity space, before any interpolation and/or gridding is made.

Example of the scatter mode, together with the magnetic field and velocity vectors

Full size image

Figure 4a, b shows examples of the volume mode and the isosurface mode, respectively. The isosurface mode provides two layers, “Isosurface1” and “Isosurface2,” both of which can be independently defined. On the “Isosurface” tab, the range (minimum and maximum), color, and the type of visualization (solid or mesh) of each surface layer can be changed. The mesh option allows the view of a surface inside the other surface, as illustrated in Fig. 4b. The three modes can be chosen simultaneously by clicking the checkboxes on the top left. Figure 4c shows a combination of the scatter and isosurface modes. This helps scientists understand, for example, how widely or narrowly the high value of a physical quantity is distributed, and the exact location in velocity space where the particle data are actually obtained.

a Example of the volume mode. b Example of the isosurface mode. Two isosurfaces are drawn in different colors, at data values selected in the bottom left tab. c Example of a combination of the scatter and isosurface modes, along with the magnetic field and velocity vectors

Full size image

A two-dimensional (2D) slice of velocity distributions at a specific particle velocity or kinetic energy is one of the most widely used and helpful visualization methods. The tool, with settings in “Slice” tab, enables the display of a distribution slice of any level of the X–Y, Y–Z, or X–Z plane at any visualization mode or even with no modes selected, as shown in Fig. 5a. Vectors can also be displayed, depending on on/off settings of the vector in the “Vector” tab. With the “Contour” on/off checkbox in the “Slice” tab, contours can be added on the slice. Two or three slices can be displayed simultaneously, as shown in Fig. 5b. Figure 5c shows an example of a combination of two slices and the volume mode from a different viewpoint. The “Reset view” button on the “View” tab can reset the view direction to the default view. Clicking the XY-, XZ-, or YZ-plane buttons enables the jump to the viewpoint facing the selected plane at a right angle.

a Example of the X–Y slice of the distribution data. b Example of the X–Y and X–Z slices shown together. c X–Y slice from a different view angle, together with an isosurface and the magnetic field and velocity vectors

Full size image

The tool also provides another function for the 2D slices. A right click on the visualization part allows users to open a new pop-up window, which displays a 2D distribution (X–Y, Y–Z, or X–Z slice) on the left, along with two one-dimensional (1D) distribution cuts on the right. Figure 6 shows a snapshot of a new window, which provides an interactive interface for visualizing the two slices. With the mouse pointer, users can choose between the two axes on the 2D slice, along which the 1D cuts are drawn.

Pop-up window of the interactive tool for a 2D slice (X–Y plane in this case) and a snapshot of two 1D slices at the values indicated by the two red lines drawn on the 2D slice

Full size image

Figures 7 and 8 show examples of the visualization of the 3D distributions observed by the MMS mission (Burch et al. 2015). Figure 7 shows, from top to bottom, an energy–time spectrogram of ions with energies of 10 eV to 30 keV, the three components and the magnitude of the magnetic field, and the three components of the ion bulk velocity. The ions and the magnetic field were observed by the fast plasma investigation (FPI) instrument (Pollock et al. 2016) and by the fluxgate magnetometer (FGM) (Russell et al. 2016), respectively. Figure 8 shows the 3D ion distribution in the scatter mode (left) and the 2D slices of the distribution (right) for 02:13:19.916 UT taken on November 18, 2015. The distribution is visualized in the unit of phase space density (PSD) in MAG coordinates, with the magnetic field and velocity vectors represented by cyan and yellow arrows, respectively. In the slices, two distinct ion populations can be clearly seen: one with a phase space density peak close to the center of the distribution and the other moving mainly in magnetic field-aligned directions (+ Z-directions).

Ion and magnetic field observations by the MMS1 spacecraft on November 18, 2015, near the dayside magnetopause. (Top) Energy–time spectrogram of the omnidirectional ion flux from the FPI instrument, (middle) three components in GSE coordinates and the magnitude of the magnetic field from the FGM instrument, and (bottom) three components of the ion velocity in GSE coordinates from the FPI instrument. The vertical dashed line indicates the time interval for which the 3D ion velocity distribution is shown in Fig. 8

Full size image

Examples of a the scatter mode and b the 2D slice plot for ion velocity distributions (phase space density vs. velocity) in magnetic field coordinates observed by MMS1/FPI. Cyan and yellow arrows represent the directions of the magnetic field and the velocity vector, respectively. The spacecraft was crossing the dayside magnetopause at this time period, as shown in Fig. 7

Full size image

Figures 9 and 10 show examples of the visualization of the 3D distributions observed by the hot plasma composition analyzer (HPCA) (Young et al. 2016) on board MMS. Figure 9 shows, from top to bottom, an energy–time spectrogram of protons with energies below 40 keV, the three components and the magnitude of the magnetic field (from FGM), and the three components of the ion bulk velocity. Figure 10 shows the 3D ion distribution in the volume mode (left) and the 2D slices of the distribution (right) for 13:70:51 UT taken on October 16, 2015. The distribution is visualized in the unit of phase space density in MAG coordinates with the magnetic field and velocity vectors represented by cyan and yellow arrows, respectively. In both volume and slice modes, a nongyrotropic distribution can be clearly seen in the Vx > 0 velocity space.

Proton and magnetic field observations by the MMS1 spacecraft on October 16, 2015, near the dayside magnetopause. (Top) Energy–time spectrogram of the omnidirectional ion flux from the HPCA instrument, (middle) three components in GSM coordinates and the magnitude of the magnetic field from the FGM instrument, and (bottom) three components of the proton velocity in GSM coordinates from the HPCA instrument. The vertical dashed line indicates the time interval for which the 3D proton velocity distribution is shown in Fig. 10

Full size image

Examples of a the volume mode and b 2D slice plot for the proton velocity distributions (phase space density vs. velocity) in magnetic field coordinates observed by MMS1/HPCA. Cyan and yellow arrows represent the directions of the magnetic field and the velocity vector, respectively. The spacecraft was close to the dayside magnetopause during this time period, as shown in Fig. 8

Full size image

Example codes for the application to MMS data are available in mms_isee_3d_crib.pro and mms_isee_3d_crib_basic.pro in the subdirectory, “projects/mms/examples/advanced,” under the SPEDAS main “idl” directory. The SPEDAS routine, spd_dist_to_hash.pro, converts ion and electron data from FPI and HPCA from an idl structure to an idl hash. Regular “tplot” variables for the magnetic field and bulk velocity vectors are used as inputs of the tool. Only these three variables (one hash and two “tplot” variables) are required to load and visualize plasma data from other missions in ISEE_3D.

We have developed a visualization tool for 3D plasma velocity distributions, named ISEE_3D. The aim of the development is to provide a tool for the scientific community as a plug-in for SPEDAS, which is user-friendly, independent of computer operating systems, and can be easily extended to accept plasma data from different spacecraft missions. Currently, the visualization tool can be used for plasma data from Geotail/LEP, MMS, and THEMIS. The tool provides three different modes to visualize data to help researchers analyze velocity distributions more easily and extensively. The tool enables the view of 2D slices of the distributions and contours on the slice(s) for further analysis. The tool also displays, in the same window, important information about space plasma, such as the direction of the magnetic field and velocity vectors. The transformation between spacecraft and magnetic field coordinate systems is implemented in the tool. We plan to extend the tool to plasma data from the Arase (ERG) mission (Miyoshi et al. 2012; Miyoshi et al. this issue) and the Van Allen Probes mission (Mauk et al. 2012) after replacing or adding the data loading plug-ins (i.e., an alternative of spd_dist_to_hash.pro for MMS data), and we expect that the tools can be also used for other satellite missions.

1D:

one-dimensional

2D:

two-dimensional

3D:

three-dimensional

DARTS:

Data Archives and Transmission System

ERG:

Exploration of energization and Radiation in Geospace

FGM:

fluxgate magnetometer

FPI:

fast plasma investigation

HPCA:

hot plasma composition analyzer

IDL:

Interactive Data Language

ISAS:

Institute of Space and Astronautical Science

JAXA:

Japan Aerospace Exploration Agency

LEP:

low-energy particle

MHD:

magnetohydrodynamics

MMS:

magnetospheric multiscale

SPEDAS:

Space Physics Environment Data Analysis Software

THEMIS:

Time History of Events and Macroscale Interactions during Substorms

KK led the development of ISEE_3D and the collaborations between the teams. YM and SM proposed the idea of an interactive visualization tool and its plug-in function to SPEDAS. AI and KS provided data and plots for the Geotail event of nongyrotropic velocity distributions on December 12, 1997. TH, YM, and MS collaborated with KK in the development and improvement of the tool. VA, JWL, and AF contributed in the application of tool to MMS data. All authors read and approved the final manuscript.

Acknowledgements

We thank M. Oka and H. Hasegawa for their helpful, valuable comments and suggestions on the improvement of the visualization tool. This work was carried out at the ERG (Arase) Science Center (ERG-SC) operated by ISAS/JAXA and ISEE/Nagoya University and was supported by the GEMSIS Project, Institute for Space-Earth Environmental Research, Nagoya University, Japan. This study was supported by the Grants-in-Aid for Scientific Research (15H05815) of the Japan Society for the Promotion of Science (JSPS). This work was also supported by the JSPS program for Advancing Strategic International Networks to Accelerate the Circulation of Talented Researchers under Grant G2602. Parts of the works by K. Keika, Y. Miyoshi, T. Hori, Y. Miyashita, and M. Shoji were done at the ERG-SC.

Competing interests

The authors declare that they have no competing interests.

Publisher’s Note

Springer Nature remains neutral with regard to jurisdictional claims in published maps and institutional affiliations.

Affiliations

1. Department of Earth and Planetary Science, University of Tokyo, Tokyo, Japan

   • Kunihiro Keika
   •  & Kanako Seki

2. Institute for Space-Earth Environmental Research, Nagoya University, Nagoya, Japan

   • Yoshizumi Miyoshi
   • , Shinobu Machida
   • , Akimasa Ieda
   • , Tomoaki Hori
   •  & Masafumi Shoji

3. Korea Astronomy and Space Science Institute, Daejeon, South Korea

   • Yukinaga Miyashita

4. Institute of Space and Astronautical Science (ISAS), Japan Aerospace Exploration Agency (JAXA), Sagamihara, Japan

   • Iku Shinohara

5. University of California, Los Angeles, CA, USA

   • Vassilis Angelopoulos
   •  & Aaron Flores

6. University of California, Berkeley, CA, USA

   • Jim W. Lewis

Corresponding author

Correspondence to Kunihiro Keika.

Reprints and Permissions