.. _examples-pyvisa: |pyvisa|: Visualization and analysis of path sampling results ============================================================= In this example, we become familiar with |pyvisa|. Every example on the website can be used to generate data for the analysis. |pyvisa| is composed of two units: a **compressor** tool and a **visualization** tool. The visualization tool requires the additional installation of the optional GUI requirements. Both units can be executed directly with the ``pyvisa`` command or used as a Python library. Here, we illustrate the command-line usage of the |pyvisa| components. Since clusters might not support GUIs or the related packages, the GUI requirements are **not** prerequisites for |pyretis| or command-line |pyvisa| use. To operate the |pyvisa| GUI visualizer, these packages must therefore be installed manually, for example with ``pip``. | **Verification status:** engine -- see :ref:`example-tutorial-map`. Tutorial quick start -------------------- * **Best starting point:** any completed path-sampling tutorial with an ``out.rst`` file; the GROMACS hydrate tutorial is a common example. * **Requirements:** PyQt5 is required only for the GUI visualizer, not for compression. * **Compress:** ``pyvisa -i out.rst -cmp``. * **Open the GUI:** ``pyvisa -i out.rst`` or ``pyvisa -i data.hdf5``. * **Expected output:** compressed ``.hdf5`` data and plots selected in the GUI. * **Related check:** :file:`examples/tests/test-pyvisa/`; see :ref:`example-test-status`. Compressor ---------- The **compressor** tool can be executed with: .. code-block:: pyretis pyvisa -i -cmp where ```` is the same ``.rst`` file used to execute the |pyretis| simulations. |pyvisa| will read, for each folder, the energy and the order parameter files. It will check the consistency and integrity of each file and discard corrupted data. The compressor tool will then generate ``pyvisa_compressed_data.hdf5.zip``, where all the input files are condensed, compressed, and organized to simplify the following post-processing operations. The compressor tool reports file inconsistencies, such as corrupted files or mismatched cycles. This situation might happen when the simulation data have been produced by multiple machines and/or by multiple independent runs. .. _fig_compressor: .. figure:: /_static/examples/pyvisa/fig_compressor.png :alt: Terminal output of the compressor tool :width: 80% :align: center A report on the reading and consistency check for each ensemble and for each file is provided by the compressor tool. The source files are not touched by this operation. If the data consistency is very low, a manual check is required before importing the data. | Remote/headless workflow ------------------------ On clusters or remote machines where the GUI is not available, run the compressor from the command line and move the compressed file to a machine with the GUI requirements installed: .. code-block:: pyretis pyvisa -i -cmp This creates ``pyvisa_compressed_data.hdf5.zip`` in the simulation directory. Copy that file to the local machine and open it with: .. code-block:: pyretis pyvisa -i pyvisa_compressed_data.hdf5.zip The same remote workflow can be used after recalculating order parameters or collective variables: .. code-block:: pyretis pyvisa -i -recalculate pyvisa -i -cmp For more details on remote use, direct GUI use, and the ``-data`` option, see :ref:`user-guide-pyvisa`. | Visualization ------------- The **visualization** tool can be executed with: .. code-block:: pyretis pyvisa -i where ```` can either be the ``.rst`` |pyretis| input file or the compressed file generated by the compressor tool, ``pyvisa_compressed_data.hdf5.zip`` by default. The |pyvisa| GUI has two main panels: :ref:`data ` and :ref:`plotting `. .. _fig_data_settings: .. figure:: /_static/examples/pyvisa/fig_data_settings.png :alt: PyVisA data selection panel :width: 60% :align: center Data panel: select the plotting type and data sub-set. The plot types are defined by: * Plot type: select the Matplotlib plot type and the number of dimensions to use. When plotting density maps, path weighting of accepted trajectories is an option. | Data sub-sets selection ----------------------- Data selection and manipulation criteria are: * x, y, z: list of order parameters, cycles and timesteps. Also, y, z allows the selection of the kinetic, potential, and total energy (kinetic+potential). * Folder: choose an ensemble number or select all of them. * Paths: accepted (``ACC``), rejected (``REJ``), or both (``BOTH``). See :ref:`user-guide-path-status-codes` for all status codes. * Cycles: select the minimum and maximum cycle number, where a cycle is a Monte Carlo move, i.e. a trajectory for each ensemble. * Data shift: shift the x-y data. This can be useful in the case of a cyclic order parameter such as an angle or dihedral. * Interfaces: toggle interface lines (2D plot) or planes (3D plot) It requires that x is the main order parameter (OP1). * Reg. line: plot a linear regression line and report its slope, intercept and r–squared values. * Resolution: number of pixels or grid–points to use for density, surface plot types. For scatter plots, it controls the dot size. | Plotting -------- .. _fig_plot_settings: .. figure:: /_static/examples/pyvisa/fig_plot_settings.png :alt: PyVisA plotting preferences panel :width: 60% :align: center Plotting panel: select the various plotting preferences. From the GUI, without reloading the data, it is possible to manipulate the picture. The options are: * Colormap: the colormaps to use for the plot. * xmin/xmax: minimum and maximum x–values in the plot. * ymin/ymax: minimum and maximum y–values in the plot. * Save: save the figure in a ``.png`` file. * Font size, Titles/Axes: the font size of plot titles and axis labels. * Show titles/labels: display the plot titles and axis labels. | Data handling ------------- Further options can be accessed from the drop-down panel labeled :ref:`**File** `. .. _fig_file: .. figure:: /_static/examples/pyvisa/fig_file.png :alt: PyVisA file operations :width: 60% :align: center A drop-down menu for file operations. The drop-down menu contains a few options: * Data Loading: reload the compressed simulation data. * Data Saving: save the simulation data, for example with the compressor tool, in ``.hdf5`` format. * Figure save: save the current data selection/picture. Several options are here available. To further facilitate data handling, |pyvisa| can save the selected data in very different ways. The idea is to minimize user efforts in data manipulation. In all the following selections, the file name is automatically generated to contain all the information for (manually) reconstructing the plot. The figure's data can be saved in: * Raw format: ``.txt`` file. Other visualization software can directly be used (e.g. xmgrace, gnuplot). * JSON format: ``.json`` file. This allows users to directly access the numbers corresponding to a plot and/or load them via the JSON package. The figure's object can be saved in: * ``.hdf5``: a versatile compressed format that can be loaded also by other programming languages (e.g. R). The figure itself can be saved as: * ``figure.png``: a ``.png`` file. * ``script.py``: a Python program is generated to reproduce the selected plot from the compressed data simply by typing ``python ``. A large variety of plots can thus be generated via |pyvisa|. The respective data can be saved in different formats to further facilitate post-processing and analysis in different programming languages. Tested by --------- The command-line compression and analysis helpers are represented by :file:`examples/tests/test-pyvisa/`. GUI behavior can depend on local Qt availability, so use the heavy check as the automated target and this page as the interactive guide.