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

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.

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.

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.

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 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.

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.

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).

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.

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.