6. Visualization
As mentioned in section Code directory structure, PORTA comes with a visualization tool to help with visualization of the files used and generated by PORTA (PMD and PSP files, see section PORTA files).
6.1. Installing and executing PORTA GUI
PORTA GUI is programmed in Python, it is located in the directory tools/gui, and it does not require compilation, so it can be executed from the tools/gui directory by executing the following at the command line:
$ python portagui.py
6.1.1. Dependencies
PORTA GUI uses a number of Python packages that should be installed in your system:
sys, os, struct, numpy, scipy, FileDialog, matplotlib, ttk, Tkinter,
base64, subprocess, copy, pyvtk
Additionally, for the visualization of PMD files Mayavi needs to be installed in the system, callable as mayavi2.
There are many ways in which Python and the required dependencies can be installed. While Mayavi is not difficult to install, its dependencies are rather heavy, and installation is not always trouble free. Below, we illustrate how to use Python Virtual Environments to easily install all the required dependencies.
6.1.1.1. Sample installation of dependencies with Virtual Environments
Make sure the system meets the following requirements:
gcc compiler
Python version 3.4 or later (with modules Tk and venv installed)
Qt5
The following procedure has been tested with a fresh install in Ubuntu 18.04LTS.
Verify the above requirements are met by installing the following packages:
$ sudo apt-get install gcc python3 python3-dev python3-tk python3-venv qt5-default
Create the virtual environment with the necessary dependencies for the PORTA GUI. (In this example we name the virtual environment “portagui” and we are placing it inside the “tools/gui” directory, but you could name it differently and place it where it suits you best).
../tools/gui$ /usr/bin/python3 -m venv portagui
../tools/gui$ source portagui/bin/activate
(portagui) ../tools/gui$ python -m pip install --upgrade pip
(portagui) ../tools/gui$ python -m pip install mayavi PyQt5 scipy matplotlib pyvtk h5py
(portagui) ../tools/gui$ deactivate
Now whenever you want to use the PORTA GUI, you can activate (in the directory where you created it, here assuming tools/gui) the portagui environment and start the application as explained above:
../tools/gui$ source portagui/bin/activate
(portagui) ../tools/gui$ python portagui.py
When you have finished working with the PORTA gui, you can deactivate the virtual environment by just issuing the command:
(portagui) ../tools/gui$ deactivate
6.2. PORTA GUI main window
When running PORTA GUI (see section Installing and executing PORTA GUI), the following window pops up.
Fig. 6.1 Main PORTA GUI window
The four buttons have the following functions:
Visualize pmd files. This button opens the GUI for the visualization of the PORTA pmd files, that is, the files that contain the information about the model atmosphere and the self-consistent solution. See PMD Visualizer for details about its use.
Visualize psp files. This button opens the GUI for the visualization of the PORTA psp files, that is, the files that contain the emergent Stokes parameters of a formal solution. See PSP Visualizer for details about its use.
Settings. This button opens the GUI for the general settings of the GUI. See Settings for details about its use.
Close. This button closes the GUI.
6.3. Settings
The Settings window allows to change the following properties of the GUI:
Font size. Changes the font size of the text in the GUI. This option does not affect the data visualization.
Border color and thickness. The GUI can have several open windowssimultaneously. As a visual cue, the active one has a colored border. With this options we can change the color and thickness of this border.
Fig. 6.2 Settings window
6.4. PMD Visualizer
Pressing the Visualize pmd files button in the main window will pop up the following PMD view controller window.
Fig. 6.3 PMD view controller window
This window contains three sections: header, display, and control buttons.
The header manages the selection of a pmd file and contains two buttons:
Choose file, which opens a dialog to navigate the file system and select a pmd file. If the selected file is a compatible pmd file, it is accepted and the display is updated with the information in its header.
Remove. If a file has been chosen, then this button becomes active. This button drops the header information that has been previously loaded and cleans the display. Selecting a different pmd file will overwrite the display and remove the old header data from the GUI. Only one pmd file can be selected at a time.
The display shows the information of the header of the chosen file, if any. For example, the following figure shows the PMD view controller window with header information after choosing a PMD file.
Fig. 6.4 PMD view controller window with header information
Below the display there are two control buttons:
Module. This button becomes active when the user loads the header of a
pmd file and, upon pressing it, it opens the module visualization GUI (see section Module Visualization GUI). The module visualization GUI is module dependent, but its main components are similar for all modules.
Close. This button closes the pmd visualizer window and returns control
to the main window.
6.4.1. Module Visualization GUI
Note
As mentioned above, the Module Visualization GUI is module dependent. The figures and details in this section correspond to the multilevel module, but they would be quite similar for the other modules.
Upon pressing the Module button in the PMD view controller window, the Module Visualization GUI pops-up, similar to the following figure:
Fig. 6.5 Module Visualization GUI (multilevel module) - in the process of loading interpolated data for two of the PMD file variables.
This window contains six sections:
Load Manager. Contains the buttons to control the loading or unloading of the model data. Because the pmd files can be quite big in size, the model data is not loaded automatically.
Load loads the data for the variables specified in the section Variables to read (see below)
Unload button drops all loaded data.
Interpolation Manager. This section controls the interpolation parameters. Because the pmd files can be quite big, the GUI allows the user to interpolate the data into smaller regular grids. There are two ways of interpolating the data:
Interpolate the data wile is being loaded. This is attained by checking the box Interpolate data while reading. If the box is selected, the data will be interpolated while is being loaded, which can save memory, as the variables selected in the section Variables to read will be read plane by plane, and the unused data will be deprecated after use. If the box is not selected, the chosen variables will be read with their full resolution. Once the data have been read, this check box cannot be used anymore.
Interpolate already loaded data. After the data have been loaded, the Interpolate button becomes active. By pressing this button, the current loaded data (regardless of it being already interpolated or not) will be interpolated to the specified grid size.
The grid sizes of the interpolation are set through the entries between the check box and the button, and the set numbers are used for both types of interpolation.
Variables to read. This section contains an array of check boxes with all the variables that are contained in a PMD file for the corresponding module. When the user presses the Load button, this section becomes inactive and the selected variables are loaded from the file. Once a file is loaded, this section cannot be changed. In order to change the selection of variables the user must press the Unload button and reload the data with the new selection. There are three buttons to help reduce the number of clicks required:
Check all selects all variables
Uncheck all deselects all variables
Toggle all selects the unselected variables while selecting the unselected ones.
Display. This section (just below Variables to read), is a text display that shows information of the atom and transition lines of PMD file read, as well as the grid dimensions.
Progress bar. The rectangle below the Display is a progress bar that shows the completion degree during the loading and interpolation operations (Load and Interpolate buttons, respectively).
Buttons section. The bottom part of the GUI contains three buttons:
Plot. This button opens Mayavi and loads into it the data for the variables selected in Variables to read. The Plot button can only be pressed if there is something already loaded. A screenshot of Mayavi after loading some of the variables of a PMD file can be seen below.
Save vtk. This option will save the selected variables as individual VTK files, which can later be used with other software packages for further analysis or visualization. (As an example, we also show below a screenshot of using VisIt for the visualization of VTK saved data with this option).
Close. This button can only be used if there is no data currently loaded, and it just closes the module visualization GUI and returns the control to the PMD view controller window.
Fig. 6.6 Visualization of PMD loaded data with Mayavi
Fig. 6.7 Visualization of VTK saved files with VisIt
6.5. PSP Visualizer
Pressing the Visualize psp files button in the main window will pop up the following PSP view controller window.
Fig. 6.8 PSP view controller window
This window contains three sections: header, display, and control buttons.
The header manages the selection of psp files and contains several buttons, a drop-down menu and two status fields:
Choose new opens a dialog that lets the user navigate the file system and select a psp file. If the selected file is a valid psp file, it is accepted and added to the list of pre-selected files. The selection of the first file updates the display with the information of its header. Once at least one file has been selected, the rest of the buttons of the header become active.
Load all loads all the selected files in the list that are not loaded yet
Unload all unloads all the selected files in the list that are already loaded
Remove all removes from the selection list those files that are not loaded yet.
The third row contains the following widgets:
An option menu to select the file over which the rest of the buttons of the row will take action.
A label with the current status of the currently selected file: “Not Loaded” means that only the header information has been read, and this file will not appear for plotting, while “Loaded” means that the Stokes parameters have been read, and the file is ready for plotting. After using the Load button, this field shows “Loading” until the Stokes data is fully read. The reason why the Stokes data must be read manually is because the psp files can be quite big in size, and we want to avoid accidentaly loading data before checking the headers.
The Load button loads the Stokes information upon pressing, only active if the Stokes data is not read yet for the currently selected file.
The Unload button, that drops the Stokes information upon pressing, is only active if the Stokes data has been read for the currently selected file.
The Remove button drops the Stokes data (if loaded) and header of the currently selected file, and removes it from the list of pre-selected files.
The display shows the information of the header of the file currently selected in the drop down menu, if any. For example, the following figure shows the PSP view controller window with header information after choosing a PSP file.
Fig. 6.9 PSP view controller window with header information
Below the display there are several control buttons:
Three Plot buttons that open three different plotting windows. For details, see sections Plot XY, Plot Slit and Plot Profile.
Note
Some plots may require some dimensions of the Stokes data to be larger than one, i.e., the Plot XY requires more than one point in both spatial dimensions, Plot Slit requires more than one point in spectral and at least one of the spatial dimensions, and Plot Profile requires more than one point in the spectral dimension.
Close. This button closes the psp visualizer window and returns control to the main window.
6.5.1. Plot XY
Upon pressing the Plot XY button in the PSP view controller window, and if there is at least one file with two extended spatial dimensions loaded, a window to manage two-dimensional plots pops-up.
Fig. 6.10 Plot XY plotting window
The Plot XY window consists of several sections. From top to bottom, they are:
Plot Selection. This section contains two buttons to decrease or increase the number of plots (between 1 and 9) and an option menu to select the plot to edit. The properties shown in the rest of the sections correspond to the plot that is selected in this drop down menu.
File Selection. This section contains a drop down menu to select the file, between the valid loaded files, that will be drawn in the currently selected plot.
Variable Selection. This section manages the variable that will be plotted in the currently selected plot, and it has a number of fields:
The drop down menu Variable to plot lets the user choose this variable between a selection of Stokes parameters.
The Minimum and Maximum entry fields allow the user to manually specify the limits of the colorbar in the currently selected plot.
The Reset button resets the Minimum and Maximum fields of this section to the default quantities (calculated taking into account all the loaded files).
The Fit button finds the minimum and maximum for the specified Stokes parameter and file, and sets these values as minimum and maximum for the currently selected plot.
Wavelength Selection. This section allows choosing the frequency for which the two-dimensional plot will be shown in the currently selected plot.
The user can either type a numeric value in the entry field or move the slider to select a specific wavelength. If the user uses the entry field, the closest wavelength to the one written will be selected.
The Max P checkbox selects, for each spatial point, the wavelength for which the linear polarization degree \(P\) is maximum, and ignores the selected wavelength.
Spatial Range Selection. This section allows specifying the spatial range that will be plotted in the currently selected plot, for the selected file.
There are four entry fields with an associated slider, and the user can use any of the two to modify each of the quantities. If the user uses the entry field, the closest coordinate to the one written will be selected.
The Shrink check box toggles the shrinking of the horizontal dimension if the heliocentric angle of the observation is not zero.
Colormap Selection. This section contains a slider that allows the user to select the colormap to use for the currently selected plot. The selection contains all the standard matplotlib colormaps and an extra pair:
RedYellowBlue, the color table used in the total linear polarization figures in del Pino Alemán et al. (2018), and
SignAdjustable, the one used in the \(Q/I\) and \(U/I\) plots of the same paper. The SignAdjustable scale is defined such that the 0 value is always coloured in white.
Format Axis Selection. This section allows changing the font size of the title, as well as the format and font size of the color bar axis and the axis labels (both for the horizontal and vertical axis). This section consists of four subsections. The first one contains a checkbox and a pair of buttons to change the title font size. The remaining three subsections are identical, and each one contains:
an entry field to specify the format of the axis labels, to be specified in the Python way (e.g., %4.1f)
a checkbox to specify if a custom font size should be used, and
a pair of buttons to change the font size, enabled if the checkbox is toggled on.
Buttons. The bottom part of the GUI contains the following buttons:
Save Configuration. Allows the user to create a file to store the current configuration of the widget. This configuration file will not save the specific files that are loaded and used.
Load Configuration. Allows the user to select and load a configuration file created with the Save Configuration button. Because the configuration file does not store the psp files that are loaded, in order to reproduce a previous plot the user must load the same files in the same order before loading the configuration file.
Reset Configuration. Changes all the fields in this GUI window to the default values.
Draw. Opens a matplotlib canvas with the plot given by the configuration in this GUI window. The following figure shows a sample matplotlib canvas generated this way.
Close. Closes this window and returns the control to the main PSP view controller window.
Fig. 6.11 Plot XY matplotlib canvas
6.5.2. Plot Slit
Upon pressing the Plot Slit button in the PSP view controller window, and if there is at least one file with one extended spatial dimension and an extended wavelength dimension loaded, a window to manage slit plots pops-up.
Fig. 6.12 Plot Slit plotting window
The Plot Slit window consists of several sections. From top to bottom, they are:
Plot Selection. This section contains two buttons to decrease or increase the number of plots desired (between 1 and 9), and an option menu to select the plot to edit. The properties shown in the rest of the sections correspond to the plot that is selected in this drop down menu.
File Selection. This section contains a drop down menu to select the file, between the valid loaded files, that will be drawn in the currently selected plot.
Variable Selection. This section manages the variable that will be plotted in the currently selected plot, and it has a number of fields:
The drop down menu Variable to plot lets the user choose this variable between a selection of Stokes parameters.
The Minimum and Maximum entry fields allow the user to manually specify the limits of the colorbar in the currently selected plot.
The Reset button resets the Minimum and Maximum fields of this section to the default quantities (calculated taking into account all the loaded files).
The Fit button finds the minimum and maximum for the specified Stokes parameter and file, and sets these values as minimum and maximum for the currently selected plot.
Cut Axis Selection. This section allows choosing the axis in which to cut the two-dimensional spatial plane, and where to do it.
The option menu lets the user choose between the valid spatial axis (horizontal or vertical, or one of the two if one of the spatial dimensions has just one point).
Below the option menu, the user can either type a numeric value in the entry field or move the slider to select a specific spatial point. If the user uses the entry field, the closest spatial node to the one written will be selected.
2D Range Selection. This section allows specifying the wavelength (horizontal axis) and spatial (vertical axis) ranges that will be plotted in the currently selected plot, for the selected file.
There are four entry fields with an associated slider, and the user can use any of the two to modify each of the quantities. If the user uses the entry field, the closest coordinate to the one written will be selected.
The Shrink check box toggles the shrinking of the horizontal dimension if the heliocentric angle of the observation is not zero. In this type of plots, the shrinking only affects the values in the spatial (vertical) axis, not the actual aspect ratio of the plot.
Colormap Selection. This section contains a slider that allows the user to select the colormap to use for the currently selected plot. The selection contains all the standard matplotlib colormaps and an extra pair:
RedYellowBlue, the color table used in the total linear polarization figures in del Pino Alemán et al. (2018), and
SignAdjustable, the one used in the \(Q/I\) and \(U/I\) plots of the same paper. The SignAdjustable scale is defined such that the 0 value is always coloured in white.
Format Axis Selection. This section allows changing the font size of the title, as well as the format and font size of the color bar axis and the axis labels (both for the horizontal and vertical axis). This section consists of four subsections. The first one contains a checkbox and a pair of buttons to change the title font size. The remaining three subsections are identical, and each one contains:
an entry field to specify the format of the axis labels, to be specified in the Python way (e.g., %4.1f)
a checkbox to specify if a custom font size should be used, and
a pair of buttons to change the font size, enabled if the checkbox is toggled on.
Buttons. The bottom part of the GUI contains the following buttons:
Save Configuration. Allows the user to create a file to store the current configuration of the widget. This configuration file will not save the specific files that are loaded and used.
Load Configuration. Allows the user to select and load a configuration file created with the Save Configuration button. Because the configuration file does not store the psp files that are loaded, in order to reproduce a previous plot the user must load the same files in the same order before loading the configuration file.
Reset Configuration. Changes all the fields in this GUI window to the default values.
Draw. Opens a matplotlib canvas with the plot given by the configuration in this GUI window. The following figure shows a sample matplotlib canvas generated this way.
Close. Closes this window and returns the control to the main PSP view controller window.
Fig. 6.13 Plot Slit matplotlib canvas
6.5.3. Plot Profile
Upon pressing the Plot Profile button in the PSP view controller window, and if there is at least one file with an extended wavelength dimension loaded, a window to manage profile plots pops-up.
Fig. 6.14 Plot Profile plotting window
The Plot Profile window consists of several sections. From top to bottom, they are:
Plot Selection. This section contains two buttons to decrease or increase the number of plots desired (between 1 and 9), and an option menu to select the plot to edit. The properties shown in the rest of the sections correspond to the plot that is selected in this drop down menu.
File Selection. This section contains two parts:
The top part contains: buttons to allow the user select the number of curves that will be included in the currently selected plot; and a drop down menu to select the curve to edit.
The bottom part has an option menu to select the file to plot from for the currently selected plot and curve.
Variable Selection. This section manages the variable that will be plotted in the currently selected plot, and it has a number of fields:
The drop down menu Variable to plot lets the user choose this variable between a selection of Stokes parameters.
The Minimum and Maximum entry fields allow the user to manually specify the limits of the vertical axis in the currently selected plot.
The Reset button resets the Minimum and Maximum fields of this section to the default quantities (calculated taking into account all the loaded files).
The Fit button finds the minimum and maximum for the specified Stokes parameter and file, and sets these values as minimum and maximum for the currently selected plot.
Wavelength Limits. This section allows the user to choose the wavelength range (horizontal axis) of the plot. The user can either type a numeric value in the entry fields or move the sliders to select a specific spatial point for the minimum and maximum wavelengths to plot. If the user uses the entry fields, the closest wavelength in the loaded data to the one written will be selected.
2D Range Selection. This section has two different behaviours depending on the Single check box.
If Single is off, this section allows the user to specify the minimum and maximum spatial coordinates of a square in which all the profiles will be averaged for the currently selected plot and curve. There are four entry fields with an associated slider, and the user can use any of the two to modify each of the quantities. If the user uses the entry field, the closest coordinate to the one written will be selected.
If Single is on, this section allows the user to select a particular set of spatial coordinates for the currently selected plot and curve. The profile for this specific coordinate will be plotted. There are two entry fields with an associated slider, and the user can use any of the two to modify each of the quantities. If the user uses the entry field, the closest coordinate to the one written will be selected.
Color and Style Selection. This section contains two sliders that allow the user to select the colour and style to use for the currently curve and currently selected plot. The selection contains all the standard colours and three styles.
Format Axis Selection. This section allows changing the format and font size of the axis labels, both for the horizontal and vertical axis. This section consists of two identical subsections, one for each editable axis. Each subsection contains:
an entry field to specify the format of the axis labels, to be specified in the Python way (e.g., %4.1f)
a checkbox to specify if a custom font size should be used, and
a pair of buttons to change the font size, enabled if the checkbox is toggled on.
Buttons. The bottom part of the GUI contains the following buttons:
Save Configuration. Allows the user to create a file to store the current configuration of the widget. This configuration file will not save the specific files that are loaded and used.
Load Configuration. Allows the user to select and load a configuration file created with the Save Configuration button. Because the configuration file does not store the psp files that are loaded, in order to reproduce a previous plot the user must load the same files in the same order before loading the configuration file.
Reset Configuration. Changes all the fields in this GUI window to the defaults.
Draw. Opens a matplotlib canvas with the plot given by the configuration in this GUI window. The following figure shows a sample matplotlib canvas generated this way.
Close. Closes this window and returns the control to the main psp visualization widget.
Fig. 6.15 Plot Profile matplotlib canvas
Note
The sections Variable Selection, Wavelength Limits and Format Axis Selection affect all curves of the currently selected plot, while the sections Spatial Range Selection and Color and Style Selection affect the currently selected curve in the currently selected plot.