- Technical report
- Open Access
Visualization tool for three-dimensional plasma velocity distributions (ISEE_3D) as a plug-in for SPEDAS
Earth, Planets and Space volume 69, Article number: 170 (2017)
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.
Examples of ISEE_3D
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.
Application to data from other missions
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.
Summary and future plans
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.
Data Archives and Transmission System
Exploration of energization and Radiation in Geospace
fast plasma investigation
hot plasma composition analyzer
Interactive Data Language
Institute of Space and Astronautical Science
Japan Aerospace Exploration Agency
Space Physics Environment Data Analysis Software
Time History of Events and Macroscale Interactions during Substorms
Anderson BJ, Erlandson RE, Zanetti LJ (1992) A statistical study of Pc 1–2 magnetic pulsations in the equatorial magnetosphere, 1. Equatorial occurrence distributions. J Geophys Res 97:3075–3088. https://doi.org/10.1029/91JA02706
Angelopoulos V (2009) The THEMIS mission. Springer, New York, pp 5–34
Barber CB, Dobkin DP, Huhdanpaa H (1996) The quickhull algorithm for convex hulls. ACM Trans Math Softw 22:469–483. https://doi.org/10.1145/235815.235821
Baumjohann W, Treumann RA (1997) Basic space plasma physics. Imperial College Press, London
Burch JL, Moore TE, Torbert RB, Giles BL (2015) Magnetospheric multiscale overview and science objectives. Space Sci Rev 199:5–21. https://doi.org/10.1007/s11214-015-0164-9
Burch JL et al (2016) Electron-scale measurements of magnetic reconnection in space. Science 352(6290):aaf2939. https://doi.org/10.1126/science.aaf2939
Chen L, Thorne RM, Jordanova VK et al (2011) Magnetosonic wave instability analysis for proton ring distributions observed by the LANL magnetospheric plasma analyzer. J Geophys Res 116:A03223. https://doi.org/10.1029/2010JA016068
Ebihara Y, Miyoshi Y (2011) Dynamic inner magnetosphere: a tutorial and recent advances. In: Liu W, Fujimoto M (eds) The dynamic magnetosphere. IAGA Special Sopron Book Series, vol 3. Springer, Dordrecht, pp 145–187
Ejiri M, Hoffman RA, Smith PH (1980) Energetic particle penetrations into the inner magnetosphere. J Geophys Res Space Phys (1978–2012) 85:653–663. https://doi.org/10.1029/JA085iA02p00653
Gosling JT, Thomsen MF, Bame SJ, Russell CT (1989) Suprathermal electrons at Earth’s bow shock. J Geophys Res 94(A8):10011–10025. https://doi.org/10.1029/JA094iA08p10011
Ieda A, Shue JH, Liou K et al (2003) Quiet time magnetotail plasma flow: coordinated polar ultraviolet images and Geotail observations. J Geophys Res Space Phys (1978–2012) 108:1345. https://doi.org/10.1029/2002ja009739
Kokubun S, Yamamoto T, Acuña MH (1994) The Geotail magnetic field experiment. J Geomagn Geoelectr 46:7–21
Mauk BH, Fox NJ, Kanekal SG et al (2012) Science objectives and rationale for the radiation belt storm probes mission. Space Sci Rev 179:3–27. https://doi.org/10.1007/s11214-012-9908-y
Miyoshi Y, Ono T, Takashima T et al (2012) The energization and Radiation in Geospace (ERG) Project. In: Summers D, Mann IR, Baker DN, Schulz M (eds) Dynamics of the Earth’s radiation belts and inner magnetosphere. American Geophysical Union, Washington. https://doi.org/10.1029/2012gm001304
Mukai T, Hirahara M, Machida S et al (1994a) Geotail observation of cold ion streams in the medium distance magnetotail lobe in the course of a substorm. Geophys Res Lett 21:1023–1026. https://doi.org/10.1029/93GL02424
Mukai T, Machida S, Saito Y, Hirahara M, Terasawa T, Kaya N, Obara T, Ejiri M, Nishida A (1994b) The low energy particle (LEP) experiment onboard the Geotail satellite. J Geomagn Geoelectr 46(8):669–692. https://doi.org/10.5636/jgg.46.669
Nagai T, Shinohara I, Fujimoto M, Matsuoka A, Saito Y, Mukai T (2011) Construction of magnetic reconnection in the near-Earth magnetotail with Geotail. J Geophys Res Space Phys. https://doi.org/10.1029/2010JA016283
Ng J, Egedal J, Le A, Daughton W (2012) Phase space structure of the electron diffusion region in reconnection with weak guide fields. Phys Plasmas 19(11):112108. https://doi.org/10.1063/1.4766895
Nishida A (1994) The Geotail mission. Geophys Res Lett 21:2871–2873. https://doi.org/10.1029/94GL01223
Oka M, Terasawa T, Saito Y, Mukai T (2005) Field-aligned beam observations at the quasi-perpendicular bow shock: generation and shock angle dependence. J Geophys Res Space Phys (1978–2012) 110:A05101. https://doi.org/10.1029/2004ja010688
Pollock C, Moore T, Jacques A et al (2016) Fast plasma investigation for magnetospheric multiscale. Space Sci Rev 199:331–406. https://doi.org/10.1007/s11214-016-0245-4
Roederer JG (1970) Dynamics of geomagnetically trapped radiation. Springer, Berlin
Russell CT, Anderson BJ, Baumjohann W et al (2016) The magnetospheric multiscale magnetometers. Space Sci Rev 199:189–256. https://doi.org/10.1007/s11214-014-0057-3
Saito Y, Mukai T, Hirahara M et al (1994) GEOTAIL observation of ring-shaped ion distribution functions in the plasma sheet-lobe boundary. Geophys Res Lett 21:2999–3002. https://doi.org/10.1029/94GL02099
Young et al (2016) Hot plasma composition analyzer for the magnetospheric multiscale mission. Space Sci Rev 199:407–470. https://doi.org/10.1007/s11214-014-0119-6
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.
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.
The authors declare that they have no competing interests.
Springer Nature remains neutral with regard to jurisdictional claims in published maps and institutional affiliations.
About this article
Cite this article
Keika, K., Miyoshi, Y., Machida, S. et al. Visualization tool for three-dimensional plasma velocity distributions (ISEE_3D) as a plug-in for SPEDAS. Earth Planets Space 69, 170 (2017). https://doi.org/10.1186/s40623-017-0761-9
- Velocity distributions of space plasma
- In situ measurements of space plasma
- Interactive visualization tool
- The ERG project